| name | flutter-dart-code-review |
| description | 库无关的 Flutter/Dart 代码审查清单，涵盖 Widget 最佳实践、状态管理模式（BLoC、Riverpod、Provider、GetX、MobX、Signals）、Dart 惯用法、性能、无障碍、安全和整洁架构。 Use when this capability is needed. |
| metadata | {"author":"aaione"} |
Flutter/Dart 代码审查最佳实践
全面的、库无关的 Flutter/Dart 应用审查清单。无论使用哪种状态管理方案、路由库或 DI 框架，这些原则都适用。
1. 通用项目健康
2. Dart 语言陷阱
3. Widget 最佳实践
Widget 分解：
Const 使用：
Key 使用：
主题和设计系统：
build 方法复杂度：
4. 状态管理（库无关）
这些原则适用于所有 Flutter 状态管理方案（BLoC、Riverpod、Provider、GetX、MobX、Signals、ValueNotifier 等）。
架构：
不可变性和值相等（用于不可变状态方案：BLoC、Riverpod、Redux）：
响应性规范（用于响应式修改方案：MobX、GetX、Signals）：
状态形状设计：
// 错误——布尔标志组合允许不可能的状态
class UserState {
bool isLoading = false;
bool hasError = false; // isLoading && hasError 是可表示的！
User? user;
}
// 正确（不可变方式）——密封类型使不可能的状态不可表示
sealed class UserState {}
class UserInitial extends UserState {}
class UserLoading extends UserState {}
class UserLoaded extends UserState {
final User user;
const UserLoaded(this.user);
}
class UserError extends UserState {
final String message;
const UserError(this.message);
}
// 正确（响应式方式）——可观察枚举 + 数据，通过响应式 API 变更
// enum UserStatus { initial, loading, loaded, error }
// 使用你的方案的可观察/信号来分别包装状态和数据
重建优化：
订阅和释放：
局部与全局状态：
5. 性能
不必要的重建：
build() 中的昂贵操作：
图像优化：
懒加载：
其他：
6. 测试
测试类型和期望：
覆盖率目标：
测试隔离：
Widget 测试质量：
7. 无障碍
语义化 Widget：
屏幕阅读器支持：
视觉无障碍：
交互无障碍：
8. 平台特定关注
iOS/Android 差异：
响应式设计：
9. 安全
安全存储：
API 密钥处理：
输入验证：
网络安全：
10. 包/依赖审查
评估 pub.dev 包：
版本约束：
Monorepo 特定（melos/workspace）：
11. 导航和路由
通用原则（适用于任何路由方案）：
12. 错误处理
框架错误处理：
错误报告：
优雅降级：
13. 国际化（l10n）
设置：
内容：
代码审查：
14. 依赖注入
原则（适用于任何 DI 方式）：
15. 静态分析
配置：
执行：
无论使用哪个 lint 包都应验证的关键规则：
状态管理快速参考
下表将通用原则映射到流行方案中的实现。使用此表将审查规则调整为项目使用的方案。
| 原则 | BLoC/Cubit | Riverpod | Provider | GetX | MobX | Signals | 内置 |
|---|
| 状态容器 | Bloc/Cubit | Notifier/AsyncNotifier | ChangeNotifier | GetxController | Store | signal() | StatefulWidget |
| UI 消费者 | BlocBuilder | ConsumerWidget | Consumer | Obx/GetBuilder | Observer | Watch | setState |
| 选择器 | BlocSelector/buildWhen | ref.watch(p.select(...)) | Selector | N/A | computed | computed() | N/A |
| 副作用 | BlocListener | ref.listen | Consumer 回调 | ever()/once() | reaction | effect() | 回调 |
| 释放 | 通过 BlocProvider 自动 | .autoDispose | 通过 Provider 自动 | onClose() | ReactionDisposer | 手动 | dispose() |
| 测试 | blocTest() | ProviderContainer | 直接 ChangeNotifier | 测试中 Get.put | 直接 store | 直接 signal | Widget 测试 |
来源
Source: aaione/everything-claude-code-zh — distributed by TomeVault.
