# 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 扩展，项目负责其副作用与公开原因脱敏。
- 本轮没有修改接入项目业务代码，没有使用线上服务器压测，也没有连接业务数据库。框架回归不能代替项目升级后的实际部署配置和业务验收。

## 远程验收

发布后使用空 module 缓存安装固定版本，验证无本地 replace 的生成、编译、退出、配置及消费者回归。具体版本、校验和、检查清单与源码哈希写入远程验收记录。