# v0.11.0-preview

错误目录支持提示模板和有序类型参数。业务调用 `apierrors.TextTooLong("企业名称", 100)`，错误目录统一定义业务码、HTTP 状态与文案，运行时入口和生成函数共用解析逻辑。

## 升级与接入

```sh
go get git.yuntuo.hk/k2safe/go-omni@v0.11.0-preview
go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.11.0-preview
go-omni api generate --dry-run
go-omni api generate
go test ./...
```

先升级依赖，再使用同版 CLI。新生成代码最低要求本版；已有固定错误、v0.10.0 目录、无参数函数和旧生成代码继续支持。模板错误一旦声明参数，修改其顺序/类型会改变生成函数签名，项目需同步修改调用方。手写文件仍受重生成保护。

从 [README](README.md) 接入，完整规则见 [错误目录与模板参数](errors/README.md)，可直接生成的契约见 [errorParams.api](examples/contracts/errorParams.api)。

## 能力与边界

- 有序 `params` 决定函数参数顺序；支持 string/bool/int/int32/int64/float64。目录初始化检查模板、占位符、参数类型与文档 example。
- `ByCode(key).WithParams(values)` 复制标量参数；生成函数立即解析完整 Message，非 HTTP 使用显式 Registry，不引入全局注册器。
- HTTP 200 或逐项覆盖的状态、返回体模板、data:null、RawJSON 及自定义 Encoder 保持项目配置。内部 cause 不自动进入公开提示。
- 运行时缺参、多参、类型/范围错误转系统兜底，日志包含 ParamError 诊断；不发送未替换的模板或原始参数值。
- 路由、中间件和 Context 克隆保留参数。幂等重放保存已解析公开快照，目录更新不覆盖历史响应；不保存原始参数/cause，大整数码不经浮点转换。
- OpenAPI 保留模板参数定义，响应 examples 显示具体提示。文档 example 不作为运行时缺参默认值。
- 省略 params 的旧固定提示保留字面花括号；空 params 数组明确拒绝。模板错误同标识旧 messages 映射需移除。
- 本轮没有修改 eTax/ePay 业务代码；业务侧需升级版本并声明自己的通用校验错误。

## 验证入口

```sh
GO_OMNI_SCAFFOLD_INTEGRATION=1 go test -race -p=1 -count=1 -timeout=300s ./...
go vet ./...
go build ./...
# 使用已有 redis:7-alpine 镜像启动本机有资源限制的临时容器：
python3 scripts/verifyErrorParamsRedis.py
# 发布后的远程固定版本消费者：
python3 scripts/verifyErrorParamsRelease.py --version v0.11.0-preview
python3 scripts/verifyErrorCatalogRelease.py --version v0.11.0-preview --report performance/errorParamsCatalogRemote.json
python3 scripts/verifyCompatibilityRelease.py --version v0.11.0-preview --report performance/errorParamsCompatibilityRemote.json
```

验收结果见 [提示模板验收](performance/errorParamsAcceptance.md)。历史 [v0.10.0 错误目录验收](performance/errorCatalogAcceptance.md) 保留。