---

name: flutter-dart-code-review description: 与库无关的 Flutter/Dart 代码审查清单，涵盖 Widget 最佳实践、状态管理模式（BLoC、Riverpod、Provider、GetX、MobX、Signals）、Dart 惯用法、性能、无障碍性、安全性和整洁架构。 origin: ECC

Flutter/Dart 代码审查最佳实践

全面的、与库无关的 Flutter/Dart 应用审查清单。无论使用哪种状态管理方案、路由库或 DI 框架，这些原则都适用。

---

1. 项目整体健康度

• [ ] 项目遵循一致的文件夹结构（功能优先或层级优先）
• [ ] 正确的关注点分离：UI、业务逻辑、数据层
• [ ] Widget 中没有业务逻辑；Widget 纯粹是展示性的
• [ ] pubspec.yaml 整洁——没有未使用的依赖，版本适当固定
• [ ] analysis_options.yaml 包含严格的 lint 集并启用严格分析器设置
• [ ] 生产代码中没有 print() 语句——使用 dart:developer 的 log() 或日志包
• [ ] 生成的文件（.g.dart、.freezed.dart、.gr.dart）是最新的或在 .gitignore 中
• [ ] 平台特定代码隔离在抽象层后面

---

2. Dart 语言陷阱

• [ ] 隐式 dynamic：缺少类型注解导致 dynamic——启用 strict-casts、strict-inference、strict-raw-types
• [ ] 空安全滥用：过度使用 !（bang 操作符）而非正确的空检查或 Dart 3 模式匹配（if (value case var v?)）
• [ ] 类型提升失败：使用 this.field 而本地变量提升可以工作的地方
• [ ] 捕获范围过广：catch (e) 没有 on 子句；始终指定异常类型
• [ ] 捕获 Error：Error 子类型表示 bug，不应被捕获
• [ ] 未使用的 async：标记为 async 但从不 await 的函数——不必要的开销
• [ ] late 过度使用：在可空或构造函数初始化更安全的地方使用 late；将错误推迟到运行时
• [ ] 循环中的字符串拼接：使用 StringBuffer 而非 + 进行迭代字符串构建
• [ ] const 上下文中的可变状态：const 构造函数类中的字段不应是可变的
• [ ] 忽略 Future 返回值：使用 await 或显式调用 unawaited() 来表明意图
• [ ] var 在 final 可用的地方：局部变量优先使用 final，编译时常量使用 const
• [ ] 相对导入：使用 package: 导入保持一致性
• [ ] 暴露可变集合：公共 API 应返回不可修改视图，而非原始 List/Map
• [ ] 缺少 Dart 3 模式匹配：优先使用 switch 表达式和 if-case 而非冗长的 is 检查和手动转换
• [ ] 为多返回值创建一次性类：使用 Dart 3 记录 (String, int) 而非单次使用的 DTO
• [ ] 生产代码中的 print()：使用 dart:developer 的 log() 或项目的日志包；print() 没有日志级别且无法过滤

---

3. Widget 最佳实践

Widget 分解：

• [ ] 没有单个 Widget 的 build() 方法超过约 80-100 行
• [ ] Widget 按封装性和变化方式拆分（重建边界）
• [ ] 返回 Widget 的私有 _build*() 辅助方法被提取为独立的 Widget 类（启用元素复用、const 传播和框架优化）
• [ ] 在不需要可变本地状态时优先使用 StatelessWidget 而非 StatefulWidget
• [ ] 可复用的提取 Widget 放在独立文件中

Const 使用：

• [ ] 尽可能使用 const 构造函数——防止不必要的重建
• [ ] 不变的集合使用 const 字面量（const []、const {}）
• [ ] 当所有字段都是 final 时声明 const 构造函数

Key 使用：

• [ ] 列表/网格中使用 ValueKey 以在重排序时保持状态
• [ ] GlobalKey 谨慎使用——仅在真正需要跨树访问状态时
• [ ] 避免在 build() 中使用 UniqueKey——它会强制每帧重建
• [ ] 当身份基于数据对象而非单个值时使用 ObjectKey

主题和设计系统：

• [ ] 颜色来自 Theme.of(context).colorScheme——没有硬编码的 Colors.red 或十六进制值
• [ ] 文本样式来自 Theme.of(context).textTheme——没有带原始字体大小的内联 TextStyle
• [ ] 验证暗色模式兼容性——不假设浅色背景
• [ ] 间距和尺寸使用一致的设计令牌或常量，而非魔法数字

Build 方法复杂度：

• [ ] build() 中没有网络调用、文件 I/O 或重计算
• [ ] build() 中没有 Future.then() 或 async 工作
• [ ] build() 中没有创建订阅（.listen()）
• [ ] setState() 局限于尽可能小的子树

---

4. 状态管理（与库无关）

这些原则适用于所有 Flutter 状态管理方案（BLoC、Riverpod、Provider、GetX、MobX、Signals、ValueNotifier 等）。

架构原则：

• [ ] 状态与 UI 分离
• [ ] 状态变更可追踪和可测试
• [ ] 避免全局可变状态
• [ ] 状态范围最小化——不要将所有内容放在顶层