
关于
与库无关的 Flutter/Dart 代码审查清单,涵盖 Widget 最佳实践、状态管理模式(BLoC、Riverpod、Provider、GetX、MobX、Signals)、Dart 惯用法、性能、无障碍、安全和整洁架构。
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 分离
- [ ] 状态变更可追踪和可测试
- [ ] 避免全局可变状态
- [ ] 状态范围最小化——不要将所有内容放在顶层
兼容工具
Claude CodeCursor
标签
移动端
