用 Dart 3 模式匹配与 switch…

在 Dart 3 中需要校验数据结构、处理代数数据类型或拆解复杂控制流时，用模式匹配、switch 表达式和解构替代冗长 if-else。

适用场景

解决思路

1. 按数据结构选择模式类型：校验并提取反序列化数据（如 JSON）时用 Map、List、Object 模式一步完成结构校验与属性解构；处理多态载荷或响应时用 switch 表达式基于 map 判别键反序列化为 sealed 类层次；处理多返回值时用 Record 模式直接解构到局部变量；执行类型特定行为（代数数据类型）时用 Object 模式配合 sealed 类保证穷尽性；匹配数值范围或条件时在 switch 分支中用关系模式（>=、<=）和逻辑与（&&）；多个 case 共享逻辑时用逻辑或（||）模式共享同一 case 体或 guard 子句；忽略特定值时用通配符模式（_）或集合中的非匹配 Rest 元素（...）。
2. 需要产生值时用 switch 表达式，语法为 switch (value) { pattern => expression, }，每个 case 必须是单个表达式，无隐式 fallthrough，必须穷尽。
3. 需要执行语句或副作用时用 switch 语句，语法为 switch (value) { case pattern: statements; }，空 case 会 fallthrough 到下一个 case，非空 case 隐式 break（无需 break 关键字）。
4. 逻辑或模式写作 pattern1 || pattern2，两个分支必须定义完全相同的变量集合。
5. 逻辑与模式写作 pattern1 && pattern2，两个分支不得定义重叠变量。
6. 关系模式用 ==、!=、<、>、<=、>= 后跟常量表达式。
7. Cast 模式写作 pattern as Type，值不匹配类型时抛异常，用于在解构时强制断言类型。
8. Null-check 模式写作 pattern?，值为 null 时匹配失败，并将变量绑定为非空基类型。
9. Null-assert 模式写作 pattern!，值为 null 时抛异常。
10. 变量模式写作 var name 或 Type name，将匹配值绑定到新的局部变量。
11. 通配符模式写作 _，匹配任意值并丢弃。
12. List 模式写作 [pattern1, pattern2]，匹配精确长度的列表，除非使用 Rest 元素（... 或 ...var rest）。
13. Map 模式写作 {"key": pattern}，匹配包含指定键的 map，忽略未匹配的键。
14. Record 模式写作 (pattern1, named: pattern2)，匹配精确形状的 record，用 :var name 推断 getter 名。
15. Object 模式写作 ClassName(field: pattern)，匹配 ClassName 实例，用 :var field 推断 getter 名。
16. 对单个可提升变量优先用 is 类型提升而非 if-case：例如 for (final MapEntry(:key, :value) in map.entries) { if (key is String && value != null) { process(key, value); } }，避免引入多余别名变量。
17. 在 switch 分支中合并可空类型：当 null 与类型 T 都有效且处理方式相同时，直接匹配 T?（如 final String? s => s），不要写多余的 null 分支。
18. 保留快速失败校验，不要静默丢弃数据：循环或反序列化中若畸形数据应触发错误或诊断警告，用 if (raw is! Map<String, dynamic>) { throw FormatException(...); } 而非 if-case 过滤。
19. 避免单 case 或布尔 switch：用 if (x is T) 替代只有 1 个 case 加 default: break; 的 switch 语句；用三元运算符 condition ? a : b 替代 switch (condition) { true => a, false => b }。
20. 避免无意义的对象解构：在已知非空实例上读取单个属性时用 user.name，而非 final User(:name) = user;。
21. 避免对独立标量比较使用 if-case：用 if (code >= 200 && code < 300) 而非 if (code case >= 200 && < 300)，关系模式保留给多分支 switch 表。
22. 实现复杂模式匹配时按清单推进：识别被求值的数据结构（JSON、Record、Class、Enum）；选择 switch 构造（产生值用表达式，副作用用语句）；定义所需模式（Object、Map、List、Record）；用变量模式（var x、:var y）提取所需数据；对无法用模式表达的逻辑应用 guard 子句（when condition）；用通配符（_）或 default 子句处理未匹配情况（未使用 sealed 类时）；运行 dart analyze 检查穷尽性和死代码；验证运行时 Map/JSON 模式对省略键（containsKey 语义）与显式 null 值的行为。
23. 穷尽性检查反馈循环：对 sealed 类或 enum 做 switch 时，运行 dart analyze，查看 "The type 'X' is not exhaustively matched by the switch cases" 或不可达模式分支警告，为未处理子类型补上 Object 模式，或添加显式通配符（_）分支作为默认回退或错误处理。
24. 运行时 Map 与 JSON 模式验证反馈循环：由于 dart analyze 无法静态验证动态 Map<String, dynamic> 键，需显式验证运行时语义——map 模式 {'key': String? val} 检查 map.containsKey('key')，若 JSON 载荷中完全省略 'key'，即使 String? 可空模式也会匹配失败，此时应从已校验的 map 中直接提取可选键（map['key'] as String?）；确保未匹配或畸形 map 结构命中显式 _ => throw FormatException(...) 分支，而非静默失败于 if-case 检查。
25. 多态 JSON 反序列化（可辨识联合）：用 Map 模式配合 switch 表达式校验带标签的 JSON 载荷并构造 sealed 类层次，参考 examples/json_patterns.dart 中将带标签的 ApiResponse 解析为 SuccessResponse 和 ErrorResponse 的可执行实现。
26. 嵌套 JSON 校验与可选字段：用嵌套 Map 和 List 模式一步校验必需结构并提取集合，参考 examples/json_patterns.dart 中 processUserPayload 的可执行实现；Map 模式检查键是否存在（containsKey），若可选 JSON 键可能被完全省略（而非显式传 'key': null），则通过模式解构必需键，并从匹配的子 map 中直接提取可选字段。
27. 代数数据类型（sealed 类）：用 Object 模式配合 switch 表达式穷尽处理家族类型，例如 double calculateArea(Shape shape) => switch (shape) { Square(length: var l) => l * l, Circle(:var radius) => math.pi * radius * radius, };，sealed 修饰符保证穷尽性。
28. 变量交换与解构：用变量赋值模式交换值或提取 record 字段而无需临时变量，例如 var (a, b) = ('left', 'right'); (b, a) = (a, b); 以及 var (name, age) = getUserInfo();。
29. Guard 子句与逻辑或：用 when 在模式匹配后求值任意条件，例如 switch (shape) { case Square(length: var s) || Circle(radius: var s) when s > 0: print('Valid positive shape with dimension $s'); case Square() || Circle(): print('Zero or negative dimension shape'); }。

适用边界 · 注意事项

• 不要用于简单布尔条件、单变量类型提升（应使用 is）或基础集合过滤。
• 不要用 if-case 在循环或反序列化中过滤元素，若畸形数据应触发错误或诊断警告（应快速失败）。
• 不要用单 case 或布尔 switch、无意义的对象解构，以及对独立标量比较使用 if-case。