跨平台开发 / 系统课时
逐步收紧遗留项目规则
逐步收紧遗留项目规则
遗留 Dart 项目往往已经积累了大量静态分析告警。正确目标不是一天内把所有规则都打开,而是先建立可量化基线,再按风险和修复成本分批收紧,确保每次规则升级都能被团队消化,同时让 CI 的质量门槛只会变严、不再反复回退。
学习目标
- 为已有告警的代码库设计可执行的分阶段治理路径
- 使用
analysis_options.yaml与dart analyze控制规则启用和 CI 严格度 - 为每一阶段定义进入下一阶段的验收条件,避免规则一次性升级
先把存量问题和新增约束分开
第一次治理不要直接启用大量严格规则。先在当前分支运行现有配置,记录诊断类型、数量和主要目录,再判断哪些问题会直接影响正确性,哪些主要约束代码风格。这样才能知道后续新增规则到底带来了多少额外工作,而不是把旧债和新债混在一起。
对 CI 来说,第一阶段可以继续分析整个包,但暂时不让 warning 决定失败;错误仍然必须处理。随后再恢复默认门槛,最后才把 info 级问题也纳入失败条件。这里控制的是门禁严格度,而不是用忽略注释掩盖问题。

让规则配置一次只前进一小步
假设项目已经使用 Dart 官方推荐规则集,可以把准备推广的额外规则显式写出来。尚未完成治理的规则先保持关闭,完成对应修复后再改为 true。这样代码评审能清楚看到本次到底新增了什么约束。
include: package:lints/recommended.yaml
linter:
rules:
always_declare_return_types: true
avoid_dynamic_calls: false
unawaited_futures: false这份配置的重点不是这三个规则本身,而是把临时关闭写成可追踪的治理清单。例如先处理返回类型,再单独提交 avoid_dynamic_calls: true,修完由它新增的诊断后,再启用 unawaited_futures。不要一次改十几个开关,否则失败时很难判断是哪组规则造成了回归。
分三档提升 CI 门禁
规则启用节奏和 CI 失败条件要分开控制。下面三条命令分别适用于不同治理阶段:第一条允许 warning 存量但仍阻止 error,第二条恢复常规分析门禁,第三条进一步让 info 级诊断也导致分析失败。
dart analyze --no-fatal-warnings
dart analyze
dart analyze --fatal-infos预期输出(当前包没有任何诊断时):
Analyzing <PATH>...
No issues found!
Analyzing <PATH>...
No issues found!
Analyzing <PATH>...
No issues found!<PATH> 会随当前包路径变化。这三条命令应作为三个阶段分别采用,而不是要求 CI 每次连续运行三遍。只有团队已经能稳定保持当前级别通过时,才值得进入更严格的下一档。
用验收条件决定何时升级
每个阶段都应有明确退出条件,而不是感觉差不多了。至少检查三件事:当前门禁能够持续通过、准备启用的规则已经完成批量修复、仍需保留的例外都有明确理由。满足后再提交下一次配置变更,并让变更本身保持小而可回滚。
如果升级 lints 依赖后突然出现大量新诊断,也不要为了恢复绿色状态而永久关闭整套规则。先确认新增或变化的诊断,再按相同方式拆成治理批次。对遗留项目来说,稳定提高约束强度比一次追求所有严格规则全部通过更可持续。