dart-run-static-analysis

分析和修复 Dart 代码

目录

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

分析配置

使用包根目录下的 analysis_options.yaml 文件配置 Dart 分析器。

• 基础配置： 始终使用 include: 指令引入一套标准规则集（例如 package:lints/recommended.yaml 或 package:flutter_lints/flutter.yaml）。
• 严格类型检查： 在 analyzer: language: 节点下启用严格类型检查，以防止隐式向下转型和动态类型推断。将 strict-casts: true、strict-inference: true 和 strict-raw-types: true 设为启用。
• Linter 规则： 在 linter: rules: 节点下显式启用或禁用特定规则。覆盖已引入的规则时，使用键值映射（rule_name: true/false）；定义一组全新的规则时，使用列表（- rule_name）。同一个 rules 块中不要混用列表和映射语法。
• 格式化程序配置： 在 formatter: 节点下配置 dart format 的行为。设置 page_width（默认值为 80）和 trailing_commas（automate 或 preserve）。
• 分析器插件： 在 analyzer: plugins: 节点下添加插件，以启用自定义诊断。确保在 pubspec.yaml 中将插件包添加为 dev_dependency。

抑制诊断

当诊断（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）。

工作流：执行静态分析

使用此工作流识别与类型相关的错误、风格违规以及潜在的运行时错误。

任务进度：

• 1. 确认项目根目录下存在 analysis_options.yaml。
• 2. 使用 analyze_files MCP 工具（如果可用）或 CLI 命令 dart analyze <target_directory> 运行分析器。
• 3. 检查诊断输出。
• 4. 如果必须将 info 级问题视为失败，则添加 --fatal-infos 标志。
• 5. 手动解决报告的问题，或继续执行自动修复工作流。

工作流：应用自动修复

使用此工作流解决过时的 API 用法、应用快速修复并迁移代码（例如 Dart 3 迁移）。

任务进度：

• 1. 使用 dart_fix MCP 工具或 CLI 命令 dart fix --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

行内诊断抑制

// Suppress for the entire file
// ignore_for_file: unused_local_variable, dead_code

void processData() {
  // Suppress for a specific line
  // ignore: invalid_assignment
  int x = '';
  
  const y = 10; // ignore: constant_identifier_names
}