feat: add project-owned error catalogs and HTTP 200 failure contracts
This commit is contained in:
51
RELEASE.md
51
RELEASE.md
@@ -1,31 +1,38 @@
|
||||
# v0.9.1-preview
|
||||
# v0.10.0-preview
|
||||
|
||||
本版补齐已有项目接入的两个框架缺口：标准数据库 Connector 注入，以及应用级 HTTP 读写超时配置。TLS、数据库驱动日志、字符集/时区、迁移与业务规则继续由项目决定。
|
||||
统一错误目录：由项目集中定义逻辑标识、对外业务码、公开提示和 HTTP 状态，业务只选择错误。支持 HTTP 200 的业务失败，并贯通响应、错误函数生成、日志与 OpenAPI。
|
||||
|
||||
## 安装与升级
|
||||
## 升级
|
||||
|
||||
```sh
|
||||
go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.9.1-preview
|
||||
# 在各业务 module 中：
|
||||
go get git.yuntuo.hk/k2safe/go-omni@v0.9.1-preview
|
||||
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 ./...
|
||||
```
|
||||
|
||||
私有仓库使用本机 Git 凭据管理器，并将 `git.yuntuo.hk` 追加到已有 `GOPRIVATE`。CLI 和项目依赖使用同一固定版本。v0.9.0-preview 生成代码继续兼容，本次无需为了这两个入口重新生成接口。
|
||||
先升级项目依赖，再使用同版 CLI。新生成代码最低运行时为本版；旧的 APIError/New/BadRequest、Codes/Messages、error 声明及旧生成代码继续支持。API 错误包增加 `Catalog()`，该名称成为保留符号。项目的手写 main、Service 和 Repository 不被重生成覆盖。
|
||||
|
||||
## 接入变化
|
||||
## 接入
|
||||
|
||||
- 将项目已有 `sql.OpenDB(connector)` 的池创建替换为 `database.OpenConnector(ctx, connector, poolConfig)`；不要同时保留两个池。返回对象可用于 Health/InTx；需要标准库指针时取 `.DB`。
|
||||
- 项目原有 `mysql.NewConnector`、独立 TLS、driver Logger、驱动读写时限、MySQL 版本/时区/排序规则校验继续保留，配置不进入核心框架。
|
||||
- 将原来逐项修改 `http.Server` 的读写/空闲/头大小配置放入 `omni.HTTPConfig`，通过 `WithHTTPConfig` 或 `WithConfig` 传入。Go-only `ErrorLog` 支持 nethttp。
|
||||
- 原有 `database.Open(ctx, Config)`、手动组装 `http.Server`、自定义 Runner 均可继续使用。零 HTTP 配置保留所选网络层已有默认行为；正值覆盖，负值报错。
|
||||
- 手写项目：`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。
|
||||
|
||||
完整可复制示例：[数据库 Connector](database/README.md#connector-接入v091-preview)、[HTTP 配置及语义](transport/README.md#http-配置v091-preview)。其他迁移能力见 [迁移扩展指南](MIGRATION.md)，从项目接入开始见 [README](README.md)。
|
||||
完整接入从 [README](README.md) 开始；目录/作用域/配置边界见 [错误目录](errors/README.md)；可直接生成的例子见 [errors.api](examples/contracts/errors.api)。
|
||||
|
||||
## 边界
|
||||
## 配置边界
|
||||
|
||||
独立实验性 `TransportHTTP2` 本次支持 IdleTimeout/MaxHeaderBytes 的配置透传，但不支持读头、读请求和写响应超时，设置这些正值会在监听前明确报错。native 与标准库服务器的超时含义不完全相同，详见上表；网络超时不等于 Handler 执行时间限制。`RunWith` 自定义 Runner 的配置由项目管理。
|
||||
生成路由的目录和响应以 `.api` 为准，优先于 App 默认配置；ByCode 需要当前目录中存在该标识。使用生成函数后仍须声明实际路由的 @errors，保持文档准确。不同路由可使用不同码类型与返回格式。
|
||||
|
||||
Connector 必须遵守驱动 context 协议，资源所有权按标准 `database/sql` 管理。有资源的 Connector 不跨池共享；启动 Ping 失败关闭池，成功后应用负责关闭。没有把 eTax/ePay 的数据库策略写进框架，也未修改这些业务项目或宣称它们已完成迁移。
|
||||
目录与响应模板分开，自定义 Encoder 继续控制最终 HTTP 状态和文本/XML 等协议。直接输出与已提交响应不会被再次包装。旧同标识 Codes/Messages 若与新目录冲突会明确拒绝。
|
||||
|
||||
访问日志记录实际提交状态，并带 failed/errorKey/可用的 businessCode。指标与链路识别 HTTP 200 业务失败；标准中间件和本地/共享幂等重放保留错误标识，旧缓存缺少标记时不补推历史状态。业务代码中的散落提示仍需业务项目按目录逐步迁移；本轮没有改写 eTax/ePay 业务逻辑。
|
||||
|
||||
## 验证入口
|
||||
|
||||
@@ -33,13 +40,13 @@ Connector 必须遵守驱动 context 协议，资源所有权按标准 `database
|
||||
GO_OMNI_SCAFFOLD_INTEGRATION=1 go test -race -p=1 -count=1 -timeout=300s ./...
|
||||
go vet ./...
|
||||
go build ./...
|
||||
python3 scripts/verifyConnector.py --local --report performance/connectorLocal.json
|
||||
python3 scripts/verifyConnector.py --version v0.9.1-preview --report performance/connectorRemote.json
|
||||
python3 scripts/verifyCompatibilityRelease.py --version v0.9.1-preview --report performance/connectorCompatibilityRemote.json
|
||||
python3 scripts/verifyErrorCatalogRelease.py --version v0.10.0-preview
|
||||
python3 scripts/verifyCompatibilityRelease.py --version v0.10.0-preview \
|
||||
--report performance/errorCatalogCompatibilityRemote.json
|
||||
```
|
||||
|
||||
Connector 脚本只使用本地独立 MySQL 8.4 容器，限制 1 CPU、768 MiB、128 PID，生成一次性 CA/证书及凭据，结束清理自己的容器/卷/临时文件。测试验证正确 TLS、错误 CA/主机名拒绝、每池时区/日志配置隔离、事务、关闭与失败回收。HTTP 测试使用回环地址验证慢头、慢 body、空闲连接、流式写背压及请求头上限。常规单测不依赖 Docker，显式脚本要求真实 TLS 测试通过，不能跳过。
|
||||
测试覆盖多 App 隔离、并发原因隔离、精确 int64、重复/非法定义拒绝、200 失败与 403 覆盖、未知错误兜底、已提交响应不追加、文本回执、访问日志、指标/链路、标准桥接、本地与序列化共享幂等存储，以及真实生成项目的 early middleware、raw 输出和重生成保护。远程脚本从全新缓存安装 CLI，检查固定版本、模块校验和与没有本地 replace。
|
||||
|
||||
历史发布及验收记录保留在 [CHANGELOG](CHANGELOG.md)、[v0.9.0 接入验收](performance/compatibilityAcceptance.md)。
|
||||
本版结果见 [统一错误目录验收](performance/errorCatalogAcceptance.md)。
|
||||
|
||||
全量 race（40 个测试包）、静态检查、构建、本地隔离验收及全新缓存远程消费者/CLI 验收已通过，详见 [验收记录](performance/connectorAcceptance.md)。
|
||||
历史 Connector/HTTP 配置验收保留在 [v0.9.1 记录](performance/connectorAcceptance.md)，历史版本变化见 [CHANGELOG](CHANGELOG.md)。
|
||||
|
||||
Reference in New Issue
Block a user