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 键。
• 反复生成、手写代码保留、只读检查、递归字段变更诊断；请求绑定与原有生成消费者继续全量回归。

发布验收

三个独立空模块缓存安装固定远程 v0.28.2-preview，均无本地 replace，全部通过：

• 响应与兼容报告：101 项检查、11 组生成消费者，160.57 秒。包含强类型递归 HTTP、完整引用图、再生成和漂移检查，以及原有生命周期、上传、配置、错误和 i18n 回归。
• 通用工程报告：30 项检查，73.66 秒。
• 混合工作区报告：16 项检查，66.19 秒。

三次下载的框架 checksum 一致：h1:QjHXXV184SO45GCXLyejeVDdCzLa5EtRu2ngyYpLzYI=。代码与固定标签指向 0c5b571b31b68d25cdb3e8640970e2a53ddcbea6；远程验收记录另行提交，不移动标签。