dart-tooling

Dart ツールとパッケージのワークフロー

目次

• 静的解析の解決
• パッケージの競合の解決
• テストを package:checks へ移行する

静的解析の解決

この順序立てたワークフローを使用して、Dart プロジェクトの静的解析エラーを特定、修正、検証します。

1. 静的アナライザーを実行: dart analyze . --fatal-infos
2. 自動修正を適用:
   • dart fix --dry-run
   • dart fix --apply
3. 手動で解決: dart fix が自動で解決できなかった型の不一致、Null 安全性、無効なオーバーライドに対処します。
4. パフォーマンス診断: Analysis Server の診断ページ（アナライザーの実行中に http://localhost:8082 で利用可能）を活用して、遅い解析時間を追跡および診断します。
5. 検証: dart analyze . と dart test の両方が成功することを確認します。

パッケージの競合の解決

互換性のないパッケージバージョンが原因で pub get が失敗する場合は、この体系的なアプローチを使用します。

dart pub outdated の理解

列	意味
Current	現在 pubspec.lock にあるバージョン
Upgradable	pubspec.yaml の制約で許可されている最新バージョン
Resolvable	他のすべての依存関係とともに解決できる最新バージョン
Latest	公開されている最新バージョン（制約を無視）

dart pub outdated

Git LFS のサポート

Dart 3.12 で導入

• dart pub パッケージ管理コマンドは、Git Large File Storage（LFS）をネイティブにサポートします。LFS オブジェクト（例: アセット、バイナリ、モデル）を含む Git リポジトリから取得した依存関係は、ローカル設定を必要とせずに自動的に解決されます。

バージョン制約のベストプラクティス

• キャレット構文を使用する: 常に ^1.2.3 を使用します。これは、次のメジャーバージョンまで非破壊的な更新を許可します。
• 開発用依存関係を厳格化する: dev_dependencies の下限を現在の正確なバージョンに設定します。
• CI の再現性: CI では dart pub get --enforce-lockfile を使用して、テスト済みの正確なバージョンを保証します。

依存関係のアップグレード

「Upgradable」バージョンに更新する場合:

dart pub upgrade
dart pub upgrade --tighten  # Auto-update lower bounds in pubspec.yaml

「Resolvable」バージョン（メジャー）に更新する場合:

1. pubspec.yaml を手動で編集して制約を引き上げます。
2. dart pub upgrade を実行します。
3. dart analyze を実行 → 破壊的な API 変更を修正します。
4. dart test を実行 → リグレッションを修正します。

外科的なロックファイルの削除

決して pubspec.lock 全体を削除しないでください。これは依存関係グラフ全体にわたる制御不能なアップグレードを引き起こします。

代わりに、競合しているパッケージのブロックのみを削除します。

1. pubspec.lock を開きます。
2. 競合しているパッケージの YAML ブロックのみを見つけて削除します。
3. dart pub get を実行します: そのパッケージのみの最新の互換バージョンを取得します。
4. 検証: dart pub deps → 依存関係グラフが正しく解決されることを確認します。

一時的なオーバーライド（最終手段）

dependency_overrides:
  shared_package: ^x.y.z  # Remove once direct deps support newer version

テストを package:checks へ移行する

読みやすい出力のために、テストのアサーションを package:matcher 構文から package:checks が提供するリテラシー API へ移行します。

• 依存関係: dart pub add dev:checks で dev_dependency の checks を追加します。
• 基本的な等価性: expect(actual, equals(expected)) を check(actual).equals(expected) に置き換えます。
• 型チェック: expect(actual, isA<Type>()) を check(actual).isA<Type>() に置き換えます。
• 非同期の期待値:
  • await check(Future.value(10)).completes((it) => it.equals(10));
• ワークフロー:
  1. package:checks を追加し、package:checks/checks.dart をインポートします。
  2. expect() 呼び出しを check() に書き換えます。
  3. 静的アナライザーとテストを実行して検証します。