[meta] 架构审查整改清单：配置、路由、OpenAPI 与生命周期 #98

范围

跟踪 2026-09-13 对 Gotcha commit 4aa39cf134acfeb86f681614ff940fab5016df96 的架构审查。保留两套用户入口，优先解决配置、路由元数据与运行生命周期的职责边界。每项通过独立 PR 推进；截至 2026-09-14，本轮 13 个工作项及追加的 #108 均已完成并由用户合入。

本轮新增 10 个问题 issue，并复用 3 个现有 issue；现有条目已补充此次复现证据。共 13 个工作项，含较低优先级的冗余封装评估。

建议 PR 顺序

顺序	工作项	关注点
1	#88	显式文档端点、全应用 middleware 与无 HTTP 导出（同时解决 #77）；PR #115 已合入，本地验证及 11 项 GitHub CI 检查全部通过
2	#89	P1：配置来源保存无损，保留顺序与 required；PR #99 已合入，11 项 CI 检查通过
3	#79	P1：schema 类型身份、泛型实例冲突与确定性；PR #102 已合入，11 项 CI 检查通过
4	#80	嵌套路径与实际 HTTP 路由一致；PR #103 已合入，11 项 CI 通过
5	#90	应用组合与路由组合边界；PR #106 已合入，11 项 CI 检查通过
6	#91	子路由和重复调用的 OpenAPI transform 语义；PR #104 已合入，11 项 CI 检查通过
7	#97	route(MethodRouter) 与 handler 元数据注册边界；PR #105 已合入，11 项 CI 检查通过
8	#76	数据 schema 与 HTTP 响应状态/媒体类型解耦；PR #107 已合入，11 项 CI 检查通过
9	#94	Default、serde 约束下放到实际使用边界；PR #110 已合入，本地验证通过，11 项 GitHub CI 检查全部通过
10	#92	共享启动流程，统一监听地址优先级及配置严格度；PR #111 已合入，本地验证及 11 项 GitHub CI 检查全部通过
11	#93	后台任务所有权、取消与退出等待；PR #112 已合入，本地验证及 11 项 GitHub CI 检查全部通过
12	#95	精简宏生成描述符的 Lazy/Box/Vec；PR #113 已合入，本地验证、前后文档等价对比及 11 项 GitHub CI 检查全部通过
13	#96	保留类型化命令封装，spawn 返回任务句柄并明确取消/关闭边界；PR #114 已合入，本地验证及 11 项 GitHub CI 检查全部通过

完成清单

• [P1][openapi] 分离文档生成与端点挂载，明确中间件覆盖范围 #88
• [P1][config] ConfigState 重建丢失必需文件标志并改变来源覆盖顺序 #89
• [openapi] Components are keyed by the bare Rust type name, and assembly order is random #79
• [openapi] nest() records every nested route with a doubled slash #80
• [P2][builder] nest/merge 接收完整应用却静默丢弃子应用状态、配置和任务 #90
• [P2][openapi] 为 nest/merge 和重复 openapi 调用定义 transform 组合规则 #91
• [P2][router] route(MethodRouter) 静默绕过已标注 handler 的 OpenAPI 元数据 #97
• [openapi] A handler cannot declare its own status codes or content types #76
• [P2][types] 将 Default 与配置序列化约束下放到实际需要的方法 #94
• [P2][app] 统一 Builder 与 Trait 的配置解析、地址优先级和启动流程 #92
• [P2][task] 让应用运行实例持有后台任务并负责取消与退出等待 #93
• [P3][macro] 精简 Operable 生成中的 Lazy、Vec 和动态闭包封装 #95
• [P3][message] 明确 Message/Messager 的职责并评估是否保留为核心封装 #96

边界与依赖

• [P1][config] ConfigState 重建丢失必需文件标志并改变来源覆盖顺序 #89 的配置表示应先于 [P2][app] 统一 Builder 与 Trait 的配置解析、地址优先级和启动流程 #92 的启动策略整合；[P2][types] 将 Default 与配置序列化约束下放到实际需要的方法 #94 的运行时约束设计也应纳入 [P2][app] 统一 Builder 与 Trait 的配置解析、地址优先级和启动流程 #92。
• [P2][task] 让应用运行实例持有后台任务并负责取消与退出等待 #93 与既有 [lifecycle] No graceful shutdown, no lifecycle hooks, and run() hides the bound address #82 的服务器 shutdown/prepare 接口协同，避免各自添加取消机制。
• [P1][openapi] 分离文档生成与端点挂载，明确中间件覆盖范围 #88 与既有 [openapi] The assembled spec is unreachable without an HTTP request #77 的无 HTTP 文档导出接口协同。
• [P2][builder] nest/merge 接收完整应用却静默丢弃子应用状态、配置和任务 #90、[P2][openapi] 为 nest/merge 和重复 openapi 调用定义 transform 组合规则 #91 与 [openapi] nest() records every nested route with a doubled slash #80 分别跟踪应用字段、文档变换和路径，避免一个 PR 混入所有组合问题。
• [openapi] A handler cannot declare its own status codes or content types #76/[openapi] Components are keyed by the bare Rust type name, and assembly order is random #79/[openapi] nest() records every nested route with a doubled slash #80 沿用原 issue；新增复现不会取代原有验收需求。
• [P3][message] 明确 Message/Messager 的职责并评估是否保留为核心封装 #96 是待决策设计问题，不预设必须删除，也不预设要增加队列、背压或重试。

验证依据

9 项最小行为复现已在临时外部 Rust 工程引用本地源码实际运行：

1. 配置 state 重建丢失必需文件语义。
2. 配置 state 重建逆转 file/env 覆盖优先级。
3. Envelope/Envelope 合并成一个组件。
4. 嵌套实际路径 /api/hello 与文档 /api//hello 不同。
5. 业务 middleware 返回 401 时自动文档端点仍返回 200。
6. merge 丢弃子 router 的 openapi transform。
7. route(MethodRouter) 缺失已有 #[api] handler 元数据。
8. String 实际 text/plain，但 Responsible 文档为 application/json。
9. drop scheduler 后 interval 任务继续执行。

上述复现记录的是审查基线中的问题；对应修复已在各 PR 中以回归测试或等价性验证确认。其余条目的设计决策及验证结果见关联 PR。

PR 工作约定

• 逐项提出 PR，描述触发场景、行为变化、验证结果及兼容迁移。
• 每个 PR 关联对应 issue，完成相应验收后更新清单。
• 测试或 CI 通过不构成合入授权；仅在用户明确授权当前 PR 时合入。
• 有适用部署环境时可使用 PR 产物验证，无须先合入。

后续发现

• [api] 显式声明接口错误响应时免除错误类型的 Responsible 要求 #108：接口显式接管错误响应文档，保留成功推导并免除错误类型的 Responsible 要求；PR fix(openapi)!: describe HTTP response contracts independently of schemas #107 后续，PR feat(openapi): declare endpoint errors without Responsible #109 已合入；本地验证通过，11 项 GitHub CI 检查全部通过。

本轮完成

最后一项 PR #115 已于 2026-09-14 合入（90e0efeff99ebcd032f054193cf632bafb5e5a95），本清单关闭为 completed。仓库其他既有 issue 继续独立跟踪，不属于本轮已完成范围。