5.8 KiB
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 文件的声明。业务方应迁入等价契约/配置并通过自己的权限、金额和事务回归后，再移除旧适配。
本地回归
以下命令已通过：
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 与多种存储配置的编译/配置校验；不把这些编译测试称作云服务联调。
生成进程报告 验证根目录 go run . / go build .、生成稳定性、业务保留、nethttp/native 的真实 HTTP、SIGINT/SIGTERM 和端口释放。消费者测试另外覆盖初始化/监听失败、依赖故障退出、排空后关闭、内置接口配置和 404/405。
MySQL 报告 使用仅绑定 localhost 的临时容器，限制 1 CPU、768 MiB、128 PIDs；临时凭据、CA、服务端与客户端证书在测试后移除。真实验证 TLS/mTLS、坏 CA/主机名拒绝、多个池隔离、会话设置与失败恢复，并复验 nethttp/native 读写超时。生成服务只改配置即可建池，并验证清理和借用 Logger 的所有权。
测试文件中的可选基础设施用例在普通 go test 下会跳过；上面的隔离数据库脚本显式开启它们，并拒绝测试级 skip。报告包含源码摘要用于追溯。
远程发布验收
代码发布标签后，使用以下命令在空 module 缓存验收同版远程 CLI/框架，不使用本地 replace；结果另行归档，发布标签不移动：
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 和文档。升级方法和完整示例见 业务开发指南。
回归通过不等于具体业务已迁移。声明式上传使用临时磁盘，部署仍需限制请求并发和容量；清理函数必须自行停止并等待业务后台任务。框架不会回滚 Logic 已提交的业务事务；纯流式接口仍遵守 Complete 后再提交副作用的约定。特殊 scalar 的业务语义和自定义 Encoder 文档仍需项目验证。