65 lines
6.4 KiB
Markdown
65 lines
6.4 KiB
Markdown
# v0.14.0-preview 通用业务开发验收
|
||
|
||
验收日期：2026-09-24。范围为 go-omni 框架、生成消费者、隔离本地 MySQL；没有修改 eTax/ePay 业务，也没有连接既有业务服务器。本轮实现不内置业务字段、中文文案、表结构、权限或事务规则。
|
||
|
||
## 完成项与业务可移除的适配
|
||
|
||
| 能力 | 验收内容 | 接入项目可替换的通用代码 |
|
||
| --- | --- | --- |
|
||
| 根数组、可空对象、成功 null | 自动 Logic/Handler，nil 数组归一为 `[]`，可空对象与 null 保留，raw/统一公共体/204 分开验证 | 仅为响应形状存在的手写 Handler |
|
||
| 严格请求策略 | 未知 query、原始非法 UTF-8、charset、必填/可选/禁止 body、严格 `{}`、重复键、未知字段、分块限额及 413 | strictRequest、jsonEncoding、emptyJSON、query 白名单与从 OpenAPI 反读规则 |
|
||
| 声明式 multipart | 文件/文本/JSON DTO、普通字段校验先于 Logic、未知/重复/缺失/截断/各级超限、文件读者与临时文件清理 | FormFile/PostFormValue、手工 JSON 表单解码；仍保留资料内容检查 |
|
||
| 配置与校验 | 全结构体默认值→文件→环境、显式 0/false、空值策略、嵌套、duration/map/slice、敏感值不进入解析诊断、失败不污染默认配置 | 重复 LookupEnv/ParseBool/Atoi/ParseDuration 和框架日志校验 |
|
||
| 生命周期与日志 | 逆序清理、并发幂等关闭、失败回滚、清理 panic 后继续、依赖故障原因保留、排空先于释放、多 App Logger 隔离 | svc 的锁/once/清理栈、标准日志桥接、可信 ClientIP 搬运 |
|
||
| 依赖中间件与 context 错误 | 小接口工厂装配，标准 context 传递可信元数据；取消/超时映射尊重显式业务错误 | 为接入依赖而放进 context 的服务对象、重复 contextErrors |
|
||
| 字段文档与格式化 | 中文前置/同行注释、example/枚举说明；格式化保字面量与注释、字段对齐、幂等/只读 check；元数据不调用项目 scalar 解码器 | 常规接口的文档反射补丁、第二份手工维护的 OpenAPI |
|
||
| Go 错误目录文档 | 显式 ExportCatalog、严格元数据解码、参数/响应示例、独立路由目录优先，CLI 不执行项目 Go | 在 `.api` 重复维护 Go 错误表 |
|
||
| 多服务契约与升级 | roots/摘要、路径与符号链接边界、循环/深度/数量限制、分文件 DTO、独立 module 工作区；原模板升级、定制文件保护及失败回滚 | response.api 复制脚本、把整棵新生成目录手工拼回项目 |
|
||
| MySQL 接入 | 结构化配置、独立 TLS/双向 TLS、主机名与 CA 验证、连接池/会话/驱动日志隔离、启动检查、清理；继续复用标准 Connector | TLS 注册、驱动配置、建池/Ping/日志适配和通用失败清理；保留 SQL/版本和表结构策略 |
|
||
|
||
以上是可替换的职责，不是已删除 eTax 文件的声明。业务方应迁入等价契约/配置并通过自己的权限、金额和事务回归后，再移除旧适配。
|
||
|
||
## 本地回归
|
||
|
||
以下命令已通过：
|
||
|
||
```sh
|
||
GO_OMNI_SCAFFOLD_INTEGRATION=1 go test -race ./... -count=1 -timeout=300s
|
||
go vet ./...
|
||
go build ./...
|
||
go run ./cmd/go-omni api generate --dir examples/managedService --check
|
||
go run ./cmd/go-omni api format --api examples/contracts/business.api --check
|
||
git diff --check
|
||
python3 scripts/verifyManagedProject.py --report reports/businessDevelopmentManagedLocal.json
|
||
python3 scripts/verifyConnector.py --local --report reports/businessDevelopmentConnectorLocal.json
|
||
```
|
||
|
||
全量 race 包括框架既有网络层、错误继承/参数、桥接、上传下载回归，以及实际生成消费者。生成器集成包括 MySQL 与多种存储配置的编译/配置校验；不把这些编译测试称作云服务联调。
|
||
|
||
[生成进程报告](businessDevelopmentManagedLocal.json) 验证根目录 `go run .` / `go build .`、生成稳定性、业务保留、nethttp/native 的真实 HTTP、SIGINT/SIGTERM 和端口释放。消费者测试另外覆盖初始化/监听失败、依赖故障退出、排空后关闭、内置接口配置和 404/405。
|
||
|
||
[MySQL 报告](businessDevelopmentConnectorLocal.json) 使用仅绑定 localhost 的临时容器，限制 1 CPU、768 MiB、128 PIDs；临时凭据、CA、服务端与客户端证书在测试后移除。真实验证 TLS/mTLS、坏 CA/主机名拒绝、多个池隔离、会话设置与失败恢复，并复验 nethttp/native 读写超时。生成服务只改配置即可建池，并验证清理和借用 Logger 的所有权。
|
||
|
||
测试文件中的可选基础设施用例在普通 `go test` 下会跳过；上面的隔离数据库脚本显式开启它们，并拒绝测试级 skip。报告包含源码摘要用于追溯。
|
||
|
||
## 远程发布验收
|
||
|
||
远程验收已通过。代码标签固定在 `f5478cdc7662704b164637649305361e52f7c598`，报告另行提交，标签没有移动。两个脚本分别使用空 module 缓存，同版远程 CLI/框架均无本地 replace：
|
||
|
||
- [生成服务远程报告](businessDevelopmentManagedRemote.json)：30.00 秒，覆盖实际生成、运行/构建、错误目录和模板参数、根数组/null、严格请求、声明式上传、依赖中间件、退出与清理。
|
||
- [数据库远程报告](businessDevelopmentConnectorRemote.json)：22.99 秒，真实 MySQL TLS/mTLS、Connector/池隔离、HTTP 限额与生成 MySQL 服务的配置和生命周期。
|
||
- 两者 module 校验值一致：`h1:qG0Ipjt3enc8/Enu8ihJ6h8c8U6FCDedoNSdzuC3rBc=`。临时容器、凭据、证书和消费者目录已清理。
|
||
|
||
复验命令：
|
||
|
||
```sh
|
||
python3 scripts/verifyManagedRelease.py --version v0.14.0-preview --report reports/businessDevelopmentManagedRemote.json
|
||
python3 scripts/verifyConnector.py --version v0.14.0-preview --report reports/businessDevelopmentConnectorRemote.json
|
||
```
|
||
|
||
## 维护边界
|
||
|
||
用户维护 `.api`、业务配置、svc 字段/Init/AppOptions/DatabaseOptions、错误目录、Logic、Repository、权限中间件及特殊协议扩展。生成器管理 main、runtimeGen、路由/Handler、DTO 和文档。升级方法和完整示例见 [业务开发指南](../DEVELOPMENT.md)。
|
||
|
||
回归通过不等于具体业务已迁移。声明式上传使用临时磁盘，部署仍需限制请求并发和容量；清理函数必须自行停止并等待业务后台任务。框架不会回滚 Logic 已提交的业务事务；纯流式接口仍遵守 Complete 后再提交副作用的约定。特殊 scalar 的业务语义和自定义 Encoder 文档仍需项目验证。
|