3.8 KiB
v0.10.0-preview
统一错误目录：由项目集中定义逻辑标识、对外业务码、公开提示和 HTTP 状态，业务只选择错误。支持 HTTP 200 的业务失败，并贯通响应、错误函数生成、日志与 OpenAPI。
升级
go get git.yuntuo.hk/k2safe/go-omni@v0.10.0-preview
go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.10.0-preview
# 使用 .api 的项目再执行：
go-omni api generate --dry-run
go-omni api generate
go test ./...
先升级项目依赖，再使用同版 CLI。新生成代码最低运行时为本版；旧的 APIError/New/BadRequest、Codes/Messages、error 声明及旧生成代码继续支持。API 错误包增加 Catalog()，该名称成为保留符号。项目的手写 main、Service 和 Repository 不被重生成覆盖。
接入
- 手写项目：
omni.New(omni.WithErrors(catalog), omni.WithResponse(responseConfig))，业务返回omnierrors.ByCode(key)，按需.WithCause(err)。 - 契约项目：
.api errorCatalog定义一次，路由@errors或@server errors引用，生成apierrors.UsernameInvalid()等函数、Catalog、路由策略及 OpenAPI。 - 项目目录的
defaultStatus可以设为 200，单条错误可设置 403、409 等；默认只作用于目录条目，不改变未配置系统错误的兜底。 - 逻辑标识必须唯一，对外业务码可以重复，支持字符串/int32/int64；整数精度与所选响应类型在加载/编译时校验。
- HTTP 200 失败使用错误响应模板，OpenAPI 的 200 使用 anyOf 保留成功 DTO 和错误体；同码错误保留不同示例。
- App 和路由目录隔离、初始化复制；每次生成/解析错误都返回独立对象。未知标识转系统兜底，默认公开响应不暴露 cause。
完整接入从 README 开始；目录/作用域/配置边界见 错误目录；可直接生成的例子见 errors.api。
配置边界
生成路由的目录和响应以 .api 为准，优先于 App 默认配置；ByCode 需要当前目录中存在该标识。使用生成函数后仍须声明实际路由的 @errors，保持文档准确。不同路由可使用不同码类型与返回格式。
目录与响应模板分开，自定义 Encoder 继续控制最终 HTTP 状态和文本/XML 等协议。直接输出与已提交响应不会被再次包装。旧同标识 Codes/Messages 若与新目录冲突会明确拒绝。
访问日志记录实际提交状态，并带 failed/errorKey/可用的 businessCode。指标与链路识别 HTTP 200 业务失败；标准中间件和本地/共享幂等重放保留错误标识，旧缓存缺少标记时不补推历史状态。业务代码中的散落提示仍需业务项目按目录逐步迁移；本轮没有改写 eTax/ePay 业务逻辑。
验证入口
GO_OMNI_SCAFFOLD_INTEGRATION=1 go test -race -p=1 -count=1 -timeout=300s ./...
go vet ./...
go build ./...
python3 scripts/verifyErrorCatalogRelease.py --version v0.10.0-preview
python3 scripts/verifyCompatibilityRelease.py --version v0.10.0-preview \
--report performance/errorCatalogCompatibilityRemote.json
测试覆盖多 App 隔离、并发原因隔离、精确 int64、重复/非法定义拒绝、200 失败与 403 覆盖、未知错误兜底、已提交响应不追加、文本回执、访问日志、指标/链路、标准桥接、本地与序列化共享幂等存储，以及真实生成项目的 early middleware、raw 输出和重生成保护。远程脚本从全新缓存安装 CLI，检查固定版本、模块校验和与没有本地 replace。
本版结果见 统一错误目录验收。