go-omni/performance/lifecycleEndpointsAcceptance.md

依赖主动退出与内置接口配置验收

日期：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 不包装公共体。

源码与实际生成项目

回归命令：

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 上传、流式下载、初始化/监听失败清理、业务文件保留和生成漂移检查。
• 本地真实进程报告 最近一轮通过，耗时 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 在 svc 增加 Lifecycle、RequestShutdown 和清理衔接；main/Handler 由生成器自动更新。新项目直接获得这些扩展。

请求排空使用已有 shutdownTimeout；忽略 context 的业务 goroutine 无法被框架强制结束，项目 Close 必须停止并等待自建监控任务。内置接口继续经过全局中间件，访问规则由项目设置。

没有修改 eTax/ePay，也未连接业务服务器、真实数据库或云存储。所有服务与子进程均在本地临时环境验收并回收；本轮不是压力测试或业务迁移验收。

远程安装验收在不可变标签发布后执行，报告单独提交，不改写标签。