# v0.10.0-preview

统一错误目录：由项目集中定义逻辑标识、对外业务码、公开提示和 HTTP 状态，业务只选择错误。支持 HTTP 200 的业务失败，并贯通响应、错误函数生成、日志与 OpenAPI。

## 升级

```sh
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](README.md) 开始；目录/作用域/配置边界见 [错误目录](errors/README.md)；可直接生成的例子见 [errors.api](examples/contracts/errors.api)。

## 配置边界

生成路由的目录和响应以 `.api` 为准，优先于 App 默认配置；ByCode 需要当前目录中存在该标识。使用生成函数后仍须声明实际路由的 @errors，保持文档准确。不同路由可使用不同码类型与返回格式。

目录与响应模板分开，自定义 Encoder 继续控制最终 HTTP 状态和文本/XML 等协议。直接输出与已提交响应不会被再次包装。旧同标识 Codes/Messages 若与新目录冲突会明确拒绝。

访问日志记录实际提交状态，并带 failed/errorKey/可用的 businessCode。指标与链路识别 HTTP 200 业务失败；标准中间件和本地/共享幂等重放保留错误标识，旧缓存缺少标记时不补推历史状态。业务代码中的散落提示仍需业务项目按目录逐步迁移；本轮没有改写 eTax/ePay 业务逻辑。

## 验证入口

```sh
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。

本版结果见 [统一错误目录验收](performance/errorCatalogAcceptance.md)。

历史 Connector/HTTP 配置验收保留在 [v0.9.1 记录](performance/connectorAcceptance.md)，历史版本变化见 [CHANGELOG](CHANGELOG.md)。