跨平台开发 / 系统课时

为小型项目补齐质量门禁

为小型项目补齐质量门禁

小型 Dart 项目最容易出现“代码能合并,但格式、静态问题或关键逻辑已经悄悄退化”。这一节把关键单元测试、格式检查、静态分析和覆盖率阈值串成同一套门禁,并接入持续集成,让失败直接阻断提交进入主分支。

学习目标

  • 为核心业务分支补上能防回归的单元测试。
  • 用退出码统一格式、静态分析、测试和覆盖率四类检查。
  • 把本地验证命令接入 GitHub Actions,并能根据失败阶段定位问题。

先补最值得保护的行为

覆盖率不是先追数字,而是先保护最容易造成业务回归的分支。假设项目有折扣计算逻辑,正常折扣、边界值和非法输入都属于应优先锁定的行为。

lib/discount.dart:

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:

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);
    });
  });
}

运行这组测试:

bash
dart test --reporter expanded test/discount_test.dart

预期输出:

text
<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:

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% 为最低线,在项目根目录执行完整本地门禁:

bash
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

预期结果:

text
All tests passed!
line coverage: <COVERAGE>% (<HIT>/<FOUND>)

当 <COVERAGE> 不低于 80.00 时四条命令均应以退出码 0 结束;任意一步失败都应视为门禁失败,而不是继续执行发布或合并流程。

质量门槛从检查到通过或阻断的流程

接入持续集成

本地命令已经能用退出码表达成功或失败,CI 只需要按相同顺序执行。以 GitHub Actions 为例,在 .github/workflows/quality.yml 中配置:

yaml
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、生成代码或难以稳定测试的边缘层按项目规则处理;新增代码则优先要求测试跟随变更一起进入仓库。

当门禁失败时,按“格式 → 静态分析 → 测试 → 覆盖率”的顺序处理最省时间:前两类通常是确定性的代码问题,测试失败要先确认行为是否真的回归,最后再判断覆盖率下降是遗漏测试还是代码结构需要重构。这样,小型项目也能用一条清晰的证据链决定一次变更是否具备合并条件。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

为小型项目补齐质量门禁

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通