61 lines
5.0 KiB
Markdown
61 lines
5.0 KiB
Markdown
# v0.8.0-preview
|
||
|
||
这一版让业务自行定义公共返回体：在 `.api` 中配置字段、结构、成功/失败提示和错误码类型，按分组复用或由单接口覆盖，运行时与 OpenAPI 共用定义。需要特殊协议的回调可独立控制状态、Header 和内容。
|
||
|
||
本版继续作为预览版供固定版本接入；HTTP/2 仍是独立实验适配器。
|
||
|
||
## 安装与升级
|
||
|
||
首次接入请从 [README 接入指南](README.md) 开始，按新项目或已有项目选择步骤。下面是已接入项目的版本升级命令：
|
||
|
||
```sh
|
||
GOPRIVATE=git.yuntuo.hk go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.8.0-preview
|
||
|
||
# 在业务项目 go.mod 所在目录执行：
|
||
GOPRIVATE=git.yuntuo.hk go get git.yuntuo.hk/k2safe/go-omni@v0.8.0-preview
|
||
# 仅在已经由 .api 生成、具有 .goOmni/apiManifest.json 的项目中执行：
|
||
go-omni api generate
|
||
go test ./...
|
||
```
|
||
|
||
手写接口项目跳过 `api generate`，仍需执行业务测试。生成器不会自动接管其他框架创建的已有项目。
|
||
|
||
新项目可以直接 `go-omni api new --module example.com/demo ./demo`，或用 `go-omni new --api service.api --module example.com/demo ./demo`。在框架源码目录之外运行，远程安装的 CLI 会固定生成项目的框架版本，无需本地 replace；也可显式传 `--framework-version v0.8.0-preview` 固定远程依赖。需要仓库权限时使用自己的 Git 凭据管理器，不把凭据写入 module path 或 go.mod。
|
||
|
||
## 本版功能
|
||
|
||
- `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 同步模板结构与业务错误示例。
|
||
|
||
详见 [公共响应体](RESPONSE.md)、[完整定义示例](examples/contracts/responses.api) 和 [更新记录](CHANGELOG.md)。
|
||
|
||
## 升级行为
|
||
|
||
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=1 -count=1 -timeout=300s ./...
|
||
go vet ./...
|
||
go build ./...
|
||
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、事务、日志和生命周期。数据库容器只使用本机临时资源（1 CPU / 768 MiB），结束清理，不连接业务服务器。
|
||
|
||
封版验证完成：40 个包全量 race 通过；全新缓存安装的远程 CLI/框架、公共模板消费者及 nethttp/native 的 34 项业务检查通过，无本地 replace。验收工具和最终记录维护在 main，发布标签保持固定。详见 [响应模板验收](performance/responsePoliciesAcceptance.md)。OSS/R2 云账号实网验收与长时间压力测试不属于本次发布范围。
|