dart-run-static-analysis

目录

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

分析配置

在 Dart 包的根目录中配置 analysis_options.yaml，以强制执行严格的格式规范、整洁的代码风格和健全的代码：

• 继承 Lint 规则：使用 include 指令继承一套推荐的基础规则。纯 Dart 包建议使用 package:lints/recommended.yaml，Flutter 应用建议使用 package:flutter_lints/flutter.yaml。
• 严格类型检查：在 analyzer: language: 配置中显式声明严格静态类型，以消除不安全的动态类型：

  analyzer:
    language:
      strict-casts: true
      strict-inference: true
      strict-raw-types: true
  

• 自定义 Linter 规则：在 linter: rules: 下自定义特定规则。覆盖继承的配置时，使用映射键结构（rule_name: true/false）显式启用或停用规则。
• 自动格式化选项：在 formatter: 节点下声明格式化参数（例如，配置 page_width: 80）。

诊断抑制规则

当分析器警告或风格 Lint 产生误报，或命中生成的文件时，请使用以下策略之一显式抑制警告：

• 排除筛选器：使用标准 glob 模式，在 analyzer: exclude: 列表中将整个文件或目录树（例如，生成的 JSON 模型或国际化文件）排除在分析之外：

  analyzer:
    exclude:
      - "lib/generated/**"
      - "**/*.g.dart"
  

• 文件级抑制：在 Dart 文件绝对顶部的专用行中添加 // ignore_for_file: diagnostic_name，以停用整个文件范围内的特定规则。
• 行级抑制：在目标语句的上一行添加 // ignore: diagnostic_name，或将其追加到匹配行的末尾。
• Pubspec 抑制：在 pubspec.yaml 中添加注释，以抑制包依赖项警告（例如 # ignore: sort_pub_dependencies）。

工作流：运行静态分析

按照以下清单执行静态代码审查：

• 设置分析配置：确保项目根目录中存在 analysis_options.yaml。
• 运行分析：在终端中运行分析器：

  dart analyze .
  

• 将提示升级为致命错误：在 CI/CD 工作流中，追加致命错误标志，确保信息级 Lint 导致构建失败：

  dart analyze . --fatal-infos
  

• 分类处理诊断：检查警告，修正类型层次结构或未使用的变量，或酌情应用抑制规则。

工作流：应用自动代码修复

按照以下清单自动应用机械式快速修复：

• 验证 Lint 规则：确认目标 Linter 规则已在 analysis_options.yaml 中启用。
• 试运行检查：运行试运行，检查建议的机械式修改：

  dart fix --dry-run
  

• 应用修复：在整个工作区中直接应用快速修复：

  dart fix --apply
  

• 格式化代码：格式化已修改的代码文件：

  dart format .
  

• 重新运行分析：确认 dart analyze 报告结果无问题。

示例

完整的 analysis_options.yaml 模板

include: package:lints/recommended.yaml

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

linter:
  rules:
    always_declare_return_types: true
    avoid_empty_else: true
    prefer_const_constructors: true
    sort_pub_dependencies: false

formatter:
  page_width: 100
  trailing_commas: preserve

行内抑制技巧

// 1. Suppress all instances of unused variables inside this specific file
// ignore_for_file: unused_local_variable

void calculateMetrics() {
  // 2. Suppress a single line using a preceding comment ignore
  // ignore: invalid_assignment
  int x = 'not_an_int';

  final unusedString = 'value'; // File-level ignore handles this
  
  // 3. Suppress at the end of the line
  final double pi = 3.14; // ignore: constant_identifier_names
}