go-omni/reports/recursiveResponseAcceptance.md

v0.28.2 递归响应验收

范围：.api 响应 DTO 的自引用与相互引用，使用通用 Node/Branch/Leaf；不加入接入项目的业务字段或业务行为。非递归响应保持原生成路径，递归请求与非法值循环仍拒绝。

本地回归

2026-09-30，macOS arm64：

• GO_OMNI_SCAFFOLD_INTEGRATION=1 go test -race -count=1 ./...：56 个测试包通过，apigen 集成包 112.675 秒。
• GOTOOLCHAIN=go1.22.12 GO_OMNI_SCAFFOLD_INTEGRATION=1 go test -count=1 ./...：56 个测试包通过，apigen 集成包 91.536 秒。
• 新增生成文档断言后，重新运行专项 go test -race -count=1 ./cmd/go-omni/apigen -run Recursive（开启集成）：通过，4.318 秒。
• go vet ./...、go build ./...、git diff --check：通过。
• 示例通过实际 CLI 导出后，@apidevtools/swagger-cli@4.0.4 validate 确认完整 OpenAPI 3.0.3 文档有效。

覆盖内容

• 强类型三层树、递归 slice/map/pointer、可空对象、raw、数组根响应以及相互引用的有限值，生成消费者真实 HTTP 返回和 Go JSON 解码。
• $ref 目标完整、没有被忽略的引用同级属性、可空引用的 null 分支、循环引用不展开、文档压缩幂等。
• 跨源文件引用、声明顺序无关、直接值与引用混合的合法类型、scalar 输出 schema、字段约束、描述、精确 int64 示例。
• 有限递归示例、空集合、缺失/未知字段、深层非法值、异构数组错误、非法 null 与额外 JSON 值。
• 非法直接值循环、相互值循环、字段组合循环、递归请求及间接递归请求、未知类型、非法标签、重复字段、上传字段、双指针、固定数组和错误 map 键。
• 反复生成、手写代码保留、只读检查、递归字段变更诊断；请求绑定与原有生成消费者继续全量回归。

发布验收

远程验收使用 scripts/verifyManagedRelease.py；新增递归消费者与其他消费者一起用空模块缓存安装固定版本 CLI，并核对 module checksum 和无本地 replace。通用工程与混合工作区分别运行其原有发布验收脚本。结果在发布后记录。