dart-sdk-changelog

Dart SDK 変更履歴 & バージョン機能ガイド（Dart 1.x から最新の Dart 3.x まで）

このスキルは、Dart 言語の機能、コアライブラリ API、ツールの変更点、バージョン要件、実験的機能フラグ（--enable-experiment）、静的メタプログラミング（マクロとオーグメンテーション）、およびレガシー近代化ランブックに関する、権威ある構造化されたガイドを提供します。これらは公式の Dart SDK CHANGELOG から直接引用しています。

---

🎯 親ガイド: 任意の Dart 機能や API の minSdk を見つける方法

Dart コードを作成またはレビューする際、pubspec.yaml で正しい最小 SDK 下限（minSdk）を選択することは、対象環境全体で構文とコア API がコンパイルされることを保証するために不可欠です。

1. 言語バージョンと言語バージョン対 SDK バージョン

• 言語バージョン（major.minor）: pubspec.yaml では、environment.sdk の下限（たとえば ^3.13.0 や >=3.12.0 <4.0.0）が、どの言語文法とコンパイラセマンティクスを有効にするかを規定します。
  • パッチ番号（.1、.2）は言語文法に影響しません。
  • Dart 3.13 の機能（プライマリコンストラクタなど）を使用するには sdk: '^3.13.0' が必要です。
• コアライブラリ API: メソッドとクラス（たとえば Future.pause、List.unmodifiableOf）は特定の SDK バージョンで追加されます。
• ファイル単位のオーバーライド: ファイルの 1 行目に // @dart = 3.12 を指定することで、以前の言語バージョンを強制できます。

2. 高速 minSdk 言語機能マトリックス

機能 / 構文	最小 SDK	構文例	リファレンス
プライマリコンストラクター	3.13.0	class Point(var int x, var int y); / this : assert(...)	3.13 ガイド
コンストラクターキーワードの省略記法	3.13.0	new(this.x); / factory clone(...) => ...;	3.13 ガイド
プライベート名前付きパラメーター	3.12.0	Point({required this._x, required this._y});	3.12 ガイド
ワイルドカード変数 (_)	3.7.0	var (_, b) = pair; / void fn(int _, int _)	3.7 ガイド
境界を使用した型推論	3.7.0	推論された型は型パラメーターの境界に従います	3.7 ガイド
桁区切り文字	3.6.0	1_000_000、0x4000_0000、0.000_001	3.6 ガイド
拡張型	3.3.0	extension type Meters(int value) {}	3.0-3.5 ガイド
プライベートフィールドのプロモーション	3.2.0	if (_privateFinalField != null) { ... }	3.0-3.5 ガイド
レコード (タプル)	3.0.0	(int, String) pair = (1, 'a');	3.0-3.5 ガイド
パターンマッチングと分割代入	3.0.0	var (a, b) = pair; / switch (val) { case ... }	3.0-3.5 ガイド
switch 式	3.0.0	var s = switch (e) { 0 => 'a', _ => 'b' };	3.0-3.5 ガイド
if-case 文と要素	3.0.0	if (json case {'id': int id}) ...	3.0-3.5 ガイド
sealed クラスと網羅性	3.0.0	sealed class State {}	3.0-3.5 ガイド
クラス修飾子 (base、interface、final)	3.0.0	interface class Api {} / final class Token {}	3.0-3.5 ガイド
100% サウンドな Null 安全の強制	3.0.0	Null 安全でないモードは許可されません	3.0-3.5 ガイド
スーパー初期化子パラメーター	2.17.0	SubClass(super.name, {super.key});	Dart 2 マイルストーン
拡張 enum	2.17.0	enum Status { ok(200); final int c; const Status(this.c); }	Dart 2 マイルストーン
任意の位置での名前付き引数	2.17.0	fn(1, named: 'a', 2);	Dart 2 マイルストーン
コンストラクターの tear-off	2.15.0	List.filled、Point.new	Dart 2 マイルストーン
三重シフト演算子 (>>>)	2.14.0	int result = a >>> b;	Dart 2 マイルストーン
ジェネリック型エイリアス (typedef)	2.13.0	typedef JsonMap = Map<String, dynamic>;	Dart 2 マイルストーン
サウンドな Null 安全 (?、late、!)	2.12.0	サウンドな静的 non-nullable 型	Dart 2 マイルストーン
拡張メソッド	2.7.0	extension on String { ... }	Dart 2 マイルストーン
スプレッド演算子 (...、...?)	2.3.0	[...list1, ...?maybeList]	Dart 2 マイルストーン
コレクションの if と for	2.3.0	[if (cond) a, for (var x in l) x * 2]	Dart 2 マイルストーン
サウンドな型システムと任意の new	2.0.0	静的なサウンド型が動的チェックを置き換えます	Dart 2 マイルストーン

👉 詳細な解説と検証手順については、minSdk の確認方法 と 完全なバージョン対応表 を参照してください。

---

⚡ サブスキルスポットライト

サブスキル: 拡張と静的メタプログラミング (マクロ)

• 拡張構文: augment class、import augment を宣言し、augmented() を使ってメソッドをラップします。
• マクロフェーズ: 分析サーバーにおける Type、Declaration、Definition マクロの実行を理解します。
• インメモリコード生成: ディスクを汚染する .g.dart を一切生成せず、build_runner を不要にします。 👉 詳細は マクロ & 拡張ガイド をご覧ください。

サブスキル: 実験的機能とコンパイラフラグ (--enable-experiment)

