dart-sdk-changelog

Dart SDK 变更日志与版本功能指南（Dart 1.x 至现代 Dart 3.x）

本技能提供一份权威且结构化的指南，涵盖 Dart 语言功能、核心库 API、工具变更、版本要求、实验性功能标志（--enable-experiment）、静态元编程（Macros 与 Augmentations），以及直接取材于官方 Dart SDK 变更日志 的旧版现代化操作手册。

---

🎯 上级指南：如何查找任意 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 的功能（例如 Primary Constructors）需要 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 指南
密封类与穷尽性检查	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% 健全的空安全	3.0.0	不允许使用非空安全模式	3.0-3.5 指南
超类初始化器参数	2.17.0	SubClass(super.name, {super.key});	Dart 2 里程碑
增强枚举	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 里程碑
健全的空安全（?、late、!）	2.12.0	健全的静态非空类型	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() 包装方法。
• 宏阶段：了解分析服务器中的类型宏、声明宏和定义宏的执行过程。
• 内存中代码生成：无需写入磁盘，消除 build_runner 生成的 .g.dart 文件。 👉 阅读完整的宏与增强指南。

子技能：实验性功能与编译器标志（--enable-experiment）

• 启用实验功能：配置 analysis_options.yaml（analyzer.enable-experiment）、CLI 标志（dart --enable-experiment=...）和 VS Code 设置。
• 发布流程：了解功能在 Beta 预览、Stable 门控和 Stable 非门控阶段之间的晋级路径。 👉 阅读完整的实验性功能指南。

子技能：拯救旧版代码库（Dart 1.x 和 2.12 之前的版本，迁移至现代 Dart）

• 健全空安全迁移：转换 @required 注解、未初始化的可空字段和防御性运行时断言。
• 依赖项升级：更新 pubspec.yaml 环境版本范围，并替换已弃用的旧版包（pedantic、tuple 等）。 👉 阅读完整的旧版代码库拯救指南。

---

📚 目录（TOC）和版本归档

发布版本 / 指南	重点领域	主要新增内容	参考文档
宏与增强	元编程	augment、augmented()、import augment、@JsonCodable()、3 阶段宏管线	宏与增强指南
实验性功能	编译器标志	--enable-experiment、Beta 预览版与稳定版门控发布层级、毕业状态矩阵	实验功能指南
旧版应用抢救	迁移操作手册	Dart 1.x/2.x 到现代 3.x 的现代化管线、空安全桥接、软件包替换	抢救指南
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	可扩展性与命令行	分析器插件正式稳定、Hooks（原生资源）正式稳定、dart install、@Deprecated 构造函数	3.10 参考
Dart 3.9	分析与 Pub	AOT 分析服务、Git 标签版本求解、流分析中的空安全假设	3.9 参考
Dart 3.8	格式化工具与文档	文档导入（@docImport）、高格式化风格保留尾随逗号、Iterable.withIterator	3.8 参考
Dart 3.7	语言与格式化工具	通配符变量（_）、使用界限进行推断、默认采用高格式化风格、旧版 Web 弃用项	3.7 参考
Dart 3.6	语言与 Pub	数字分隔符（1_000_000）、Pub 工作区、dart pub bump	3.6 参考
Dart 3.0 – 3.5	基础与主要功能	记录、模式、Switch 表达式、密封类、类修饰符、扩展类型、字段提升、Wasm	3.0–3.5 参考
Dart 2.0 – 2.19	历史里程碑	声明式空安全（2.12）、增强型枚举与 Super-Params（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. 将 --enable-experiment=name 传递给 dart run、dart test、flutter run 和 flutter test。
4. 确保实验性代码彼此隔离，以便生产软件包仍可发布到 pub.dev。

3. 现代化改造 / 挽救旧版代码库

1. 在 pubspec.yaml 的 environment 块中检查当前语言版本。
2. 如果低于 2.12，请阅读旧版代码挽救指南。
3. 执行 4 阶段流程：语法清理 → sound null safety → 升级依赖（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）。
   • 工具和命令行功能（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 进行验证。