62 lines
6.0 KiB
Markdown
62 lines
6.0 KiB
Markdown
# 依赖主动退出与内置接口配置验收
|
||
|
||
日期：2026-09-24；环境：Go 1.27.1，darwin/arm64；目标版本：v0.13.0-preview。
|
||
|
||
## 验收范围
|
||
|
||
- 通用生命周期控制器连接项目依赖与生成入口。项目决定故障是否需要退出；框架不判断 ID 租约或其他业务规则。
|
||
- `svc.RequestShutdown(err)` 立即通知并保留首个非空原因，生成入口排空 HTTP 后关闭依赖与日志；重复或并发通知不会重复清理。
|
||
- 生成项目通过 `server.endpoints` 控制 liveness、readiness、OpenAPI 的开关与路径。健康检查默认使用项目响应模板和错误目录，可显式选择 raw 数据。
|
||
- 就绪失败固定 HTTP 503，即使项目业务错误统一使用 HTTP 200；原始探针错误保留给日志，不进入公开响应。OpenAPI 不包装公共体。
|
||
|
||
## 源码与实际生成项目
|
||
|
||
回归命令：
|
||
|
||
```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
|
||
```
|
||
|
||
最终全量 race 测试（包括生成器集成测试）、go vet、go build 全部通过；修改文件的 gofmt、Python 语法、文档本地链接及 git diff --check 通过，本地报告的源码哈希与发布源码一致。
|
||
|
||
- `lifecycle` 测试覆盖并发通知、正常停止后报告故障、初始化前通知、父 context 原因，以及包装 context.Canceled 的显式故障。
|
||
- `TestFatalShutdownDrainsAndPreservesCause` 在 nethttp/native 上验证：在途请求完成前不关闭依赖，关闭仅一次，故障和清理错误都保留；提前取消的启动同样保留故障。
|
||
- `TestManagedGeneratedProject` 使用实际 CLI 生成的 main/Handler/DTO，在项目文件中加入模拟客户端和配置，子项目执行 race 测试与根目录构建。新增子测试验证依赖通知后的排空顺序、初始化期间通知、端点配置、冲突后的资源释放。
|
||
- `TestGeneratedFatalProcessExit` 启动真实子进程执行生成的 main：故障退出码为 1，输出保留实际原因，模拟客户端只关闭一次。
|
||
- 健康测试覆盖数字 code、项目 msg、成功模板、NOT_READY 目录映射、raw 数据、关闭中的 readiness、失败日志状态与内部原因。目录的 HTTP 200 和自定义 Encoder 都不能把未就绪改成 HTTP 200；编码器出错或 panic 时也不会误报健康。
|
||
- 配置测试覆盖默认值合并、显式 false、环境变量、非法路径/模式、重复端点及业务参数/通配路径冲突。`TestConfigurableBuiltinRoutesConsumer` 用真实生成项目验证：默认冲突明确报错；禁用或改名后项目可接管原路径。
|
||
- 原生成项目回归继续覆盖 Go 错误目录继承、模板参数、404/405、中间件错误、raw body、multipart 上传、流式下载、初始化/监听失败清理、业务文件保留和生成漂移检查。
|
||
- [本地真实进程报告](lifecycleEndpointsLocal.json) 最近一轮通过，耗时 4.33 秒，记录验收源码哈希；根目录 go run/go build、nethttp/native 的 SIGINT/SIGTERM、端口释放及上传下载请求均通过。二进制正常信号退出码为 0；go run 包装进程允许被信号终止，子服务必须退出并释放端口。
|
||
- 源码示例 `examples/managedService` 编译、race 测试与 `api generate --check` 通过；示例保留相对 replace 以运行本地源码。远程验收会重新生成无 replace 的项目。
|
||
|
||
## 验证过程中修正的问题
|
||
|
||
真实进程验收发现 Go 1.27 的 signal.NotifyContext 使用可匹配 context.Canceled 的信号原因；精确相等判断会把正常信号误报为故障。生命周期现在使用 errors.Is 识别正常取消，同时 Controller 单独保留项目显式报告的非空错误。修正后两种网络层的 SIGINT/SIGTERM 退出验证通过。
|
||
|
||
一次全量测试中，S3 协议夹具的故意损坏请求触发 SDK 随机重试，耗尽共享测试期限。仅将测试自建客户端设置为一次尝试，生产客户端配置保持不变，并单独检查 Open 创建的客户端可访问夹具；连续三次 race 回归通过。此调整不改变存储运行时行为。
|
||
|
||
## 升级与边界
|
||
|
||
v0.12 项目的 svc/config 是开发者文件，重新生成仍会保留。升级需按 [PROJECT.md](../PROJECT.md#从-v012-生成项目升级) 在 svc 增加 Lifecycle、RequestShutdown 和清理衔接；main/Handler 由生成器自动更新。新项目直接获得这些扩展。
|
||
|
||
请求排空使用已有 shutdownTimeout；忽略 context 的业务 goroutine 无法被框架强制结束，项目 Close 必须停止并等待自建监控任务。内置接口继续经过全局中间件，访问规则由项目设置。
|
||
|
||
没有修改 eTax/ePay，也未连接业务服务器、真实数据库或云存储。所有服务与子进程均在本地临时环境验收并回收；本轮不是压力测试或业务迁移验收。
|
||
|
||
## 发布后的远程产物验收
|
||
|
||
2026-09-24 执行以下命令通过，耗时 26.55 秒；[机器报告](lifecycleEndpointsRemote.json) 记录校验和、检查项和验收源码哈希：
|
||
|
||
```sh
|
||
python3 scripts/verifyManagedRelease.py --version v0.13.0-preview --report performance/lifecycleEndpointsRemote.json
|
||
```
|
||
|
||
- 不可变标签的代码提交为 `f0991d3ff248e4cb32812c368f0f8ba28740a6c7`。从远程仓库安装 CLI，使用全新 GOMODCACHE；新项目自动引用 CLI 自身版本，没有本地 replace。
|
||
- 框架 module 校验和为 `h1:FhNYVObpirgbSdd5Ot02fHuhiopn6/a6ZlfE/HMrqRs=`。四个生成消费者均验证同一远程校验和，race 测试全部通过。
|
||
- 远程生成的入口通过故障退出码、初始化期间通知、排空后清理、端点开关/改名、项目健康响应、端点冲突清理验证；Go 错误目录继承与参数、手写 hook、自定义标量继续通过。
|
||
- 真实 nethttp/native 服务验证正常信号退出、根目录运行/构建、上传下载、原文回执、默认 404/405 及 Go 错误目录。临时项目、缓存、进程和端口已回收。
|
||
- 此报告单独提交；发布标签保持在上述代码提交，不改写标签。
|