• 実験の有効化: analysis_options.yaml (analyzer.enable-experiment)、CLI フラグ (dart --enable-experiment=...)、VS Code の設定を構成します。
• リリースパイプライン: Beta プレビュー、Stable ゲート付き、Stable ゲートなしという各段階を経る昇格パスを理解します。 👉 詳細は 実験的機能ガイド をご覧ください。

サブスキル: レガシーコードベースの救済 (Dart 1.x & 2.12 以前からモダン Dart へ)

• サウンドヌルセーフティ移行: @required アノテーション、未初期化の null 許容フィールド、防御的な実行時アサーションを変換します。
• 依存関係のアップグレード: pubspec.yaml の environment 制約をモダン化し、非推奨のレガシーパッケージ (pedantic、tuple など) を置き換えます。 👉 詳細は レガシーコードベース救済ガイド をご覧ください。

---

📚 目次（TOC）とバージョンアーカイブ

リリース / ガイド	対象領域	主な追加内容	参照ドキュメント
マクロとオーグメンテーション	メタプログラミング	augment、augmented()、import augment、@JsonCodable()、3 フェーズのマクロパイプライン	マクロとオーグメンテーションガイド
実験的機能	コンパイラフラグ	--enable-experiment、ベータプレビューと安定版ゲート付きリリース層、卒業マトリクス	実験的機能ガイド
レガシー救済	移行ランブック	Dart 1.x/2.x からモダンな 3.x へのモダナイゼーションパイプライン、null 安全ブリッジ、パッケージの置き換え	救済ガイド
Dart 3.14	FFI と JS 相互運用	NativeFinalizer.callback、プリミティブ JS 配列の高速変換	3.14 リファレンス
Dart 3.13	言語とランタイム	プライマリコンストラクター、this コンストラクター本体、new/factory の省略記法、Future.pause、同期アイソレート	3.13 リファレンス
Dart 3.12	言語とツール	プライベート名前付きパラメーター（Point({this._x})）、RegExp スパン、dart run <pkg>@<ver>	3.12 リファレンス
Dart 3.11	プラットフォームと Pub	Windows の Unix ドメインソケット、ワークスペースの glob（pkgs/*）、dart pub cache gc	3.11 リファレンス
Dart 3.10	拡張性と CLI	アナライザープラグインが安定版に、フック（ネイティブアセット）が安定版に、dart install、@Deprecated コンストラクター	3.10 リファレンス
Dart 3.9	解析と Pub	AOT 解析サーバー、git タグバージョン解決、フロー解析における null 安全の前提	3.9 リファレンス
Dart 3.8	フォーマッターとドキュメント	ドキュメントインポート（@docImport）、tall フォーマッターによる末尾カンマの保持、Iterable.withIterator	3.8 リファレンス
Dart 3.7	言語とフォーマッター	ワイルドカード変数（_）、バウンドを用いた型推論、tall スタイルフォーマッターのデフォルト化、レガシー web の非推奨化	3.7 リファレンス
Dart 3.6	言語と Pub	桁区切り（1_000_000）、Pub ワークスペース、dart pub bump	3.6 リファレンス
Dart 3.0 – 3.5	基盤と主要機能	レコード、パターン、switch 式、sealed クラス、クラス修飾子、拡張型、フィールドプロモーション、Wasm	3.0～3.5 リファレンス
Dart 2.0 – 2.19	歴史的マイルストーン	完全な null 安全（2.12）、拡張 enum とスーパーパラメーター（2.17）、拡張メソッド（2.7）、スプレッド（2.3）、完全な型システム（2.0）	Dart 2 マイルストーン

---

🛠️ 推奨ランブック

1. オーグメンテーションとマクロの使用

1. マクロとオーグメンテーションガイドを確認します。
2. 元のファイルには import augment 'foo.g.dart'; を、オーグメンテーションファイルには augment library 'foo.dart'; を記述して連携させます。
3. augment class、augment void method() を使用し、augmented() を呼び出して元のロジックをラップします。

2. 実験的機能フラグの使用

1. フラグを追加する前に、その機能が使用中の SDK で既に安定版へ卒業しているかどうかを確認します。
2. 実験的な場合は、analysis_options.yaml の analyzer.enable-experiment: [name] を設定します。
3. dart run、dart test、flutter run、flutter test に --enable-experiment=name を渡します。
4. 実験的なコードを分離し、本番パッケージが pub.dev で公開可能な状態を保てるようにします。

3. レガシーコードベースのモダナイズ / 救済

1. pubspec.yaml の environment ブロックから現在の言語バージョンを確認します。
2. 2.12 より前の場合は、レガシー救済ガイドをお読みください。
3. 4段階のパイプラインを実行します: 構文のクリーンアップ → サウンドヌルセーフティ → 依存関係の更新 (sdk: ^3.5.0 または ^3.13.0) → Dart 3 へのモダナイズ。

4. 「Dart X.Y の新機能は何か」への回答

1. 要求されたバージョンを特定します。
2. references/ 配下の対応するリファレンスドキュメントをお読みください。
3. 以下を提供します:
   • 言語構文の変更点 (変更前/変更後のコードスニペット付き)。
   • コアライブラリの追加 (dart:core、dart:async、dart:io、dart:js_interop、dart:isolate、dart:ffi)。
   • ツールと CLI の機能 (dart analyze、dart format、dart pub、dart build)。
   • 破壊的変更と移行手順。

5. 「X の minSdk を見つける方法」への回答

1. 言語機能マトリクスと minSdk の見つけ方ガイドを確認します。
2. pubspec.yaml 用の正確な SDK 制約の下限を指定します (例: sdk: '^3.13.0')。
3. その機能が言語文法の機能 (言語バージョンの更新が必要) なのか、コアライブラリの API なのかを説明します。
4. dart analyze を使って確認する方法を示します。