跨平台开发 / 系统课时
在提交前执行质量检查
在提交前执行质量检查
代码进入仓库前,应尽早发现静态分析错误、格式偏差和测试失败。本节把 flutter analyze、dart format 与 flutter test 收敛到同一个检查入口,并让本地开发和 CI 复用相同规则,避免“本地能提交、流水线才失败”。
学习目标
- 组合静态分析、格式检查和自动化测试形成提交前检查链路
- 使用脚本保证任一检查失败时立即返回非零退出码
- 让本地执行与 CI 调用同一个质量检查入口
把三类检查收敛到一个入口
提交前检查最重要的不是命令数量,而是执行语义一致:分析失败、格式不符合规范或测试失败,都必须阻止后续提交或合并。可以在项目中创建 tool/check.sh,把规则集中管理。
#!/usr/bin/env bash
set -euo pipefail
flutter analyze >/dev/null
dart format --output=none --set-exit-if-changed . >/dev/null
flutter test >/dev/null
echo 'quality-check: passed'预期输出
quality-check: passed这里的输出只会在三个命令全部成功后出现。set -e 会让脚本在任一命令返回非零状态时立即终止;dart format --output=none --set-exit-if-changed . 只检查格式而不修改文件,因此更适合作为质量门禁。
理解检查顺序
建议按 analyze、format、test 的顺序执行。静态分析和格式检查通常比完整测试更快,可以先拦截低成本问题,再进入耗时更高的测试阶段。
flutter analyze 检查 Dart 分析错误以及项目启用的 lint 规则;格式检查保证仓库中不存在未格式化代码;flutter test 则验证行为是否仍满足测试断言。三者关注的问题不同,不能相互替代。
如果团队希望自动修正格式,可以在开发者主动执行的命令中使用 dart format .,但提交门禁更适合使用只检查、不改文件的方式。CI 不应悄悄修改源码后继续通过,否则仓库中的实际代码仍可能不符合约定。
在 CI 中复用同一脚本
CI 最容易出现的问题是重新复制一套命令,随后本地脚本和流水线逐渐产生差异。更稳妥的做法是让 CI 完成 Flutter 环境准备和依赖安装后,直接调用已经纳入版本控制的 tool/check.sh。下面以 GitHub Actions 为例。
name: quality-check
on:
pull_request:
push:
jobs:
quality:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: subosito/flutter-action@v2
with:
channel: stable
- run: flutter pub get
- run: bash tool/check.sh该配置在 push 和 pull request 时执行质量检查。如果 tool/check.sh 中任何命令返回非零状态,当前 job 会失败。验证时可以故意制造一个未格式化文件、分析错误或失败测试,确认流水线确实被对应步骤拦截,然后撤销测试改动。
避免提交检查变成形式主义
提交前质量检查应保持快速、确定并且可重复。不要在脚本里自动忽略分析错误,也不要用 || true 吞掉失败状态;否则命令虽然执行了,却失去了门禁作用。
本地 Git Hook 可以调用同一个脚本以便更早反馈,但 Hook 只能提升开发体验,不能取代 CI。开发者可以绕过或缺少本地 Hook,而受保护分支上的 CI 才是团队能够统一执行的最终检查点。