覆盖率差值门禁
整体覆盖率有两个问题：存量系统的历史包袱会让它长期偏低，而团队为了让数字好看，容易采取最省力的补测方式。覆盖率差值把范围限定在本次改动上：只看新增和修改的行是否被覆盖，未达阈值就要求补测。存量覆盖率同时保留，作为长期趋势跟踪，两者并行而不是互相替代。
口径要点
| 统计对象 | 变更集，即本次改动新增与修改的行 |
|---|---|
| 常见阈值 | 新代码覆盖不低于七成，关键模块更高 |
| 协同使用 | 与存量覆盖率的趋势报告并行 |
| 关键前提 | 对比基线正确，否则数值失真 |
典型使用场景
- 遗留项目引入门禁：不动存量，只要求新代码达到阈值，落地阻力小
- 大型 PR 评审：直接看变更集的未覆盖行，定位需要补测的具体位置
- 关键模块加严：计价、结算等模块单独设置更高阈值
- 覆盖率下滑归因：区分是新代码未覆盖还是存量被修改后失去覆盖
- 多分支协作：以目标分支为基线计算差值，避免把他人改动算入本次
流水线示意
流水线示意
# 先生成覆盖率数据，再只对变更集做判定
- run: coverage run -m pytest && coverage xml
- run: diff-cover coverage.xml --compare-branch=origin/main --fail-under=70
# 失败时输出未覆盖的变更行，直接定位到具体文件与行号常见误用与修正
| 误用 | 后果 | 修正 |
|---|---|---|
| 基线分支取错 | 把无关历史改动计入本次变更 | 确认对比分支与合并策略后再计算 |
| 阈值为百分之百 | 排除分支与生成代码后不可达 | 按模块设定可达阈值 |
| 未排除生成代码 | 生成文件拉低数值 | 在覆盖率配置中排除生成目录 |
| 只报数值不报位置 | 开发者不知道补哪里 | 报告输出未覆盖的变更行清单 |
| 与个人排名绑定 | 测试为数字而写 | 仅作为门禁与趋势输入 |
差值门禁的阈值要有基线依据：先用两到四周记录现状分布，再设一个略严于当前水平的目标，并定期重新校准，避免拍脑袋定下的阈值长期红灯。
差值门禁不能替代存量治理：如果长期只约束新代码，历史模块的缺口会一直存在。可行的组合是变更集设硬门槛，存量按模块排期，优先处理高频改动区域。
落地检查清单
- 对比基线明确，并在报告中写明
- 生成代码与第三方代码已排除
- 失败输出包含具体的未覆盖行
- 阈值有基线数据支撑，并按周期重新评估