跨平台开发 / 系统课时

逐步收紧遗留项目规则

逐步收紧遗留项目规则

遗留 Dart 项目往往已经积累了大量静态分析告警。正确目标不是一天内把所有规则都打开,而是先建立可量化基线,再按风险和修复成本分批收紧,确保每次规则升级都能被团队消化,同时让 CI 的质量门槛只会变严、不再反复回退。

学习目标

  • 为已有告警的代码库设计可执行的分阶段治理路径
  • 使用 analysis_options.yaml 与 dart analyze 控制规则启用和 CI 严格度
  • 为每一阶段定义进入下一阶段的验收条件,避免规则一次性升级

先把存量问题和新增约束分开

第一次治理不要直接启用大量严格规则。先在当前分支运行现有配置,记录诊断类型、数量和主要目录,再判断哪些问题会直接影响正确性,哪些主要约束代码风格。这样才能知道后续新增规则到底带来了多少额外工作,而不是把旧债和新债混在一起。

对 CI 来说,第一阶段可以继续分析整个包,但暂时不让 warning 决定失败;错误仍然必须处理。随后再恢复默认门槛,最后才把 info 级问题也纳入失败条件。这里控制的是门禁严格度,而不是用忽略注释掩盖问题。

遗留项目静态分析逐步收紧路线

让规则配置一次只前进一小步

假设项目已经使用 Dart 官方推荐规则集,可以把准备推广的额外规则显式写出来。尚未完成治理的规则先保持关闭,完成对应修复后再改为 true。这样代码评审能清楚看到本次到底新增了什么约束。

yaml
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 级诊断也导致分析失败。

bash
dart analyze --no-fatal-warnings
dart analyze
dart analyze --fatal-infos

预期输出(当前包没有任何诊断时):

text
Analyzing <PATH>...
No issues found!
Analyzing <PATH>...
No issues found!
Analyzing <PATH>...
No issues found!

<PATH> 会随当前包路径变化。这三条命令应作为三个阶段分别采用,而不是要求 CI 每次连续运行三遍。只有团队已经能稳定保持当前级别通过时,才值得进入更严格的下一档。

用验收条件决定何时升级

每个阶段都应有明确退出条件,而不是感觉差不多了。至少检查三件事:当前门禁能够持续通过、准备启用的规则已经完成批量修复、仍需保留的例外都有明确理由。满足后再提交下一次配置变更,并让变更本身保持小而可回滚。

如果升级 lints 依赖后突然出现大量新诊断,也不要为了恢复绿色状态而永久关闭整套规则。先确认新增或变化的诊断,再按相同方式拆成治理批次。对遗留项目来说,稳定提高约束强度比一次追求所有严格规则全部通过更可持续。

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

目录与阅读设置

阅读设置

17

记录一个想法

逐步收紧遗留项目规则

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

登录哪都通