feat: add HTTP migration bridges and extensible API binding
This commit is contained in:
59
RELEASE.md
59
RELEASE.md
@@ -1,46 +1,34 @@
|
||||
# v0.8.0-preview
|
||||
# v0.9.0-preview
|
||||
|
||||
这一版让业务自行定义公共返回体：在 `.api` 中配置字段、结构、成功/失败提示和错误码类型，按分组复用或由单接口覆盖，运行时与 OpenAPI 共用定义。需要特殊协议的回调可独立控制状态、Header 和内容。
|
||||
|
||||
本版继续作为预览版供固定版本接入；HTTP/2 仍是独立实验适配器。
|
||||
本版补齐已有 HTTP 项目的迁移接入能力：标准 Handler/Middleware 桥接、动态 JSON、路由级请求体限额与手写绑定、自定义标量转换。业务的响应格式、身份、资金事务和数据库实现仍由项目决定。
|
||||
|
||||
## 安装与升级
|
||||
|
||||
首次接入请从 [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 ./...
|
||||
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
|
||||
```
|
||||
|
||||
手写接口项目跳过 `api generate`，仍需执行业务测试。生成器不会自动接管其他框架创建的已有项目。
|
||||
将私有域名追加到已有 GOPRIVATE；凭据通过本机 Git 凭据管理器配置。CLI 与项目框架依赖一起升级。进入已生成的项目，再运行 `go-omni api generate --dry-run`、`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；也可显式传 `--framework-version v0.8.0-preview` 固定远程依赖。需要仓库权限时使用自己的 Git 凭据管理器，不把凭据写入 module path 或 go.mod。
|
||||
## 本次变化
|
||||
|
||||
## 本版功能
|
||||
- `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。普通基础类型不会自动放宽。
|
||||
|
||||
- `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 同步模板结构与业务错误示例。
|
||||
详见 [迁移扩展指南](MIGRATION.md)、[完整契约](examples/contracts/compatibility.api)、[运行示例](examples/compatibility/main.go) 和 [历史更新](CHANGELOG.md)。
|
||||
|
||||
详见 [公共响应体](RESPONSE.md)、[完整定义示例](examples/contracts/responses.api) 和 [更新记录](CHANGELOG.md)。
|
||||
## 兼容与边界
|
||||
|
||||
## 升级行为
|
||||
原有 `.api`、公共响应配置和普通 Handler 可以继续使用。新生成代码最低运行时版本为本版。`Raw()` 现在返回跟踪包装器；直接断言某个具体 writer 类型的代码需改用标准接口/ResponseController。
|
||||
|
||||
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解析错误、连接级过载等发生在进入应用前的错误仍按网络协议处理。
|
||||
标准中间件须保留 incoming request context 并同步调用 next；第三方框架私有的参数读取器仍由项目适配。手写 Handler/绑定 hook 初始返回 501；实现和文档一致性由项目负责，未实现不能上线。切换 manual 回自动模式时须显式迁移并移除对应手写文件，生成器不会删除它。
|
||||
|
||||
新增能力没有引入 Gin 或 go-zero 依赖。不是完整 goctl 语法兼容层，不代表任何业务项目已完成迁移。HTTP/2 仍为实验功能，本轮没有重新做 Linux 长测、代理验收或云存储账号实网验收。
|
||||
|
||||
## 验证入口
|
||||
|
||||
@@ -48,13 +36,8 @@ go test ./...
|
||||
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
|
||||
python3 scripts/verifyCompatibilityRelease.py --version v0.9.0-preview \
|
||||
--report performance/compatibilityRemote.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 云账号实网验收与长时间压力测试不属于本次发布范围。
|
||||
测试覆盖旧 Handler 404 与访问日志、提交后错误/panic、标准中间件状态/取消/提前写响应、nethttp/native 实际流式下载与请求体超限、multipart 临时文件清理、自定义标量精度/越界/nullable/集合，以及真实生成项目的验签与重生成保护。远程脚本从全新 module cache 安装 CLI，并检查生成项目的固定版本、校验和以及没有本地 replace。
|
||||
|
||||
Reference in New Issue
Block a user