61 lines
5.0 KiB
Markdown
61 lines
5.0 KiB
Markdown
# v0.22 显式配置引用验收（2026-09-26）
|
||
|
||
配置文件明确决定值的来源。框架只处理通用加载、类型绑定和安全诊断，不包含接入项目的字段、环境前缀或业务规则。
|
||
|
||
## 回归结果
|
||
|
||
- `GO_OMNI_SCAFFOLD_INTEGRATION=1 go test -race ./...`：48 个有测试的包通过，包含实际生成项目、错误目录、生命周期失败清理、上传下载、后台收尾和 copyx 回归。
|
||
- 生成模板最后调整后，CLI、apigen、scaffold 的实际消费者 race 复测通过。
|
||
- `go vet ./...`、`go build ./...` 通过。
|
||
- `GOTOOLCHAIN=go1.22.12 go test ./config ./database ./examples/configuration` 通过。
|
||
- managedService 的生成检查、race 与根目录构建通过；userService 的 race 通过。外部 MySQL 测试未配置时按原规则跳过。
|
||
- 三种格式示例分别运行默认值与显式 0/含特殊字符凭据；结果一致。类型错误非零退出，指出字段和环境名，未输出输入值。
|
||
|
||
| 场景 | 验证 |
|
||
| --- | --- |
|
||
| 固定值与 Default() | 不读取同名环境变量；文件缺失保留默认，显式 0/false/空字符串覆盖 |
|
||
| `${NAME}` / `${NAME:-fallback}` | 未设置与空值区分规则明确；必填失败不退回 Default，0/false/空格属于有效值 |
|
||
| 特殊字符与转义 | 冒号、`:-`、引号、换行、XML 字符、`${OTHER}` 原样保留；`$$` 转义，无二次展开 |
|
||
| YAML/JSON/XML/自定义 Decoder | 解码标量后解析引用，不替换文件源文本；同一绑定/验证流程 |
|
||
| 类型、null 与集合 | 按目标类型绑定，保留 int64 精度；不把环境文本隐式解析为对象、集合或 null |
|
||
| 失败诊断 | 文件、字段、环境名、可获取行列；类型/溢出/Validate 错误不输出值；相近未知字段给出建议 |
|
||
| 并发和默认值隔离 | 每次加载独立缓存，每个引用变量最多读取一次；24 个并发加载 race 通过 |
|
||
| 资源限制 | 文件和单值上限、总展开预算、深度/节点/引用上限、非法 UTF-8、恶意格式拒绝 |
|
||
| 生成维护边界 | 重复生成、dry-run/check 结果一致；业务配置和实现保留；main/loadGen 漂移拒绝 |
|
||
| `-check-config` | 使用同一 Load，成功退出 0；失败非零；不初始化依赖、不创建日志文件、不监听 |
|
||
| 单文件选择 | `-config` 选择一份，邻接 local/test 文件不自动叠加；空路径仅 Default |
|
||
| 删除旧模式 | env/envDefault 检出即提示迁移；不保留前缀、别名或隐式二次覆盖 |
|
||
|
||
`FuzzConfigurationReferences` 使用 4 worker、30 秒：284783 次执行，通过，总运行 31.445 秒（包含收尾）。另有确定性超限与格式安全测试；执行次数不代表形式化证明。
|
||
|
||
## 性能
|
||
|
||
Go 1.27.1、darwin/arm64、Apple M2 Max；同一实现、无 race、每场景三轮，benchtime=500ms。原始结果：[explicitConfigurationBenchmark.txt](explicitConfigurationBenchmark.txt)。
|
||
|
||
| 场景 | 中位数 | 典型分配 |
|
||
| --- | ---: | ---: |
|
||
| 小配置固定值：读文件＋解析＋绑定＋校验 | 24.932 µs | 10.24 KB / 123 allocs |
|
||
| 相同小配置带显式环境引用 | 25.420 µs | 11.12 KB / 133 allocs |
|
||
| 约 28 KB、1000 条目 JSON 解码＋绑定 | 2.390 ms | 2.40 MB / 31582 allocs |
|
||
|
||
小配置引用增加约 0.49 µs / 0.88 KB / 10 次分配；测量有波动，不承诺固定比例。配置只在启动/显式重新加载时执行，不进入业务请求路径。这是本机暖文件缓存测试，不是线上并发、冷磁盘或请求 QPS 测量。
|
||
|
||
## 迁移与范围
|
||
|
||
- 本版有意移除旧自动环境覆盖、标签、前缀/别名及数据库环境加载 API；完整清单见 [CONFIG.md](../CONFIG.md#v022-迁移旧模式已移除)。
|
||
- 配置文件里的其他 `${...}` 模板改写 `$${...}`；`.api` 响应模板不变。固定文件值不再被进程环境偷偷覆盖。
|
||
- XML 占位符使用普通叶元素或 type=string；显式 number/bool 表示文件常量。原有解析器的配置子集和安全限制保留。
|
||
- Decoder、Validate、自定义反序列化是可信 Go 扩展，项目负责其副作用与公开原因脱敏。
|
||
- 本轮没有修改接入项目业务代码，没有使用线上服务器压测，也没有连接业务数据库。框架回归不能代替项目升级后的实际部署配置和业务验收。
|
||
|
||
## 远程验收
|
||
|
||
`v0.22.0-preview` 标签固定在 `d598b2ebee8cde36859021e882a6bc1e0bb4fd4c`，空 module 缓存安装与远程依赖校验通过，无本地 replace。耗时 54.13 秒。
|
||
|
||
- 根目录 go run / build、nethttp/native 退出信号与端口释放通过。
|
||
- 8 组实际生成消费者 race 通过，覆盖配置引用/检查、生命周期失败清理、后台收尾、错误目录与动态提示、上传下载、copyx。
|
||
- 下载模块中的 config 包 race 与 httpc 包 race、HTTP 示例通过。
|
||
- 两服务共享错误目录、workspace 无写检查及重新生成业务文件保留通过。
|
||
|
||
完整机器记录含版本、checksum、检查清单和源码哈希：[explicitConfigurationRemote.json](explicitConfigurationRemote.json)。标签不随验收文档提交移动。
|