测试覆盖率、静态检查与质量门禁集成

质量门禁是"达到什么条件才允许继续/合入"的确定性检查集合。代理负责高效生成与自检，门禁负责用客观信号拦截低质量改动。本节讲分层门禁设计、代理如何配合通过检查，以及避免"为覆盖率数字写无效测试"的反注水原则。

一、门禁的四个层次

层次	典型检查	运行时机
本地快速层	格式、lint、类型检查、快速单元测试	实现过程中频繁运行，及早反馈
构建与单测层	可重复构建、核心单元测试、关键工具函数用例	提交/推送前
集成与冒烟层	跨模块/服务的关键路径、契约或冒烟检查	合并前、自动化流水线中
人工审查层	设计合理性、安全敏感点、测试有效性复核	合并决策前

二、让代理"带着门禁实现"

1. 开工先确认可用检查命令（测试、构建、静态检查），把退出码作为成功标准，而非口头"应该可以了"。
2. 要求代理在修改后运行相关检查，依据失败输出迭代到通过；把失败现象、修复与结果记录清楚。
3. 新增逻辑配套测试：覆盖正常路径、边界条件、异常分支与回归场景；修复缺陷先补能复现问题的回归用例。
4. 门禁失败时先修根因，不靠删除检查、放宽断言或跳过用例来"变绿"。

三、有效测试的判断标准

• 断言有意义：验证真实输出与状态，而不是只调用函数不校验结果。
• 覆盖失败路径：异常、空值、非法输入与边界值同样被检验。
• 不重复实现逻辑：测试应固化外部行为契约，避免把实现细节照抄进断言导致脆弱。
• 回归用例可复现：先复现旧缺陷、再验证修复，用例名称说明保护意图。
• 避免脆弱快照：对易变输出谨慎使用整体快照，聚焦稳定契约。

四、覆盖率与度量的正确用法

• 覆盖率是发现"未被执行代码"的线索，不是质量本身；高覆盖也可能伴随弱断言与漏测分支。
• 优先关注核心业务路径、错误处理与历史缺陷区的覆盖，而非平均数字达标。
• 记录门禁通过率、回归缺陷数与检查耗时趋势，用于发现质量退化，而非制造指标游戏。
• 无人值守自动化（第 10 章）定位为建议与小修；合并级门禁由稳定的自动化流水线与人工决策把关。

五、门禁失效的常见原因

• 检查命令不可重复、依赖人工环境，导致结果不可信。
• 门禁只跑最容易通过的浅层检查，漏掉集成与安全风险。
• 为赶进度临时跳过关键检查且未补回，债务累积。
• 测试与实现同步漂移，断言失去保护价值。