跨平台开发 / 系统课时
为小型项目补齐质量门禁
为小型项目补齐质量门禁
小型 Dart 项目最容易出现“代码能合并,但格式、静态问题或关键逻辑已经悄悄退化”。这一节把关键单元测试、格式检查、静态分析和覆盖率阈值串成同一套门禁,并接入持续集成,让失败直接阻断提交进入主分支。
学习目标
- 为核心业务分支补上能防回归的单元测试。
- 用退出码统一格式、静态分析、测试和覆盖率四类检查。
- 把本地验证命令接入 GitHub Actions,并能根据失败阶段定位问题。
先补最值得保护的行为
覆盖率不是先追数字,而是先保护最容易造成业务回归的分支。假设项目有折扣计算逻辑,正常折扣、边界值和非法输入都属于应优先锁定的行为。
lib/discount.dart:
double discountedPrice(double price, double rate) {
if (price < 0) {
throw ArgumentError.value(price, 'price', 'must be non-negative');
}
if (rate < 0 || rate > 1) {
throw ArgumentError.value(rate, 'rate', 'must be between 0 and 1');
}
return price * (1 - rate);
}test/discount_test.dart:
import 'package:test/test.dart';
import 'package:quality_gate_demo/discount.dart';
void main() {
group('discountedPrice', () {
test('applies a normal discount', () {
expect(discountedPrice(100, 0.2), closeTo(80, 0.0001));
});
test('allows the boundary rates', () {
expect(discountedPrice(100, 0), 100);
expect(discountedPrice(100, 1), 0);
});
test('rejects an invalid rate', () {
expect(() => discountedPrice(100, 1.2), throwsArgumentError);
});
});
}运行这组测试:
dart test --reporter expanded test/discount_test.dart预期输出:
<TIME> +0: loading test/discount_test.dart
<TIME> +1: discountedPrice applies a normal discount
<TIME> +2: discountedPrice allows the boundary rates
<TIME> +3: discountedPrice rejects an invalid rate
<TIME> +3: All tests passed!其中 <TIME> 会随机器和缓存状态变化;门禁真正依赖的是命令最终退出码为 0。
把覆盖率阈值变成可执行检查
测试全部通过,并不代表关键代码已经被充分执行。下面用 LCOV 中的 LF 与 LH 汇总行数计算行覆盖率:LF 是可覆盖行数,LH 是已命中行数。脚本低于阈值时主动返回非零退出码。
创建 tool/check_coverage.dart:
import 'dart:io';
void main(List<String> args) {
if (args.length != 2) {
stderr.writeln('Usage: dart run tool/check_coverage.dart <lcov> <minimum>');
exitCode = 64;
return;
}
final threshold = double.tryParse(args[1]);
if (threshold == null || threshold < 0 || threshold > 100) {
stderr.writeln('minimum must be a number from 0 to 100');
exitCode = 64;
return;
}
final file = File(args[0]);
if (!file.existsSync()) {
stderr.writeln('coverage file not found: ${args[0]}');
exitCode = 66;
return;
}
var found = 0;
var hit = 0;
for (final line in file.readAsLinesSync()) {
if (line.startsWith('LF:')) {
found += int.parse(line.substring(3));
} else if (line.startsWith('LH:')) {
hit += int.parse(line.substring(3));
}
}
if (found == 0) {
stderr.writeln('no line coverage data found');
exitCode = 65;
return;
}
final percent = hit * 100 / found;
stdout.writeln(
'line coverage: ${percent.toStringAsFixed(2)}% ($hit/$found)',
);
if (percent < threshold) {
stderr.writeln('coverage is below the required ${threshold.toStringAsFixed(2)}%');
exitCode = 1;
}
}以 80% 为最低线,在项目根目录执行完整本地门禁:
dart format -o none --set-exit-if-changed .
dart analyze --fatal-infos
dart run test --coverage-path=coverage/lcov.info
dart run tool/check_coverage.dart coverage/lcov.info 80预期结果:
All tests passed!
line coverage: <COVERAGE>% (<HIT>/<FOUND>)当 <COVERAGE> 不低于 80.00 时四条命令均应以退出码 0 结束;任意一步失败都应视为门禁失败,而不是继续执行发布或合并流程。

接入持续集成
本地命令已经能用退出码表达成功或失败,CI 只需要按相同顺序执行。以 GitHub Actions 为例,在 .github/workflows/quality.yml 中配置:
name: quality-gate
on:
push:
pull_request:
jobs:
quality:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: dart-lang/setup-dart@v1
- name: Install dependencies
run: dart pub get
- name: Check formatting
run: dart format -o none --set-exit-if-changed .
- name: Analyze
run: dart analyze --fatal-infos
- name: Test with coverage
run: dart run test --coverage-path=coverage/lcov.info
- name: Enforce coverage
run: dart run tool/check_coverage.dart coverage/lcov.info 80这段配置的关键不是 CI 平台本身,而是复用与本地完全相同的门禁命令。某一步返回非零退出码后,作业会失败,后续交付步骤就不应继续。
验证方法是推送一个测试分支并查看 quality 作业:正常提交应全部通过;再故意把一个已格式化文件改乱、制造 analyzer 问题、让测试失败或把覆盖率降到阈值以下,确认对应步骤确实变红并阻断作业。
让门槛服务于回归风险
质量门禁需要足够严格,但不应为了数字制造脆弱测试。覆盖率阈值应覆盖核心业务路径,同时把无意义的 getter、生成代码或难以稳定测试的边缘层按项目规则处理;新增代码则优先要求测试跟随变更一起进入仓库。
当门禁失败时,按“格式 → 静态分析 → 测试 → 覆盖率”的顺序处理最省时间:前两类通常是确定性的代码问题,测试失败要先确认行为是否真的回归,最后再判断覆盖率下降是遗漏测试还是代码结构需要重构。这样,小型项目也能用一条清晰的证据链决定一次变更是否具备合并条件。