62 lines
4.4 KiB
Markdown
62 lines
4.4 KiB
Markdown
# 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](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](configurationRemote.json)，本轮耗时 50.24 秒。标签不因补充验收记录移动；记录随后提交到 main。
|
||
|
||
完整使用与迁移：[CONFIG.md](../CONFIG.md)。
|