go-omni/performance/errorCatalogAcceptance.md

v0.10.0-preview 统一错误目录验收

范围

项目定义错误目录，框架解析逻辑标识、HTTP 状态、对外业务码及公开提示；支持 HTTP 200 的业务失败，并贯通 .api 生成、响应、日志、指标、链路和错误重放。没有修改 eTax/ePay 业务代码，也没有使用业务服务器压测。

目录与响应模板分离；不同 App、路由可选择不同目录和协议。系统兜底不受 DefaultStatus 隐式影响，自定义 Encoder 继续控制最终输出。

本地回归

环境：go1.27.1 darwin/arm64。验收日期：2026-09-24。

• GO_OMNI_SCAFFOLD_INTEGRATION=1 go test -race -p=1 -count=1 -timeout=300s ./... 全部通过，包含实际生成并编译的脚手架/契约消费者。
• 全量之后增加配置快照隔离与 Encoder 包装策略测试，完成 go test -race -count=1 ./response ./config ./cmd/go-omni/apigen。
• 本地/共享幂等错误元数据补充用例通过 go test -race -count=1 ./app ./config ./httpx ./middleware/... ./metrics ./response ./telemetry。
• go vet ./...、go build ./...、gofmt、git diff --check 与 CLI 校验 examples/contracts/errors.api 通过。

专项覆盖

• 多 App 隔离、目录复制、配置快照隔离、静态配置变更要求重启；并发解析及 WithCause 不互相污染。
• JSON/YAML 精确 int64、字符串/整数类型与范围、重复 key、非法状态/字段/映射冲突拒绝。重复对外业务码允许保留独立提示。
• HTTP 200 业务失败、403 单项覆盖、未知标识 500、内部原因不进入默认公开响应、已提交响应不追加、文本 ACK 由自定义 Encoder 输出。
• RawJSON 成功不包装、失败保持错误响应；嵌套相同/空目录保留已有策略，不同目录叠加明确拒绝。
• 访问日志记录最终状态和业务失败；指标计入 HTTP 200 失败，链路保留状态与失败标记。标准中间件、本地/共享幂等重放保留失败语义。
• 多文件导入、多个目录和不同码类型的路由作用域；200 成功/失败 OpenAPI anyOf、多错误同码的独立示例。
• 实际生成项目的无参数错误函数、全局中间件提前返回时的路由目录、unknown fallback、raw 成功/失败、手写文件重生成保护。

验证边界

共享幂等新增用例使用 JSON 序列化的内存替身，验证字段在持久化边界上保留；未为本特性运行外部 Redis 服务。没有进行 Linux soak、代理长测或完整业务迁移验收。业务项目仍需升级框架/CLI，并逐步将散落错误改为目录调用。

远程固定版本验收

发布后两条独立远程验收均通过；各自从全新 module cache 安装远程 CLI，生成的消费者依赖固定版本，没有本地 replace。

• 发布标签：v0.10.0-preview；源码：ebfd279f9ada059bcb5d229e463759122b8a3669。
• module 校验和：h1:bbBDhMtp6ax+krphTGu9M1xnHGFORSg/ahFxWbEILyQ=，两条验收结果一致。
• 错误目录远程消费者：实际生成代码编译、HTTP 200 失败、同码不同提示、状态覆盖、未知标识兜底、cause 隔离、raw 输出、中间件提前返回、重生成保护与 race 测试通过；耗时 14.15 秒，详见 错误目录远程记录。
• 迁移兼容性消费者：标量转换、int64 精度、动态 JSON、原始请求体验签、路由体积限制、上传临时文件清理、下载及重生成保护通过；耗时 14.48 秒，详见 兼容性远程记录。
• 验收 fixture 哈希与当前文件一致；临时目录及缓存已清理。

结果在 main 单独追加，已发布标签保持不可变。