44 lines
3.2 KiB
Markdown
44 lines
3.2 KiB
Markdown
# v0.9.0-preview
|
||
|
||
本版补齐已有 HTTP 项目的迁移接入能力：标准 Handler/Middleware 桥接、动态 JSON、路由级请求体限额与手写绑定、自定义标量转换。业务的响应格式、身份、资金事务和数据库实现仍由项目决定。
|
||
|
||
## 安装与升级
|
||
|
||
```sh
|
||
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。普通基础类型不会自动放宽。
|
||
|
||
详见 [迁移扩展指南](MIGRATION.md)、[完整契约](examples/contracts/compatibility.api)、[运行示例](examples/compatibility/main.go) 和 [历史更新](CHANGELOG.md)。
|
||
|
||
## 兼容与边界
|
||
|
||
原有 `.api`、公共响应配置和普通 Handler 可以继续使用。新生成代码最低运行时版本为本版。`Raw()` 现在返回跟踪包装器；直接断言某个具体 writer 类型的代码需改用标准接口/ResponseController。
|
||
|
||
标准中间件须保留 incoming request context 并同步调用 next；第三方框架私有的参数读取器仍由项目适配。手写 Handler/绑定 hook 初始返回 501；实现和文档一致性由项目负责，未实现不能上线。切换 manual 回自动模式时须显式迁移并移除对应手写文件，生成器不会删除它。
|
||
|
||
新增能力没有引入 Gin 或 go-zero 依赖。不是完整 goctl 语法兼容层，不代表任何业务项目已完成迁移。HTTP/2 仍为实验功能，本轮没有重新做 Linux 长测、代理验收或云存储账号实网验收。
|
||
|
||
## 验证入口
|
||
|
||
```sh
|
||
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。
|