go-omni/reports/configurationAcceptance.md

v0.20 统一配置加载验收（2026-09-26）

本轮修改 go-omni 配置包、生成模板与文档。没有修改接入项目的业务配置/数据库，也没有使用线上服务器做压力测试。

回归结果

• 全量 GO_OMNI_SCAFFOLD_INTEGRATION=1 go test -race ./...：47 个有测试的包通过，包含实际生成项目、生命周期失败清理、错误目录/响应继承、上传和拷贝工具回归。
• go vet ./...、go build ./... 通过。
• GOTOOLCHAIN=go1.22.12 go test ./config ./examples/configuration 通过。
• 新生成消费者的 go test -race ./...、go build .、generate/check/dry-run 通过。
• checked-in managedService 已显式迁移旧 Load，生成检查、race 和构建通过；三种格式示例与环境覆盖命令实际运行通过。

针对性验证：

场景	结果
JSON / YAML / XML 的 defaults→file→env→Validate	同值，0/false 可覆盖，envDefault 不覆盖文件
大于 2^53 的整数、动态 json.Number	精度保留
null、空数组、嵌套指针、map、duration、TextUnmarshaler、JSON tag / 嵌入字段	语义回归通过
文件字段类型错、未知字段、重复字段、业务 Validate 失败	文件/字段/可用行列与安全原因
环境类型或校验失败、集合子字段校验	定位环境来源，不错误归因于文件
内部错误链和默认值隔离	errors.Is/As 可用，失败不提交半成品/修改默认值
24 个并发加载、自定义 Decoder、禁止事后注册	race 通过，实例间不泄漏
超大文件、超深输入、重复 XML 根、DTD/entity、YAML alias/merge、UTF-8	拒绝；解析器 panic 不公开 panic 内容
业务新增字段与自定义格式	不改 main/loadGen，生成保留手写文件
配置校验失败	依赖初始化之前返回；未触发测试中的 Init panic
旧手写 Load、loadGen 漂移	generate/check/dry-run 拒绝冲突，不改业务文件

30 秒、4 worker 的 FuzzConfigurationDecoders：383586 次执行，无失败（总运行 31.309 秒，包含停止收尾）。模糊输入上限 8 KiB；另有确定性 1 MiB/深度上限和恶意格式回归，不把 fuzz 次数当作形式证明。

性能

Go 1.27.1、darwin/arm64、Apple M2 Max；无 race 的本地基准，每个场景三轮。原始数据：configurationBenchmark.txt。

场景	中位数耗时	典型分配
小配置 JSON 解析＋绑定	5.068 µs	3781 B / 75 allocs
小配置 YAML 解析＋绑定	14.855 µs	15602 B / 181 allocs
小配置 XML 解析＋绑定	7.137 µs	5605 B / 122 allocs
含完整 Server 默认值：文件读取＋环境覆盖＋校验	107.660 µs	约 67.4 KB / 1288 allocs
1000 个条目，约 28 KB JSON 解析＋绑定	2.548 ms	约 2.40 MB / 31585 allocs

配置在启动阶段加载，不经过业务请求路径。这些是暖文件缓存、本机测试结果，不能等同冷磁盘启动耗时、请求 QPS 或跨机器性能承诺。没有为此引入全局反射缓存、解析器池或后台线程。

边界与迁移

• 旧手写 Load 必须先明确迁移，生成器不会猜测其解密/其他特殊行为。
• 内置 XML 是明确的配置子集；YAML alias/merge/custom tag 拒绝；固定 Go 数组严格长度。
• 自定义 Decoder/反序列化/Validate 是可信 Go 回调，其并发、副作用与公开 Reason 的脱敏由项目负责。
• 第三方非结构化验证错误仅定位子树，并保留内部原因；业务用 Invalid/AtField 提供准确的公开字段与原因。
• 未进行业务数据库/第三方真实依赖验收，未修改或替代各接入项目的业务回归。

远程发布验收

v0.20.0-preview 标签固定在 c60841f901a3bcc3e9582eece6cfb2cad008fb9e。空 module 缓存安装已发布 CLI；生成消费者引用相同远程 module 和 checksum，没有本地 replace。

根目录 go run . / 构建、nethttp/native 退出信号与端口释放、上传下载/原始回调、两服务共享错误目录，以及 8 组消费者 race 回归全部通过。新消费者验证 JSON/YAML/XML/自定义扩展、环境来源、初始化前验证、业务文件保留与 loadGen 漂移检查。

完整机器记录：configurationRemote.json，本轮耗时 50.24 秒。标签不因补充验收记录移动；记录随后提交到 main。

完整使用与迁移：CONFIG.md。