197 lines
16 KiB
Markdown
197 lines
16 KiB
Markdown
# v0.15.0-preview
|
||
|
||
增加通用后台分阶段关闭：生成入口先完成 HTTP 排空，再运行全部 OnStop、全部 OnDrain，确认组件收尾后逆序释放 OnClose 资源，最后关闭日志。适用于任意后台组件；不引入 Orbit，不改变业务事务或任务一致性策略。
|
||
|
||
- svc 登记成对、同名的 OnStop/OnDrain，Context 用于早期退出通知，WorkContext 供已接受工作在收尾期间使用。同一阶段并发执行，存在内部先后依赖的组件组合登记。
|
||
- server.lifecycle 配置 stopTimeout、drainTimeout、cancelTimeout。阶段超时取消工作并给未返回钩子收尾窗口；错误与阶段/组件名称可通过错误链追踪。
|
||
- 不能确认后台已经结束时，返回 ErrResourcesRetained，保留共享资源和借用日志，生成进程非零退出。未返回的 Stop 不会与自己的 Drain 重叠；错误、panic 不阻止其他组件尝试收尾。
|
||
- task.Runner 增加 StopAccepting/Wait，原 Shutdown/Close 继续可用。核心 lifecycle 不依赖 task 或其他适配器。
|
||
- 初始化和监听失败复用同一流程；重复关闭只执行一次。生成器继续保留配置、svc 和业务代码。
|
||
|
||
```sh
|
||
go get git.yuntuo.hk/k2safe/go-omni@v0.15.0-preview
|
||
go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.15.0-preview
|
||
go-omni api generate
|
||
go-omni api generate --check
|
||
go test ./...
|
||
```
|
||
|
||
v0.14.x 无需重写 svc/config；生成器更新 main/runtimeGen，未配置时使用默认时限。也可 api upgrade --dry-run/--apply 更新依赖与生成文件，保留已有项目扩展。需要阶段保证的旧后台 OnClose 登记，应显式迁到 Stop/Drain；v0.13 及更早版本仍按原迁移指南处理。
|
||
|
||
全量 race（含实际生成项目）、vet、build 和隔离 MySQL/GORM 验收已通过。发布后的空缓存远程生成项目与真实 MySQL/GORM 验收也通过，CLI/框架同版且无本地 replace；标签固定在 `16deead70e860052c5b629511207578c03f9b2cb`。详见 [生命周期接入](lifecycle/README.md#后台组件分阶段关闭) 与 [验收记录](reports/phasedLifecycleAcceptance.md)。Go 无法强制结束任意 goroutine；OnClose 仍须能返回，HTTP 处理器仍须响应取消。此版不会将未知的第三方组件自动改造成优雅关闭组件。
|
||
|
||
---
|
||
|
||
# v0.14.1-preview（历史版本）
|
||
|
||
增加可选 `database/gormx`：GORM 复用 go-omni 已初始化的标准池、TLS、限额、健康检查和关闭流程，业务继续使用原生 GORM 模型与事务。核心 App/数据库包的编译依赖链不引入 GORM。
|
||
|
||
在 svc.Init 中调用 `gormx.MySQL(ctx, c.DB, gormx.WithLogger(c.Logger))`；通用 Open 工厂保留其他方言入口。适配器保护借用池不被初始化失败路径关闭，并为初始化查询设置时限。查询使用 WithContext，SQL 日志接入 logx，请求标识、慢查询和错误分类贯通；默认不输出绑定参数与驱动完整错误文本。
|
||
|
||
v0.14.0 项目更新 module 与 CLI 即可，不改生成目录或 main。模板最低运行时保持 v0.14.0；修正新版 CLI 把最低兼容版本误当自身版本、导致同版消费者出现版本提示的问题。其他数据库方言和管理额外池的插件未纳入本次实库验收，原生 PrepareStmt 的生命周期限制见 [接入说明](database/gormx/README.md)。
|
||
|
||
```sh
|
||
go get git.yuntuo.hk/k2safe/go-omni@v0.14.1-preview
|
||
go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.14.1-preview
|
||
```
|
||
|
||
全量 race（含生成消费者）、vet、build，以及隔离 MySQL 的事务/取消/日志/生成项目接入通过。发布后的空缓存远程 MySQL/GORM 和生成项目验收均通过，无本地 replace，CLI 与框架使用同版。标签固定在 `b8ab6b35219d53d6de392c920fe7ecbe9a76dade`，详见 [GORM 验收](reports/gormAcceptance.md)。
|
||
|
||
---
|
||
|
||
# v0.14.0-preview（历史版本）
|
||
|
||
本版补齐契约驱动的业务开发与通用基础设施。项目继续维护接口、配置、依赖装配、Logic、SQL 和业务规则；生成器维护入口、请求绑定、路由、响应与文档。
|
||
|
||
## 安装与升级
|
||
|
||
```sh
|
||
go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.14.0-preview
|
||
go-omni new --module example.com/billing ./billing
|
||
```
|
||
|
||
新生成器与运行时一起升级。已有 v0.13 项目先运行 `go-omni api upgrade --dry-run`，再按 [定点迁移步骤](DEVELOPMENT.md#v013-项目升级) 处理；不会静默覆盖自定义 svc/config。运行期的新构造器由生成器维护，项目初始化迁入 `svc.Init`，使用 `OnClose` 登记资源。
|
||
|
||
## 本版能力
|
||
|
||
- `.api` 支持根数组、可空对象、成功 null；真正 204 独立保留。生成 Logic、Handler、OpenAPI 和漂移检查使用相同语义。
|
||
- 请求契约控制未知 query、原始 UTF-8、charset、必须/可选/禁止 body 和严格空对象。路由覆盖 App 策略，普通 JSON 只解析一次。
|
||
- multipart 声明文件、文本和 JSON 表单字段。Logic 收到校验后的 DTO；文件有界暂存、流式读取、请求结束清理，保留底层 raw/multipart/下载扩展。
|
||
- 完整项目配置支持环境覆盖、显式零值、空值策略、必填、嵌套及复杂类型。独立校验先于日志和连接创建。
|
||
- `lifecycle.Runtime` 统一逆序清理、幂等关闭、失败回滚及故障保留；App Logger 独立，支持标准 `log.Logger` 与可信请求元数据。提供依赖中间件装配示例和可选 context 错误映射。
|
||
- 官方 `database/mysql` 适配器提供结构化配置、每连接池独立 TLS/mTLS、驱动日志、启动检查与失败清理。继续返回同一 `database.DB`，不自动迁移表或重试业务事务。
|
||
- 字段注释、示例和枚举说明进入 DTO/OpenAPI；`api format` 幂等格式化。Go 错误目录可显式导出供文档使用，无需复制错误定义。
|
||
- 显式共享契约 roots、来源摘要、分文件 DTO、多服务 workspace 命令、基础模板升级预览；保留目录边界及业务文件所有权。
|
||
|
||
详见 [业务开发指南](DEVELOPMENT.md)、[数据库接入](database/mysql/README.md) 和 [验收记录](reports/businessDevelopmentAcceptance.md)。
|
||
|
||
全量 race（含生成项目）、vet、build 与本地进程验收通过。发布后的空缓存远程消费者和隔离 MySQL 验收也均通过；CLI/框架同版且无本地 replace。标签固定在 `f5478cdc7662704b164637649305361e52f7c598`，报告单独提交。
|
||
|
||
仍需业务维护：契约、配置、svc 依赖创建/探针/清理登记、错误目录、Logic、Repository 和权限中间件。特殊协议可使用保留的扩展点。声明式上传的暂存磁盘和并发量需配置容量；共享契约版本标签由项目管理，框架校验摘要但不下载依赖。此版仍为 preview，不代表 eTax/ePay 已完成业务迁移。
|
||
|
||
---
|
||
|
||
# v0.13.0-preview（历史版本）
|
||
|
||
本版补齐项目依赖主动退出与内置接口配置。ID 租约、数据库或后台任务等故障由项目判断，框架通过统一生命周期完成退出；不内置业务规则。
|
||
|
||
## 使用与升级
|
||
|
||
```sh
|
||
go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.13.0-preview
|
||
# 在业务 module 中执行
|
||
go get git.yuntuo.hk/k2safe/go-omni@v0.13.0-preview
|
||
go-omni api generate
|
||
```
|
||
|
||
新项目自动获得全部扩展。v0.12 的 config/svc 属于项目文件，重新生成会保留它们；需按 [升级步骤](PROJECT.md#从-v012-生成项目升级) 给 svc 补入 Lifecycle、RequestShutdown 与清理衔接，main 和 Handler 由生成器更新。旧 v0.11 目录仍按原迁移规则在新目录生成。
|
||
|
||
## 行为
|
||
|
||
- `svc.RequestShutdown(err)` 非阻塞通知：停止接收请求、排空、关闭依赖和日志。首个非空故障保留，故障退出码为 1；正常停止在没有其他故障时退出码为 0。初始化期间通知、并发通知和排空期间报告故障均可处理。
|
||
- App 生命周期入口保留异常 context 取消原因；符合 context.Canceled 的信号取消保持正常停止。生成入口还读取 Controller.Err，保留显式依赖故障，即使该故障包装了 context.Canceled。
|
||
- `/health/ready` 修复绕过响应配置的问题，默认与 liveness 一起使用项目 App 的响应格式。就绪成功使用项目成功码与提示；未就绪使用 `NOT_READY` 的项目错误定义，同时固定 HTTP 503。raw 模式只返回健康数据；内部探针原因仅供日志。
|
||
- `server.endpoints` 控制三个内置 GET 接口的开关和路径，健康端点另有 responseMode。支持环境变量覆盖。OpenAPI 保持原始规范，不包业务公共体；关闭 HTTP 端点不影响生成文档。
|
||
- `.api` 不再固定保留三个默认路径；启用的内置路径与业务 GET/参数/通配路由重叠时，启动前返回明确错误并清理已创建的依赖。关闭或改名后允许项目接管旧路径。全局中间件继续执行。
|
||
|
||
## 验收
|
||
|
||
源码测试和实际生成项目验证记录见 [生命周期与端点验收](performance/lifecycleEndpointsAcceptance.md)。复验命令：
|
||
|
||
```sh
|
||
GO_OMNI_SCAFFOLD_INTEGRATION=1 go test -race -p=1 -count=1 -timeout=300s ./...
|
||
go vet ./...
|
||
go build ./...
|
||
python3 scripts/verifyManagedProject.py --report performance/lifecycleEndpointsLocal.json
|
||
python3 scripts/verifyManagedRelease.py --version v0.13.0-preview --report performance/lifecycleEndpointsRemote.json
|
||
```
|
||
|
||
发布后的远程空缓存验收已通过，耗时 26.55 秒；[机器报告](performance/lifecycleEndpointsRemote.json) 确认 CLI 和生成项目使用同版远程 module，无本地 replace。报告单独提交，发布标签保持在代码提交 `f0991d3ff248e4cb32812c368f0f8ba28740a6c7`。此版仍为 preview；具体业务的租约失效保护、鉴权与事务回归由接入项目验证。资源清理顺序不代表能强行结束忽略 context 取消的业务 goroutine；项目 Close 必须停止并等待自己启动的后台任务。
|
||
|
||
---
|
||
|
||
# v0.12.0-preview（历史版本）
|
||
|
||
本版用于固定版本开展业务接入。生成器统一维护服务根目录 main.go、路由、HTTP Handler、DTO 和 OpenAPI，业务方维护 `.api`、config、svc、logic、repository 与项目中间件。目录不再生成 cmd/server、settings、servicecontext 或 service。
|
||
|
||
## 安装与接入
|
||
|
||
仓库权限及 PATH 配置见 [README](README.md#准备环境与安装)。CLI 与框架使用同一版本：
|
||
|
||
```sh
|
||
go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.12.0-preview
|
||
go-omni new --module example.com/hello ./hello
|
||
cd hello
|
||
go mod tidy
|
||
go run .
|
||
```
|
||
|
||
已存在的手写项目可直接 `go get git.yuntuo.hk/k2safe/go-omni@v0.12.0-preview`。采用生成目录的旧项目在新目录生成后迁入业务代码，详见 [接入步骤](PROJECT.md#已有服务接入步骤) 和 [文件维护边界](PROJECT.md#哪些文件由用户维护)。新 manifest v2 不兼容旧 manifest；不会静默覆盖手写 main，也不会删除独立 cmd/migrate 等工具。
|
||
|
||
## 本版行为
|
||
|
||
- 根目录支持 go run / go build；入口负责配置、日志、依赖、HTTP 启动与信号退出。svc 的 AppOptions、GlobalMiddleware 和 OnClose 是显式扩展入口；初始化/监听失败会释放资源，正常退出先排空请求再关闭依赖和日志。
|
||
- `.api` 入口通过 `@app(defaultResponse: Name)` 选择默认响应，覆盖普通路由、404/405 与相应中间件错误；多模板不会按声明顺序猜默认值。字段、状态、业务码和文案由项目配置。
|
||
- 保持 v0.11.1 的错误目录继承：Go 中注册一次，无独立错误目录的生成路由继承 App。带参数提示、内部错误链、raw 响应和独立目录保持各自行为。
|
||
- raw/multipart 上传及 `@produces` 下载可直接编写 Logic，由生成 Handler 完成受限读取、响应和流关闭。损坏 multipart 默认 400，超限 413；项目可以定制公开错误。
|
||
- 契约变更提示受影响的 Logic、DTO 字段和请求模式；明确的签名/语法/重复方法错误使 `generate --check` 失败。重新生成保留业务文件，main 和其他生成文件的漂移也会被检查。
|
||
|
||
## 验收与范围
|
||
|
||
发布前全量 race 测试、go vet、go build 和本地实际生成项目进程验收通过。发布后的空缓存远程验收也已通过，记录见 [生成项目验收](performance/managedProjectAcceptance.md) 和 [远程产物报告](performance/managedProjectRemote.json)。报告作为单独提交保存，v0.12.0-preview 标签保持在发布代码提交 `158b8002b355f09237cd12f49d9b66ee78d493f3`，没有改写。复验命令：
|
||
|
||
```sh
|
||
GO_OMNI_SCAFFOLD_INTEGRATION=1 go test -race -p=1 -count=1 -timeout=300s ./...
|
||
go vet ./...
|
||
go build ./...
|
||
python3 scripts/verifyManagedProject.py
|
||
python3 scripts/verifyManagedRelease.py --version v0.12.0-preview
|
||
```
|
||
|
||
远程验收使用空 module 缓存安装已发布 CLI，生成的业务项目仅依赖同版远程 module，无本地 replace；检查根目录运行/构建、重新生成、错误继承/模板参数、上传下载、nethttp/native 的真实请求与退出信号，以及初始化失败/监听失败/请求排空后的清理。
|
||
|
||
本版不代表具体业务项目已完成迁移验收。HTTP/2 仍为实验状态；真实数据库、云账号和业务服务器不属于本轮验收范围。轻量 Logic 检查不能代替 Go 编译器或业务测试。静态 OpenAPI 不执行 Go 代码，因此不会自动列举仅在 Go 中维护的错误目录。请求流校验不能回滚业务提前执行的副作用，关键写入应放在 `body.Complete()` 成功之后。
|
||
|
||
---
|
||
|
||
# v0.11.1-preview（历史版本）
|
||
|
||
修复生成路由使用空错误目录遮蔽 `omni.WithErrors(catalog)` 的问题。错误现在可以只在 Go 中注册一次，`.api` 无需重复定义错误目录或逐条列出错误。
|
||
|
||
## 行为
|
||
|
||
- 未声明路由错误列表：继承 App 目录，包括带参数提示及项目自定义 INTERNAL_ERROR 兜底。
|
||
- 显式引用路由错误：继续使用路由独立目录，不与 App 合并。
|
||
- `@errors none` 清空 `.api` 分组错误列表，随后继承 App。
|
||
- 错误继承不覆盖 `.api` 的返回格式、RawJSON、手写绑定或请求体限额；全局中间件提前返回、标准桥接与克隆保持一致。
|
||
- 空 `response.WithErrors` / `MustWithErrors` 返回原 Encoder，既不覆盖 Context 的目录，也不在编码阶段按空目录重新解析错误。
|
||
|
||
## 升级
|
||
|
||
```sh
|
||
go get git.yuntuo.hk/k2safe/go-omni@v0.11.1-preview
|
||
go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.11.1-preview
|
||
go-omni api generate --dry-run
|
||
go-omni api generate
|
||
go test ./...
|
||
```
|
||
|
||
运行时修复也适用于旧 v0.11.0 生成代码，因此升级运行时后即可解除空目录遮蔽。同步升级 CLI 重新生成时不再创建空目录包装；已生成业务文件继续受保护。代码生成最低运行时仍为 v0.11.0-preview。
|
||
|
||
接入见 [README](README.md)、[错误目录继承](errors/README.md) 和 [只在 Go 注册错误的契约示例](examples/contracts/errorInheritance.api)。静态 OpenAPI 不执行 Go 配置，保留契约响应结构，不自动列举运行时目录内容。
|
||
|
||
## 验收
|
||
|
||
复现用例在修复前：普通路由通过，生成/RawJSON 路由和提前返回中间件共 12 项失败，均变成 500/英文系统提示。修复后同一批用例通过。
|
||
|
||
```sh
|
||
GO_OMNI_SCAFFOLD_INTEGRATION=1 go test -race -p=1 -count=1 -timeout=300s ./...
|
||
go vet ./...
|
||
go build ./...
|
||
python3 scripts/verifyErrorInheritanceRelease.py --version v0.11.1-preview
|
||
python3 scripts/verifyErrorParamsRelease.py --version v0.11.1-preview --report performance/errorInheritanceParamsRemote.json
|
||
python3 scripts/verifyCompatibilityRelease.py --version v0.11.1-preview --report performance/errorInheritanceCompatibilityRemote.json
|
||
```
|
||
|
||
结果见 [目录继承验收](performance/errorInheritanceAcceptance.md)。本轮未修改 eTax/ePay 业务代码，没有使用业务服务器。
|