dart-static-analysis

Dart コードの解析と lint

目次

• 解析オプションの設定
• Linter ルールの管理
• 型昇格の失敗を解決する
• ワークフロー：静的解析のセットアップと実行
• ワークフロー：型昇格の修正
• 例

解析オプションの設定

パッケージのルートに analysis_options.yaml ファイルを配置して、静的解析を制御します。

• 厳密な型チェックを有効にする： コンパイル時に暗黙的な dynamic キャストや型が推論されていない箇所を検出するため、analyzer セクションで strict-casts、strict-inference、strict-raw-types を常に有効にします。
• フォーマットを設定する： formatter セクション内で dart format のルールを定義します（例：page_width や trailing_commas）。
• 生成コードを除外する： 生成ファイル（例：**/*.g.dart、**/*.freezed.dart）を無視するには exclude キーを使い、誤検出を防ぎます。

Linter ルールの管理

独自のルール一覧を管理するのではなく、コミュニティ標準のルールセットを利用します。

• 標準パッケージを使う： 純粋な Dart プロジェクトでは package:lints/recommended.yaml を、Flutter プロジェクトでは package:flutter_lints/flutter.yaml を含めます。
• 手動での無視を避ける： 絶対に必要な場合を除き、lint を手動で無視すること（例：// ignore: ...）は避けます。lint の根本原因を修正することを優先します。
• 一括修正： コードベース全体にわたる一般的な lint 違反や移行の問題を自動的に解決するには、dart fix --apply を使います。
• 重大度をカスタマイズする： 特定のルールの通知が多すぎるものの有用性がある場合は、完全に無効にするのではなく、errors マップで重大度を変更します（例：todo: info）。

型昇格の失敗を解決する

フロー解析によって nullable 変数が null ではないと確認された場合、型昇格が発生します。チェックと使用の間で値が安定していることをコンパイラーが保証できない場合、型昇格は失敗します。

型昇格が失敗する一般的な原因は次のとおりです。

1. 公開フィールドまたは final ではないフィールド： 外部ライブラリによって公開フィールドがオーバーライドされる可能性があり、final ではないフィールドは変更される可能性があります。
2. ゲッター： ゲッターが呼び出されるたびに同じ値を返すことをコンパイラーが保証できません。
3. 書き込みキャプチャ： クロージャまたは関数式内で変数が変更されると、それまでのチェックが無効になります。

解決策： 「型昇格しない」理由を解決するには、null チェックまたは型チェックを行う前に、フィールド、ゲッター、またはキャプチャされた変数をローカルな final 変数に代入します。ローカル変数は安定していることが保証されるため、コンパイラーは安全に型を昇格できます。

ワークフロー：静的解析のセットアップと実行

このチェックリストを使って、Dart プロジェクトで静的解析を初期化し、徹底します。

• タスクの進捗：解析のセットアップ
  • dart pub add --dev lints（または flutter_lints）を実行します。
  • プロジェクトのルートに analysis_options.yaml を作成します。
  • 推奨ルールセットを含めます（include: package:lints/recommended.yaml）。
  • 厳密な言語モード（strict-casts、strict-inference、strict-raw-types）を有効にします。
• タスクの進捗：実行と修正
  • dart analyze を実行して、潜在的なバグやスタイル違反を早期に検出します。
  • dart fix --apply を実行して、機械的に修正できる lint の問題を自動的に解決します。
  • 残りのエラーを手動で確認します。バリデーターを実行 -> エラーを確認 -> // ignore を使わずに根本原因を修正します。

型の昇格を修正するワークフロー

dart analyze でプロパティまたはフィールドを昇格できないと報告された場合：

• タスクの進捗：昇格の修正
  • 問題が発生している変数を特定します（例：パブリックフィールド、ゲッター、または書き込みによってキャプチャされた変数）。
  • 条件チェックの直前で、ローカルの final 変数を宣言します。
  • 昇格できないフィールドまたはゲッターを、新しいローカル変数に代入します。
  • ローカル変数に対して != null または is Type のチェックを行います。
  • 条件ブロック内のすべての参照を、ローカル変数を使うように更新します。
  • dart analyze を実行し、昇格の問題が解決したことを確認します。

例

高忠実度の analysis_options.yaml

include: package:lints/recommended.yaml

analyzer:
  exclude:
    - "**/*.g.dart"
    - "**/*.freezed.dart"
  language:
    strict-casts: true
    strict-inference: true
    strict-raw-types: true
  errors:
    todo: info
    invalid_assignment: error

formatter:
  page_width: 80
  trailing_commas: preserve

linter:
  rules:
    # Disable specific rules if they conflict with project architecture
    avoid_classes_with_only_static_members: false
    # Enable additional strict rules
    always_declare_return_types: true
    cancel_subscriptions: true

ローカル変数による型の昇格の修正

アンチパターン： ゲッターまたはパブリックフィールドを直接チェックします。_value はゲッターであり、2回目の呼び出しで異なる結果を返す可能性があるため、コンパイラーはエラーを出します。

abstract class Example {
  int? get _value => Random().nextBool() ? 123 : null;
}

void printParity(Example x) {
  if (x._value != null) {
    // ERROR: '_value' refers to a getter so it couldn't be promoted.
    print(x._value.isEven); 
  }
}

ベストプラクティス： ローカルの final 変数に代入して、値が安定するようにします。

abstract class Example {
  int? get _value => Random().nextBool() ? 123 : null;
}

void printParity(Example x) {
  final localValue = x._value; // 1. Assign to local final variable
  
  if (localValue != null) {    // 2. Check the local variable
    print(localValue.isEven);  // 3. Use the promoted local variable (OK)
  }
}

---

関連スキル：dart-effective-style、dart-api-design