flutter-best-practices

Flutter のベストプラクティス

保守しやすい Flutter アプリを構築するための標準です。公式の Flutter アーキテクチャガイドと、LeanCode が 40 件以上の Flutter プロジェクト（開発者 30 人が参加した銀行アプリを含む）をリリースしてきた経験をもとにまとめています。新しいコードを書くときはこれらを適用してください。既存のコードを変更するときは、周囲のコードベースとの一貫性を優先し、黙って書き換えるのではなく、これらの標準との不一致を指摘してください。

このスキルの使い方

タスクに合ったリファレンスファイルを読んでください。複数の領域にまたがるタスク（たとえば、新機能が構成とコーディングスタイルの両方に関わる場合）は、複数のファイルを読んでください。

タスク	読むファイル
レイヤーの設計、ロジックの配置場所の決定、MVVM、リポジトリ／サービス	references/architecture-layers.md
機能の作成／整理、フォルダー構成、状態管理の接続	references/feature-structure.md
Dart／Flutter コード、ウィジェット、テスト、リンターの作成またはレビュー	references/dart-coding-practices.md
複数チーム／複数パッケージのアプリ、モノレポ、ナビゲーション、ローカライズ、API コントラクト、E2E テスト	references/enterprise-scale.md
アプリのローカライズ設定、再利用可能な UI パッケージの文字列の管理、言語ピッカーの表示	references/localization-package-boundaries.md

簡単なタスク（小さなウィジェットの修正、1 行のレビューコメントなど）では、以下の基本ルールだけで十分な場合があります。

基本ルール（常に適用）

アーキテクチャ

1. UI とデータを分離します。 大きく 2 つのレイヤーに分けます。UI（ビュー＋ビューモデル／キュービット）とデータ（リポジトリ＋サービス）です。依存関係の方向は一方通行です。View → ViewModel → Repository → Service。下位レイヤーから上位レイヤーをインポートしてはいけません。リポジトリ同士を依存させてはいけません。
2. ビューにビジネスロジックを持たせません。 ウィジェットには、表示／非表示の条件分岐、アニメーション、レイアウト、単純なルーティングロジックを含めてもかまいませんが、データを変換したり判断したりする処理を含めてはいけません。データロジックはすべて、BuildContext にアクセスしないビューモデル（またはキュービット／ブロック）に置きます。
3. レイヤーではなく機能ごとに整理します。 状態管理、ウィジェット、モデルなど、機能に必要なものはすべて 1 つの機能ディレクトリにまとめます。機能がツリー全体に散らばるようなトップレベルの blocs/、widgets/、models/ ディレクトリを作成してはいけません。
4. 状態は不変かつ明示的にします。 UI の状態は、sealed／union 型（initial／inProgress／failure／ready）としてモデル化し、すべてのケースを網羅的に処理してください。スナックバーやナビゲーションなどの単発の効果は、状態ではなくイベントとして扱います。
5. メリットがある場合にのみレイヤーを追加します。 まずはビューモデル → API クライアントから始めます。キャッシュ、オフライン対応、またはデータソースの統合が必要になったら、リポジトリを導入します。ユースケースを導入するのは、複数のリポジトリにまたがるロジックがある場合、ロジックが本当に複雑な場合、または複数のビューモデルで再利用する場合に限ります。

コーディング

6. Container より、意図が伝わるウィジェットを優先します。 Padding、SizedBox、ColoredBox、DecoratedBox、Center を使います。これらは const にでき、役割が明確です。Container は、複数のプロパティを同時に組み合わせる場合にのみ使用してください。
7. モダンな Dart を使います。 パターンマッチング（if (x case final v?)）、網羅性を備えた switch 式、レコードと分割代入、.add() ループの代わりとなるコレクションの if／for／スプレッド、冗長な async／await を使わない中継用の非同期関数での式本体を活用します。
8. スライバーを返すウィジェットには Sliver を接頭辞として付けます。 これにより、誤ったスクロールコンテキストでの使用をひと目で見つけられます。
9. テストで処理の流れを伝えます。 表現力のあるマッチャー（isEmpty、throwsA、isA、completion）を使い、依存関係を最小限に抑えます。テスト用フィクスチャでは、デザインシステムのウィジェットよりも通常の Text／SizedBox を使います。キュービット／ビューモデルはウィジェットツリーから分離してテストします。
10. すべての // ignore: に、同じ行または直前の行で理由を記載します。 エラーのログには専用の error／stackTrace パラメーターを使い、文字列補間は使用しません。

ワークフローのチェックリスト

新しい機能／画面の追加

1. references/feature-structure.md を読み、 機能ディレクトリについて既存プロジェクトの規約に合わせます。
2. まず状態をユニオン型として定義し、次にCubit／ビューモデルを定義してから、 ウィジェットを作成します。依存関係はコンストラクターで注入し、機能の ウィジェットサブツリー内にスコープを設定します。
3. データはリポジトリまたは型付きAPIクライアントを通じて取得します。ウィジェット内で 取得してはいけません。
4. UIの詳細を組み込む前に、Cubit／ビューモデルのロジックに対するユニットテストを追加します。

Flutterコードのレビュー

重要度の高い順に確認します。

1. ロジックは適切なレイヤーにありますか（ルール1～2）？ビジネスロジックに BuildContext が含まれていませんか？
2. 状態は不変のユニオン型としてモデル化され、すべてのケースが処理されていますか？
3. 機能は自己完結していますか。それとも、別の機能の内部に踏み込んでいますか？
4. ウィジェットの選択（ルール6）、モダンなDart（ルール7）、スライバーの命名（ルール8）は適切ですか？
5. ロジックのテストがあり、読みやすく、依存関係は最小限ですか？
6. 説明のない // ignore:、文字列補間を使ったエラーログ、非推奨の パターンがまだ広がっていませんか？

新しいプロジェクトの開始

1. レイヤーの設計図については references/architecture-layers.md を、 フォルダーのひな形については references/feature-structure.md を 読みます。
2. 約2チームを超える場合、または明確に分離できるドメインがある場合は、 references/enterprise-scale.md を読み、 最初からドメインごとに1つのパッケージを設けるMelosモノレポを検討します。
3. 厳格なリント（leancode_lint または同等のものとカスタムルール）を早い段階で設定します。 後から導入する方がはるかにコストがかかります。

パッケージの選択肢

これらの標準が想定するデフォルトです（コードベースですでに別のものを使っている場合は、 プロジェクト内で使われている同等のものに置き換えてください）。

• 状態: ユニオン型の状態には bloc（Cubit）＋ freezed を使用します。 単発のUIイベントには bloc_presentation を使用します。
• DI: ウィジェットのサブツリー内でスコープを設定した provider を使用します （コンパイル時の安全性がない点は、より小さな悪として受け入れます）。
• ボイラープレートの削減: flutter_hooks
• モノレポ: melos
• ローカライズ: .arb ファイルを使った flutter_localizations ＋ intl
• リント: leancode_lint
• E2E／UIテスト: patrol

Flutterの公式ガイドは状態管理の方式を指定していません（ChangeNotifierを使ったMVVMも問題ありません）。 重要なのはレイヤーの分離であり、パッケージではありません。根拠とトレードオフについては リファレンスファイルを参照してください。