go-omni/RELEASE.md

v0.9.0-preview

本版补齐已有 HTTP 项目的迁移接入能力：标准 Handler/Middleware 桥接、动态 JSON、路由级请求体限额与手写绑定、自定义标量转换。业务的响应格式、身份、资金事务和数据库实现仍由项目决定。

安装与升级

export GOPRIVATE=git.yuntuo.hk
go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.9.0-preview
# 在业务 module 中：
go get git.yuntuo.hk/k2safe/go-omni@v0.9.0-preview

将私有域名追加到已有 GOPRIVATE；凭据通过本机 Git 凭据管理器配置。CLI 与项目框架依赖一起升级。进入已生成的项目，再运行 go-omni api generate --dry-run、go-omni api generate、go test ./...。

本次变化

• httpx.WrapHandler、WrapMiddleware、WrapFuncMiddleware 将现有标准代码接入 App 中间件链。Raw 写入会记录真实状态和提交；已经输出的响应不再追加错误 JSON。下载/流式输出不整体缓存，保留底层支持的 HTTP 可选能力和取消信号。
• .api 的 any / interface{} 支持动态 JSON。数字保留为 json.Number，外围 DTO 严格校验不变。
• @body 按路由声明限额；内置 App 在全局中间件读取前限制 body。@binding custom、@handlerMode manual 生成保留的项目实现文件；上传、原文验签、下载可自行处理。@produces 描述手写成功输出的媒体类型。
• scalar 显式引用项目 Go 类型，调用标准 JSON/Text 方法；输入和输出各自生成 OpenAPI。普通基础类型不会自动放宽。

详见 迁移扩展指南、完整契约、运行示例 和 历史更新。

兼容与边界

原有 .api、公共响应配置和普通 Handler 可以继续使用。新生成代码最低运行时版本为本版。Raw() 现在返回跟踪包装器；直接断言某个具体 writer 类型的代码需改用标准接口/ResponseController。

标准中间件须保留 incoming request context 并同步调用 next；第三方框架私有的参数读取器仍由项目适配。手写 Handler/绑定 hook 初始返回 501；实现和文档一致性由项目负责，未实现不能上线。切换 manual 回自动模式时须显式迁移并移除对应手写文件，生成器不会删除它。

新增能力没有引入 Gin 或 go-zero 依赖。不是完整 goctl 语法兼容层，不代表任何业务项目已完成迁移。HTTP/2 仍为实验功能，本轮没有重新做 Linux 长测、代理验收或云存储账号实网验收。

验证入口

GO_OMNI_SCAFFOLD_INTEGRATION=1 go test -race -p=1 -count=1 -timeout=300s ./...
go vet ./...
go build ./...
python3 scripts/verifyCompatibilityRelease.py --version v0.9.0-preview \
  --report performance/compatibilityRemote.json

测试覆盖旧 Handler 404 与访问日志、提交后错误/panic、标准中间件状态/取消/提前写响应、nethttp/native 实际流式下载与请求体超限、multipart 临时文件清理、自定义标量精度/越界/nullable/集合，以及真实生成项目的验签与重生成保护。远程脚本从全新 module cache 安装 CLI，并检查生成项目的固定版本、校验和以及没有本地 replace。

本版封版验收通过：40 个包全量 race、独立 userService 回归，以及全新缓存的远程消费者验证。详见 完整验收记录。