go-omni/RELEASE.md

v0.8.0-preview

这一版让业务自行定义公共返回体：在 .api 中配置字段、结构、成功/失败提示和错误码类型，按分组复用或由单接口覆盖，运行时与 OpenAPI 共用定义。需要特殊协议的回调可独立控制状态、Header 和内容。

本版继续作为预览版供固定版本接入；HTTP/2 仍是独立实验适配器。

安装与升级

GOPRIVATE=git.yuntuo.hk go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.8.0-preview

# 已有业务项目中执行：
GOPRIVATE=git.yuntuo.hk go get git.yuntuo.hk/k2safe/go-omni@v0.8.0-preview
go-omni api generate
go test ./...

新项目可以直接 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。

本版功能

• 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 同步模板结构与业务错误示例。

详见 公共响应体、完整定义示例 和 更新记录。

升级行为

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解析错误、连接级过载等发生在进入应用前的错误仍按网络协议处理。

验证入口

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，发布标签保持固定。详见 响应模板验收。OSS/R2 云账号实网验收与长时间压力测试不属于本次发布范围。