feat: release configurable API response contracts
Define reusable response bodies in .api with typed code mappings, per-route overrides and matching OpenAPI schemas. Add application and callback encoders, early response policy selection, and isolated remote-consumer release verification. Release v0.8.0-preview after full race, vet, build and local MySQL workflow acceptance.
This commit is contained in:
84
RELEASE.md
84
RELEASE.md
@@ -1,71 +1,55 @@
|
||||
# v0.7.0-preview.1
|
||||
# v0.8.0-preview
|
||||
|
||||
这一版完善接口开发体验：业务错误和鉴权可在 .api 中声明，代码调用与 OpenAPI 同步；增加路由总览、文档导出和无写入的生成预览。
|
||||
预览版用于固定版本试用；API 方言有明确范围，HTTP/2 仍是独立实验适配器。
|
||||
这一版让业务自行定义公共返回体：在 `.api` 中配置字段、结构、成功/失败提示和错误码类型，按分组复用或由单接口覆盖，运行时与 OpenAPI 共用定义。需要特殊协议的回调可独立控制状态、Header 和内容。
|
||||
|
||||
## 安装与开始
|
||||
本版继续作为预览版供固定版本接入；HTTP/2 仍是独立实验适配器。
|
||||
|
||||
## 安装与升级
|
||||
|
||||
```sh
|
||||
GOPRIVATE=git.yuntuo.hk go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.7.0-preview.1
|
||||
GOPRIVATE=git.yuntuo.hk go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.8.0-preview
|
||||
|
||||
go-omni api new --module example.com/demo ./demo
|
||||
cd demo
|
||||
GOPRIVATE=git.yuntuo.hk go mod tidy
|
||||
go run ./cmd/server
|
||||
# 已有业务项目中执行：
|
||||
GOPRIVATE=git.yuntuo.hk go get git.yuntuo.hk/k2safe/go-omni@v0.8.0-preview
|
||||
go-omni api generate
|
||||
go test ./...
|
||||
```
|
||||
|
||||
需要该 Git 仓库的读取权限时，通过自己的 Git 凭据管理器配置；不要将凭据写入 module path 或 go.mod。
|
||||
CLI 会将自身下载版本固定到生成项目的 go.mod。业务项目正常使用远程模块，不需要本地 replace。
|
||||
新项目可以直接 `go-omni api new --module example.com/demo ./demo`，或用 `go-omni new --api service.api --module example.com/demo ./demo`。远程安装的 CLI 会固定生成项目的框架版本，无需本地 replace。需要仓库权限时使用自己的 Git 凭据管理器，不把凭据写入 module path 或 go.mod。
|
||||
|
||||
使用已有定义，并一次选择基础模块：
|
||||
## 本版功能
|
||||
|
||||
```sh
|
||||
go-omni new --api user.api --module example.com/userService \
|
||||
--database mysql --storage local --log-output file ./userService
|
||||
```
|
||||
- `response Name (...)` 定义公共 JSON 体，支持嵌套结构、独立 errorBody、常量及类型保持的占位符；通过 import 共享配置。
|
||||
- `@server (response: Name)` 为整个 service 块选择模板，`@response Name` 单接口覆盖；`@response raw` 成功返回业务 JSON，错误保留组级格式。
|
||||
- `codeType: int32 / int64 / string` 使用与业务字段一致的名称；默认码和映射都校验，int64 配置及生成代码保留整数精度。旧 `integer` 写法仍兼容。
|
||||
- `successMessage` / `errorMessage` 配置默认提示，`codes` / `messages` 按逻辑错误码覆盖。业务只返回数据或错误，公共体由框架组装。
|
||||
- `omni.WithResponse` 设置手写路由的应用默认格式，`WithResponseEncoder` 与 `HandleWithResponse` 支持特殊协议；Text / XML / Bytes / JSON / NoContent 可直接输出。
|
||||
- 生成路由在全局中间件之前选定策略，提前鉴权拒绝、限流、panic 和 Context 克隆沿用正确格式。OpenAPI 同步模板结构与业务错误示例。
|
||||
|
||||
MySQL 与存储需要按生成 README 设置环境变量。任意契约生成的业务方法先返回 501，
|
||||
由业务方实现；可直接参考 [完整用户示例](examples/userService/README.md)。
|
||||
详见 [公共响应体](RESPONSE.md)、[完整定义示例](examples/contracts/responses.api) 和 [更新记录](CHANGELOG.md)。
|
||||
|
||||
## 主要变化
|
||||
## 升级行为
|
||||
|
||||
- `error (...)` + `@errors` 声明业务错误，生成 `apierrors.EmailTaken()` 等全新实例构造函数和错误码常量。
|
||||
- `auth Name (...)` + `@auth` 同步 OpenAPI security 与实际路由中间件，声明本身不替代凭证验证。
|
||||
- 多行 `@doc` 支持 description/tags/deprecated；一个状态可有多个业务错误示例。
|
||||
- 项目内直接 `api inspect`、`api export`、`api generate --dry-run`，无需重复指定入口文件。
|
||||
|
||||
此前 v0.7.0-preview 已提供：
|
||||
|
||||
- `.api` 生成项目、绑定/校验、路由、业务骨架和 OpenAPI；支持分组、导入、命名中间件。
|
||||
- 同一入口初始化 MySQL、日志、Local / S3 / R2 / OSS；标准 context 与 httpx 保持业务/网络分离。
|
||||
- 生成器保护手写业务文件，校验自有文件哈希，支持只读 --check；基础设施选项持久化到 manifest。
|
||||
- 完整用户示例包含数据库迁移、CRUD / 分页、事务审计、鉴权、文件导出与 requestId 日志。
|
||||
- 日志文件轮转/结构化脱敏、上传策略/直传/分片，以及此前 main 分支的通用业务模块一并提供。
|
||||
|
||||
所有变化及网络层验收记录见 [CHANGELOG](CHANGELOG.md)。
|
||||
|
||||
## 升级注意
|
||||
|
||||
1. 将 CLI 和项目框架依赖固定为相同版本。旧版 CRUD 项目继续使用现有目录；不能直接用 API 生成器接管已有 Go 目录。
|
||||
2. Gen.go 由生成器维护，业务实现/配置/迁移由项目维护。新增 API 后执行 generate 和 go test；修改或删除类型需要同步处理自己的业务代码。
|
||||
3. `.goOmni/apiManifest.json` 需随代码提交。切换数据库或存储选项时，在新目录生成对照后迁移；重新生成不会改写现有基础设施文件。
|
||||
4. 配置使用 lowerCamelCase。DSN、Token、存储密钥由环境变量提供；`database.Config` 的 DSN 不会被 JSON/YAML 序列化。
|
||||
5. 旧 `.api` 仍可解析。新语法需要本版 CLI；生成的错误函数沿用已有框架错误类型。旧 CLI 无法解析新增声明，请一起升级。鉴权引用的已有 hook 和业务函数仍保留，不会自动重写。
|
||||
6. API 的 none/memory 数据库选项仅表示不打开连接，不会从 HTTP DTO 自动推导内存仓库或数据表。
|
||||
1. CLI 与框架依赖一起升级到本版。新生成路由使用新的响应策略入口，旧运行时不能编译。旧 `.api` 可继续使用；生成器不会覆盖已有 Service、Repository、middleware、配置和 main。
|
||||
2. 生成接口以 `.api` 为响应契约来源，即使没有声明模板也固定使用默认格式；应用 YAML 的 response 用于手写路由和应用兜底。需要变更生成接口的格式，请修改 `.api` 后重新生成。
|
||||
3. `response.Response` DTO 保留为兼容类型，运行时不再依赖它固定结构。未配置的正常业务响应继续使用默认 code/message/data/requestId。
|
||||
4. 内置 App 的 404/405 现在经过应用响应策略和中间件，默认输出 JSON；原先依赖纯文本兜底的客户端需调整。直接使用 nethttp.Router 的兜底行为不变。
|
||||
5. `int32` / `int64` 按有符号整数范围校验并输出 JSON 数值；消费端需支持相应精度。需要文本码时使用 string。旧 integer 继续保留原有 ±(2^53−1) 范围。
|
||||
6. `.api` 的模板和 raw 当前描述 JSON。文本/XML回调用 Go 编码器并维护对应文档；TLS/HTTP解析错误、连接级过载等发生在进入应用前的错误仍按网络协议处理。
|
||||
|
||||
## 验证入口
|
||||
|
||||
```sh
|
||||
GO_OMNI_SCAFFOLD_INTEGRATION=1 go test -race -p=2 -count=1 -timeout=300s ./...
|
||||
GO_OMNI_SCAFFOLD_INTEGRATION=1 go test -race -p=1 -count=1 -timeout=300s ./...
|
||||
go vet ./...
|
||||
go build ./...
|
||||
python3 scripts/verifyAPIWorkflow.py --report performance/apiDeveloperExperienceLocal.json
|
||||
python3 scripts/verifyAPIWorkflow.py --version v0.7.0-preview.1 \
|
||||
--report performance/apiDeveloperExperienceRemote.json
|
||||
python3 scripts/verifyAPIWorkflow.py --report performance/responsePoliciesWorkflowLocal.json
|
||||
python3 scripts/verifyResponseRelease.py --version v0.8.0-preview \
|
||||
--report performance/responsePoliciesRemote.json
|
||||
python3 scripts/verifyAPIWorkflow.py --version v0.8.0-preview \
|
||||
--report performance/responsePoliciesWorkflowRemote.json
|
||||
```
|
||||
|
||||
最后一项在全新 module cache 安装远程 CLI，并验证无本地 replace 的项目生成、
|
||||
真实 MySQL、nethttp/native 启动与业务流程。容器只使用本机临时资源，结束时清理。
|
||||
本轮验收见 [接口开发体验报告](performance/apiDeveloperExperienceAcceptance.md)；此前业务闭环见 [API 业务验收](performance/apiWorkflowAcceptance.md)。
|
||||
远程验收分别从全新 module cache 安装 CLI，验证生成项目固定依赖且没有本地 replace，以及完整用户示例的真实 MySQL、nethttp/native、事务、日志和生命周期。数据库容器只使用本机临时资源（1 CPU / 768 MiB），结束清理，不连接业务服务器。
|
||||
|
||||
OSS/R2 云端仍需项目自己的账号做上线环境验收；当前云端适配器检查不等同于这些账号的实网测试。
|
||||
验收记录见 [响应模板验收](performance/responsePoliciesAcceptance.md)。OSS/R2 云账号实网验收与长时间压力测试不属于本次发布范围。
|
||||
|
||||
Reference in New Issue
Block a user