dart-run-static-analysis

Dart 代码静态分析与自动修复

目录

• 分析配置
• 诊断忽略
• 工作流：执行静态分析
• 工作流：应用自动修复
• 示例

分析配置

通过项目根目录下的 analysis_options.yaml 文件配置 Dart 分析器。

• 基础配置： 务必使用 include: 指令引入标准规则集（例如 package:lints/recommended.yaml 或 package:flutter_lints/flutter.yaml）。
• 严格类型检查： 在 analyzer: language: 节点下开启严格类型检查，防止隐式向下类型转换（downcast）和 dynamic 类型推断。请设置 strict-casts: true、strict-inference: true 和 strict-raw-types: true。
• Linter 规则： 在 linter: rules: 节点下显式开启或禁用特定规则。重写已包含的规则时请使用键值对 Map 语法（rule_name: true/false）；定义全新规则集时可使用列表 List 语法（- rule_name）。切勿在同一个 rules 块中混合使用列表与 Map 语法。
• 格式化配置： 在 formatter: 节点下配置 dart format 的行为。可设置 page_width（默认 80）和 trailing_commas（automate 或 preserve）。
• 分析器插件： 在 analyzer: plugins: 节点下添加插件以开启自定义诊断规则。同时确保已将插件包添加至 pubspec.yaml 的 dev_dependencies 中。

诊断忽略

当诊断结果（lint 规则或警告）出现误报，或适用于自动生成的代码时，可以显式进行忽略处理。

• 文件级排除： 在 analysis_options.yaml 的 analyzer: exclude: 节点中使用 Glob 匹配模式排除整份文件或目录（例如 **/*.g.dart）。
• 文件级诊断忽略： 在 Dart 文件顶部添加 // ignore_for_file: <diagnostic_code>，即可忽略整份文件中的特定诊断提示。使用 // ignore_for_file: type=lint 可忽略所有 linter 规则。
• 行级诊断忽略： 在问题代码的正上方一行添加 // ignore: <diagnostic_code>，或直接追加在该行代码末尾。
• Pubspec 诊断忽略： 在 pubspec.yaml 文件中问题代码行的上方添加 # ignore: <diagnostic_code>（例如 # ignore: sort_pub_dependencies）。
• 插件诊断忽略： 忽略插件专属的提示时，诊断代码前需加上插件名作为前缀（例如 // ignore: some_plugin/some_code）。

工作流：执行静态分析

使用此工作流排查类型相关的 Bug、代码风格违规以及潜在的运行时错误。

任务进度：

• [ ] 1. 确认项目根目录下存在 analysis_options.yaml。
• [ ] 2. 使用 analyze_files MCP 工具（若可用）或 CLI 命令 dart analyze <target_directory> 运行分析器。
• [ ] 3. 检查诊断输出结果。
• [ ] 4. 若需要将 Info 级别的提示视为错误拦截，请加上 --fatal-infos 标志。
• [ ] 5. 手动修复报告的错误，或进入“应用自动修复”工作流。

工作流：应用自动修复

使用此工作流清理废弃 API、应用 Quick Fix 快捷修复以及进行代码迁移（例如 Dart 3 升级迁移）。

任务进度：

• [ ] 1. 使用 dart_fix MCP 工具或 CLI 命令 dart fix --dry-run 进行预演（dry run），预览拟修改的内容。
• [ ] 2. 审查建议的修复方案，确保符合既定的代码架构设计。
• [ ] 3. 若需要自动修复更多问题，请检查 analysis_options.yaml 中是否已开启对应的 linter 规则。
• [ ] 4. 使用 dart_fix MCP 工具或 CLI 命令 dart fix --apply 正式应用修复。
• [ ] 5. 使用 dart_format MCP 工具或 CLI 命令 dart format . 格式化修改后的代码。
• [ ] 6. 重新运行“静态分析”工作流，确认所有诊断问题均已解决。

示例

完整的 analysis_options.yaml 示例

include: package:flutter_lints/recommended.yaml

analyzer:
  exclude:
    - "**/*.g.dart"
    - "lib/generated/**"
  language:
    strict-casts: true
    strict-inference: true
    strict-raw-types: true
  errors:
    todo: ignore
    invalid_assignment: warning
    missing_return: error

linter:
  rules:
    avoid_shadowing_type_parameters: false
    await_only_futures: true
    use_super_parameters: true

formatter:
  page_width: 100
  trailing_commas: preserve

行内诊断忽略示例

// 忽略整份文件中的特定诊断提示
// ignore_for_file: unused_local_variable, dead_code

void processData() {
  // 忽略特定行的诊断提示
  // ignore: invalid_assignment
  int x = '';
  
  const y = 10; // ignore: constant_identifier_names
}