跨平台开发 / 系统课时
设定可执行的质量门槛
设定可执行的质量门槛
质量门槛的价值不在于写一句“覆盖率要高”,而在于把要求变成自动检查:格式、静态分析、测试和覆盖率任何一项不达标,都用非零退出码阻止继续交付。本节会把这些条件组织成一套可在本地和 CI 共用的规则。
学习目标
- 把测试、静态分析和覆盖率要求转换成明确的通过条件
- 根据现有代码基线设定不会失真的覆盖率阈值
- 用一个可执行脚本验证质量门槛,并让失败返回非零退出码
把门槛写成可以失败的规则
可执行门槛必须回答两个问题:检查什么,以及失败时程序是否真的退出失败。Dart 项目常见的最小门槛可以由四部分组成:格式无差异、静态分析无问题、测试全部通过、行覆盖率不低于阈值。
其中前三项直接利用命令退出码即可。覆盖率则需要把测试生成的 LCOV 报告转换成一个百分比,再与阈值比较。只有所有检查都通过,脚本才返回成功;任意一步失败,后续交付流程应停止。

用脚本统一门槛
下面的脚本适用于 Linux、macOS 和常见 Linux CI Runner。项目需要已经在 dev_dependencies 中声明 test,脚本会让测试直接生成 coverage/lcov.info,再用 awk 汇总 LCOV 中的可执行行数 LF 与命中行数 LH。
把脚本保存为 tool/quality_gate.sh,并赋予执行权限。默认最低覆盖率为 80%,也可以通过环境变量 MIN_COVERAGE 调整。
#!/usr/bin/env bash
set -euo pipefail
MIN_COVERAGE="${MIN_COVERAGE:-80}"
dart format --output=none --set-exit-if-changed .
dart analyze --fatal-infos
dart run test --coverage-path=coverage/lcov.info
coverage_percent="$(
awk -F: '
/^LF:/ { total += $2 }
/^LH:/ { hit += $2 }
END {
if (total == 0) {
print "0.00"
} else {
printf "%.2f", hit * 100 / total
}
}
' coverage/lcov.info
)"
echo "line coverage: ${coverage_percent}% (minimum ${MIN_COVERAGE}%)"
awk -v actual="$coverage_percent" -v min="$MIN_COVERAGE" 'BEGIN { exit !(actual + 0 >= min + 0) }'
echo "quality gate passed"预期结果
当示例项目行覆盖率为 84.62% 且其他检查都通过时,格式、分析和测试会先输出各自日志;其中文件数、测试数和耗时随项目变化。脚本最后额外输出:
line coverage: 84.62% (minimum 80%)
quality gate passed若覆盖率只有 76.50%,第二个 awk 会返回非零退出码,因此不会打印 quality gate passed。格式、分析或测试失败时,set -e 也会让脚本在对应命令处立即失败。
从现有基线开始,而不是拍脑袋定数字
覆盖率阈值应该建立在当前代码事实之上。假设仓库当前稳定覆盖率约为 62.4%,直接把门槛设成 90% 只会让团队长期绕过检查;更实用的做法是先把阈值设为 62%,确保新提交不能把总体覆盖率继续拉低,再随着关键模块补测逐步提高。
门槛也不应只剩一个覆盖率数字。测试失败必须始终是硬失败;静态分析是否把 info 级问题也视为失败,则应与团队的 analysis_options.yaml 规则强度配套。使用 dart analyze --fatal-infos 时,info 级诊断也会让检查失败,因此启用前要先清理现有存量。
让门槛保持可维护
质量门槛最好只有一个权威入口。本地开发、预提交脚本和 CI 都调用同一份 tool/quality_gate.sh,就不会出现“本地过了,CI 用另一套规则失败”的漂移。
当业务代码大幅重构时,可以先测量新的稳定基线,再调整阈值;不要为了让单次提交变绿而临时下调。与此同时要定期检查 coverage/lcov.info 的统计范围,确认真正关心的源码被纳入报告。最终目标不是追求尽可能高的百分比,而是让每条门槛都能稳定阻止已知的质量退化。