60 lines
7.3 KiB
Markdown
60 lines
7.3 KiB
Markdown
# 受管理生成项目第一版验收
|
||
|
||
日期：2026-09-24；环境：本地 darwin/arm64。版本 v0.12.0-preview；下面记录发布前源码验收，远程产物另用 `scripts/verifyManagedRelease.py` 验证。
|
||
|
||
## 完成范围
|
||
|
||
- new / api new 共用契约生成器，根目录 main.go，config/svc/logic/handler 目录；不生成 cmd/server 入口。
|
||
- main、HTTP 装配、DTO、路由和 OpenAPI 纳入 manifest v2 的生成所有权与漂移检查。
|
||
- svc 显式提供 AppOptions、GlobalMiddleware、命名中间件依赖、OnClose 和幂等 Close。初始化失败和监听失败释放资源，正常退出先排空再关闭依赖，最后关闭日志。
|
||
- 入口 @app(defaultResponse: Name)，路由/分组可覆盖；Go 错误目录单处注册，404/405 和全局中间件使用有效响应策略。
|
||
- 自动 raw/multipart 输入、@produces 输出；Logic 接收受限字节流/返回内容流，Handler 负责输出与关闭，无需手写普通上传下载接入。
|
||
- 开发者文件按字节保留，手写 main / 旧 manifest 拒绝静默接管；独立 cmd/migrate 文件保留。
|
||
|
||
## 测试结果
|
||
|
||
1. `GO_OMNI_SCAFFOLD_INTEGRATION=1 go test -race -p=1 -count=1 -timeout=300s ./...` 全部通过，含两种数据库与五种存储生成配置、原错误目录/参数和兼容性生成消费者回归。
|
||
2. `go vet ./...`、`go build ./...`、gofmt 与 `git diff --check` 通过。
|
||
3. `TestManagedGeneratedProject` 用实际生成的项目添加自定义配置/客户端，只修改 config/svc/Logic；main 保持生成版本。子项目执行 race 测试和根目录 go build。
|
||
4. 子项目验证固定错误、参数提示、未知兜底、路由覆盖、raw JSON、404/405、提前返回中间件、multipart 上传、原始 body、未知长度请求体超限、下载内容及内容流关闭。
|
||
5. 子项目验证初始化失败/监听失败只关闭一次、在途请求排空前依赖仍可用；追加接口自动生成、连续生成稳定、main 漂移被 --check 拒绝。
|
||
6. 新增所有权专项 `go test -race ./cmd/go-omni/apigen -run '^TestManagedOwnership' -count=1` 通过：旧 manifest 和无所有权 main 均拒绝且不改写项目。
|
||
7. [真实进程报告](managedProjectLocal.json) 记录最近一轮耗时与源码哈希；根目录 go run/go build，nethttp/native 二进制 SIGINT/SIGTERM 退出码为 0、监听端口释放。go run 的包装进程可由信号退出，子服务必须退出并释放端口。
|
||
8. nethttp/native 均实际请求 managedService 示例：Go 错误目录、默认 404/405、raw JSON、下载、原文回执、上传及 413 均通过。所有临时进程、端口、文件已回收。
|
||
9. 仓库中的 examples/managedService 单独执行 go mod tidy、go test -race ./...、go build .；生成器 --check 通过。它用相对 replace 指向当前源码；远程产物验收会重新生成项目，不复制这个 replace。
|
||
|
||
## 第一版复查补强
|
||
|
||
- 上传内容和 MIME 头截断、缺少关闭边界、未读部分和被忽略的读取错误均拒绝成功；默认错误为 400 / INVALID_MULTIPART，项目目录可定制。数据库等 Logic 错误保留原语义，内部文件内容和解析原因不出现在公开提示。
|
||
- 覆盖逐字节输入、CRLF/LF、无尾部换行、合法边界空白、多文件顺序、跳过/重复关闭 Part、quoted-printable 与 NextRawPart、epilogue 及未知长度超限。保持标准库 MIME 解析，附加关闭边界观察不缓存文件内容，也不创建临时文件。
|
||
- Config.Validate 检查实际选中的编码器与 App 错误目录，拒绝冲突目录和冲突业务码映射；相同目录和兼容 RawJSON 仍通过。
|
||
- 实际生成项目验证定制的 400 / 400004 /「上传内容不完整」及 data:null；真实本地 nethttp/native 请求覆盖内容截断和 MIME 头截断。
|
||
|
||
## 契约变更诊断验收
|
||
|
||
- manifest v2 增加可选契约快照，与生成产物在同一次受保护写入中更新；新项目初次生成不报无意义变更，缺少快照的已有 v2 项目明确提示建立基线。
|
||
- 验证请求/返回类型替换、body 参数增加、DTO 改为流式返回、嵌套字段/标签、scalar 映射、路径/限额/媒体类型变化及接口删除。无关接口和注释修改不误报；提示顺序稳定。
|
||
- 业务签名检查支持导入别名、命名返回值和同组跨文件方法定位；覆盖语法错误、重复方法、测试文件排除和不确定的项目类型别名/build tags。方法体语义和复杂类型关系由 Go 编译器验证。
|
||
- 实际临时项目修改 GreetReq 为 HelloReq：dry-run/check 保持文件不变，generate 保留业务文件原字节，重新生成后 check 仍拒绝旧签名；修复业务签名后 check、go test、go build 通过。CLI 失败时也能看到文件/行号与前后签名。
|
||
- `GO_OMNI_SCAFFOLD_INTEGRATION=1 go test -race -p=1 -count=1 -timeout=300s ./cmd/go-omni/...` 通过，覆盖生成器与脚手架全部消费者；新增诊断专项 race 回归通过。`go vet ./cmd/go-omni/...`、`go build ./...` 通过。
|
||
- 本轮 [真实进程报告](managedProjectLocal.json) 包含 contractChangePreview、logicSignatureCheckPersists、businessSourcePreserved、fixedConsumerBuild，并保留 nethttp/native 的真实请求与退出验证。
|
||
|
||
## 边界
|
||
|
||
未修改 eTax/ePay；未连接业务服务器、真实数据库或云存储；没有负载/soak 测试。源码与远程产物均在本地临时服务上验收。数据库/云存储配置组合通过生成项目编译与既有测试，不能据此声称真实环境集成完成。
|
||
|
||
multipart 通过流式 Parts 处理，不产生临时文件。业务负责字段/文件内容校验、存储和实际签名算法。请求读取后再提交业务副作用；超限或读取失败不能回滚业务自行提前写出的数据。Range、SSE 等特殊行为仍可显式选择手写 Handler。
|
||
|
||
项目维护边界见 [PROJECT.md](../PROJECT.md)，可运行示例见 [managedService](../examples/managedService/README.md)。
|
||
|
||
## 发布后的远程产物验收
|
||
|
||
2026-09-24 执行 `python3 scripts/verifyManagedRelease.py --version v0.12.0-preview` 通过，耗时 28.89 秒；[机器报告](managedProjectRemote.json) 记录依赖校验和与验收源码哈希。
|
||
|
||
- 不可变标签对应代码提交 `158b8002b355f09237cd12f49d9b66ee78d493f3`；CLI 从远程仓库安装，使用全新 GOMODCACHE。新生成项目不传 framework-dir 或 framework-version，自动固定 CLI 自身版本。
|
||
- 框架 module 为 v0.12.0-preview，校验和 `h1:o9dN8YdhE9o4EcGWAuFb/EGCcQlWRR7IMUc/G7Ymkeg=`；消费者无本地 replace，四个生成消费者验证同一校验和。
|
||
- 实际生成新目录，根目录 go run/go build；修改 DTO 后 dry-run/check 只读，重新生成保留业务源码，签名问题持续报错；修复签名后检查、测试与构建通过。
|
||
- nethttp/native 二进制分别验证 SIGINT/SIGTERM、退出码和端口释放。下载、原文回执、上传、损坏 multipart、默认 404/405 和 Go 错误目录通过真实本地 HTTP 请求验证。
|
||
- 四个消费者 race 回归全部通过：TestManagedGeneratedProject、TestErrorInheritanceConsumer、TestErrorParamsConsumer、TestCompatibilityConsumer；覆盖初始化/监听失败清理、先排空后关闭依赖、错误参数与继承、手写 hook 和自定义标量。
|
||
- 临时缓存、生成项目、进程和监听端口已回收。这个报告在发布后单独提交，不移动已经发布的标签。
|