[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M72Y2VKB18HJ0VCXWCQHP0RQ":3,"skill-same:01M72Y2VKB18HJ0VCXWCQHP0RQ":48},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":25,"commitSha":26,"skillDirectory":27,"forksCount":28,"repositoryHtmlUrl":29,"repositoryHomepageUrl":6,"ownerHtmlUrl":30,"ownerBlogUrl":31,"ownerDescription":32,"updatedAt":33,"install":34,"resources":47},"01M72Y2VKB18HJ0VCXWCQHP0RQ","flutter-dart-code-review",null,"库无关的Flutter\u002FDart代码审查清单，涵盖Widget最佳实践、状态管理模式（BLoC、Riverpod、Provider、GetX、MobX、Signals）、Dart惯用法、性能、可访问性、安全性和整洁架构。","SriramGandhiS\u002FSkills","SriramGandhiS","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F211849986?v=4","01M72WQCW12BYX71C6WN584TTA","Sriram S","01M72WQCWTJ2RD0ET1X31AF1RC",1,"MIT","https:\u002F\u002Fgithub.com\u002FSriramGandhiS\u002FSkills\u002Fblob\u002Fmaster\u002Feverything-claude-code\u002Fdocs\u002Fzh-CN\u002Fskills\u002Fflutter-dart-code-review\u002FSKILL.md",[],[],"2026-11-10 22:39:42",false,"---\nname: flutter-dart-code-review\ndescription: 库无关的Flutter\u002FDart代码审查清单，涵盖Widget最佳实践、状态管理模式（BLoC、Riverpod、Provider、GetX、MobX、Signals）、Dart惯用法、性能、可访问性、安全性和整洁架构。\norigin: ECC\n---\n\n# Flutter\u002FDart 代码审查最佳实践\n\n适用于审查 Flutter\u002FDart 应用程序的全面、与库无关的清单。无论使用哪种状态管理方案、路由库或依赖注入框架，这些原则都适用。\n\n***\n\n## 1. 通用项目健康度\n\n* \\[ ] 项目遵循一致的文件夹结构（功能优先或分层优先）\n* \\[ ] 关注点分离得当：UI、业务逻辑、数据层\n* \\[ ] 部件中无业务逻辑；部件纯粹是展示性的\n* \\[ ] `pubspec.yaml` 是干净的 —— 没有未使用的依赖项，版本已适当固定\n* \\[ ] `analysis_options.yaml` 包含严格的 lint 规则集，并启用了严格的分析器设置\n* \\[ ] 生产代码中没有 `print()` 语句 —— 使用 `dart:developer` `log()` 或日志包\n* \\[ ] 生成的文件 (`.g.dart`, `.freezed.dart`, `.gr.dart`) 是最新的或在 `.gitignore` 中\n* \\[ ] 平台特定代码通过抽象进行隔离\n\n***\n\n## 2. Dart 语言陷阱\n\n* \\[ ] **隐式动态类型**：缺少类型注解导致 `dynamic` —— 启用 `strict-casts`, `strict-inference`, `strict-raw-types`\n* \\[ ] **空安全误用**：过度使用 `!`（感叹号操作符）而不是适当的空检查或 Dart 3 模式匹配 (`if (value case var v?)`)\n* \\[ ] **类型提升失败**：在可以使用局部变量类型提升的地方使用了 `this.field`\n* \\[ ] **捕获范围过宽**：`catch (e)` 没有 `on` 子句；应始终指定异常类型\n* \\[ ] **捕获 `Error`**：`Error` 子类型表示错误，不应被捕获\n* \\[ ] **未使用的 `async`**：标记为 `async` 但从未 `await` 的函数 —— 不必要的开销\n* \\[ ] **`late` 过度使用**：在可使用可空类型或构造函数初始化更安全的地方使用了 `late`；将错误推迟到运行时\n* \\[ ] **循环中的字符串拼接**：使用 `StringBuffer` 而不是 `+` 进行迭代式字符串构建\n* \\[ ] **`const` 上下文中的可变状态**：`const` 构造器类中的字段不应是可变的\n* \\[ ] **忽略 `Future` 返回值**：使用 `await` 或显式调用 `unawaited()` 来表明意图\n* \\[ ] **在 `final` 可用时使用 `var`**：局部变量首选 `final`，编译时常量首选 `const`\n* \\[ ] **相对导入**：为保持一致性，使用 `package:` 导入\n* \\[ ] **暴露可变集合**：公共 API 应返回不可修改的视图，而不是原始的 `List`\u002F`Map`\n* \\[ ] **缺少 Dart 3 模式匹配**：优先使用 switch 表达式和 `if-case`，而不是冗长的 `is` 检查和手动类型转换\n* \\[ ] **为多重返回值使用一次性类**：使用 Dart 3 记录 `(String, int)` 代替一次性 DTO\n* \\[ ] **生产代码中的 `print()`**：使用 `dart:developer` `log()` 或项目的日志包；`print()` 没有日志级别且无法过滤\n\n***\n\n## 3. 部件最佳实践\n\n### 部件分解：\n\n* \\[ ] 没有单个部件的 `build()` 方法超过约 80-100 行\n* \\[ ] 部件按封装方式以及按变化方式（重建边界）进行拆分\n* \\[ ] 返回部件的私有 `_build*()` 辅助方法被提取到单独的部件类中（支持元素重用、常量传播和框架优化）\n* \\[ ] 在不需要可变局部状态的地方，优先使用无状态部件而非有状态部件\n* \\[ ] 提取的部件在可复用时放在单独的文件中\n\n### Const 使用：\n\n* \\[ ] 尽可能使用 `const` 构造器 —— 防止不必要的重建\n* \\[ ] 对不变化的集合使用 `const` 字面量 (`const []`, `const {}`)\n* \\[ ] 当所有字段都是 final 时，构造函数声明为 `const`\n\n### Key 使用：\n\n* \\[ ] 在列表\u002F网格中使用 `ValueKey` 以在重新排序时保持状态\n* \\[ ] 谨慎使用 `GlobalKey` —— 仅在确实需要跨树访问状态时使用\n* \\[ ] 避免在 `build()` 中使用 `UniqueKey` —— 它会强制每帧都重建\n* \\[ ] 当身份基于数据对象而非单个值时，使用 `ObjectKey`\n\n### 主题与设计系统：\n\n* \\[ ] 颜色来自 `Theme.of(context).colorScheme` —— 没有硬编码的 `Colors.red` 或十六进制值\n* \\[ ] 文本样式来自 `Theme.of(context).textTheme` —— 没有内联的 `TextStyle` 和原始字体大小\n* \\[ ] 已验证深色模式兼容性 —— 不假设浅色背景\n* \\[ ] 间距和尺寸使用一致的设计令牌或常量，而不是魔法数字\n\n### Build 方法复杂度：\n\n* \\[ ] `build()` 中没有网络调用、文件 I\u002FO 或繁重计算\n* \\[ ] `build()` 中没有 `Future.then()` 或 `async` 工作\n* \\[ ] `build()` 中没有创建订阅 (`.listen()`)\n* \\[ ] `setState()` 局部化到尽可能小的子树\n\n***\n\n## 4. 状态管理（与库无关）\n\n这些原则适用于所有 Flutter 状态管理方案（BLoC、Riverpod、Provider、GetX、MobX、Signals、ValueNotifier 等）。\n\n### 架构：\n\n* \\[ ] 业务逻辑位于部件层之外 —— 在状态管理组件中（BLoC、Notifier、Controller、Store、ViewModel 等）\n* \\[ ] 状态管理器通过依赖注入接收依赖，而不是内部构造它们\n* \\[ ] 服务或仓库层抽象数据源 —— 部件和状态管理器不应直接调用 API 或数据库\n* \\[ ] 状态管理器职责单一 —— 没有处理不相关职责的“上帝”管理器\n* \\[ ] 跨组件依赖遵循解决方案的约定：\n  * 在 **Riverpod** 中：提供者通过 `ref.watch` 依赖其他提供者是预期的 —— 仅标记循环或过度复杂的链\n  * 在 **BLoC** 中：bloc 不应直接依赖其他 bloc —— 优先使用共享仓库或表示层协调\n  * 在其他解决方案中：遵循文档中关于组件间通信的约定\n\n### 不可变性与值相等性（适用于不可变状态解决方案：BLoC、Riverpod、Redux）：\n\n* \\[ ] 状态对象是不可变的 —— 通过 `copyWith()` 或构造函数创建新实例，绝不就地修改\n* \\[ ] 状态类正确实现 `==` 和 `hashCode`（比较中包含所有字段）\n* \\[ ] 机制在整个项目中保持一致 —— 手动覆盖、`Equatable`、`freezed`、Dart 记录或其他方式\n* \\[ ] 状态对象内部的集合不作为原始可变的 `List`\u002F`Map` 暴露\n\n### 响应式纪律（适用于响应式突变解决方案：MobX、GetX、Signals）：\n\n* \\[ ] 状态仅通过解决方案的响应式 API 进行修改（MobX 中的 `@action`，Signals 上的 `.value`，GetX 中的 `.obs`）—— 直接字段修改会绕过变更跟踪\n* \\[ ] 派生值使用解决方案的计算机制，而不是冗余存储\n* \\[ ] 反应和清理器被正确清理（MobX 中的 `ReactionDisposer`，Signals 中的 effect 清理）\n\n### 状态形状设计：\n\n* \\[ ] 互斥状态使用密封类型、联合变体或解决方案内置的异步状态类型（例如 Riverpod 的 `AsyncValue`）—— 而不是布尔标志 (`isLoading`, `isError`, `hasData`)\n* \\[ ] 每个异步操作都将加载、成功和错误建模为不同的状态\n* \\[ ] UI 中详尽处理所有状态变体 —— 没有静默忽略的情况\n* \\[ ] 错误状态携带用于显示的错误信息；加载状态不携带陈旧数据\n* \\[ ] 可空数据不用于作为加载指示器 —— 状态是明确的\n\n```dart\n\u002F\u002F BAD — boolean flag soup allows impossible states\nclass UserState {\n  bool isLoading = false;\n  bool hasError = false; \u002F\u002F isLoading && hasError is representable!\n  User? user;\n}\n\n\u002F\u002F GOOD (immutable approach) — sealed types make impossible states unrepresentable\nsealed class UserState {}\nclass UserInitial extends UserState {}\nclass UserLoading extends UserState {}\nclass UserLoaded extends UserState {\n  final User user;\n  const UserLoaded(this.user);\n}\nclass UserError extends UserState {\n  final String message;\n  const UserError(this.message);\n}\n\n\u002F\u002F GOOD (reactive approach) — observable enum + data, mutations via reactivity API\n\u002F\u002F enum UserStatus { initial, loading, loaded, error }\n\u002F\u002F Use your solution's observable\u002Fsignal to wrap status and data separately\n```\n\n### 重建优化：\n\n* \\[ ] 状态消费者部件（Builder、Consumer、Observer、Obx、Watch 等）的范围尽可能窄\n* \\[ ] 使用选择器仅在特定字段变化时重建 —— 而不是每次状态发射时\n* \\[ ] 使用 `const` 部件来阻止重建在树中传播\n* \\[ ] 计算\u002F派生状态是响应式计算的，而不是冗余存储的\n\n### 订阅与清理：\n\n* \\[ ] 所有手动订阅 (`.listen()`) 在 `dispose()` \u002F `close()` 中被取消\n* \\[ ] 流控制器在不再需要时关闭\n* \\[ ] 定时器在清理生命周期中被取消\n* \\[ ] 优先使用框架管理的生命周期，而不是手动订阅（声明式构建器优于 `.listen()`）\n* \\[ ] 异步回调中在 `setState` 之前检查 `mounted`\n* \\[ ] 在 `await` 之后使用 `BuildContext` 而不检查 `context.mounted`（Flutter 3.7+）—— 过时的上下文会导致崩溃\n* \\[ ] 在异步间隙后，没有在验证部件仍然挂载的情况下进行导航、显示对话框或脚手架消息\n* \\[ ] `BuildContext` 绝不存储在单例、状态管理器或静态字段中\n\n### 本地状态与全局状态：\n\n* \\[ ] 临时 UI 状态（复选框、滑块、动画）使用本地状态 (`setState`, `ValueNotifier`)\n* \\[ ] 共享状态仅提升到所需的高度 —— 不过度全局化\n* \\[ ] 功能作用域的状态在功能不再活跃时被正确清理\n\n***\n\n## 5. 性能\n\n### 不必要的重建：\n\n* \\[ ] 不在根部件级别调用 `setState()` —— 将状态变化局部化\n* \\[ ] 使用 `const` 部件来阻止重建传播\n* \\[ ] 在独立重绘的复杂子树周围使用 `RepaintBoundary`\n* \\[ ] 使用 `AnimatedBuilder` 的 child 参数处理独立于动画的子树\n\n### build() 中的昂贵操作：\n\n* \\[ ] 不在 `build()` 中对大型集合进行排序、过滤或映射 —— 在状态管理层计算\n* \\[ ] 不在 `build()` 中编译正则表达式\n* \\[ ] `MediaQuery.of(context)` 的使用是具体的（例如，`MediaQuery.sizeOf(context)`）\n\n### 图像优化：\n\n* \\[ ] 网络图像使用缓存（适用于项目的任何缓存解决方案）\n* \\[ ] 为目标设备使用适当的图像分辨率（不为缩略图加载 4K 图像）\n* \\[ ] 使用带有 `cacheWidth`\u002F`cacheHeight` 的 `Image.asset` 以按显示尺寸解码\n* \\[ ] 为网络图像提供占位符和错误部件\n\n### 懒加载：\n\n* \\[ ] 对于大型或动态列表，使用 `ListView.builder` \u002F `GridView.builder` 代替 `ListView(children: [...])`（对于小型、静态列表，具体构造器是可以的）\n* \\[ ] 为大型数据集实现分页\n* \\[ ] 在 Web 构建中对重量级库使用延迟加载 (`deferred as`)\n\n### 其他：\n\n* \\[ ] 在动画中避免使用 `Opacity` 部件 —— 使用 `AnimatedOpacity` 或 `FadeTransition`\n* \\[ ] 在动画中避免裁剪 —— 预裁剪图像\n* \\[ ] 不在部件上重写 `operator ==` —— 使用 `const` 构造器代替\n* \\[ ] 固有尺寸部件 (`IntrinsicHeight`, `IntrinsicWidth`) 谨慎使用（额外的布局传递）\n\n***\n\n## 6. 测试\n\n### 测试类型与期望：\n\n* \\[ ] **单元测试**：覆盖所有业务逻辑（状态管理器、仓库、工具函数）\n* \\[ ] **部件测试**：覆盖单个部件的行为、交互和视觉输出\n* \\[ ] **集成测试**：端到端覆盖关键用户流程\n* \\[ ] **Golden 测试**：对设计关键的 UI 组件进行像素级精确比较\n\n### 覆盖率目标：\n\n* \\[ ] 业务逻辑的目标行覆盖率达到 80% 以上\n* \\[ ] 所有状态转换都有对应的测试（加载 → 成功，加载 → 错误，重试等）\n* \\[ ] 测试边缘情况：空状态、错误状态、加载状态、边界值\n\n### 测试隔离：\n\n* \\[ ] 外部依赖（API 客户端、数据库、服务）已被模拟或伪造\n* \\[ ] 每个测试文件仅测试一个类\u002F单元\n* \\[ ] 测试验证行为，而非实现细节\n* \\[ ] 存根仅定义每个测试所需的行为（最小化存根）\n* \\[ ] 测试用例之间没有共享的可变状态\n\n### 小部件测试质量：\n\n* \\[ ] `pumpWidget` 和 `pump` 被正确用于异步操作\n* \\[ ] `find.byType`、`find.text`、`find.byKey` 使用得当\n* \\[ ] 没有依赖于时序的不可靠测试——使用 `pumpAndSettle` 或显式的 `pump(Duration)`\n* \\[ ] 测试在 CI 中运行，失败会阻止合并\n\n***\n\n## 7. 无障碍功能\n\n### 语义化小部件：\n\n* \\[ ] 使用 `Semantics` 小部件在自动标签不足时提供屏幕阅读器标签\n* \\[ ] 使用 `ExcludeSemantics` 处理纯装饰性元素\n* \\[ ] 使用 `MergeSemantics` 将相关小部件组合成单个可访问元素\n* \\[ ] 图像设置了 `semanticLabel` 属性\n\n### 屏幕阅读器支持：\n\n* \\[ ] 所有交互元素均可聚焦并具有有意义的描述\n* \\[ ] 焦点顺序符合逻辑（遵循视觉阅读顺序）\n\n### 视觉无障碍：\n\n* \\[ ] 文本与背景的对比度 >= 4.5:1\n* \\[ ] 可点击目标至少为 48x48 像素\n* \\[ ] 颜色不是状态的唯一指示器（同时使用图标\u002F文本）\n* \\[ ] 文本随系统字体大小设置缩放\n\n### 交互无障碍：\n\n* \\[ ] 没有无操作的 `onPressed` 回调——每个按钮都有作用或处于禁用状态\n* \\[ ] 错误字段建议更正\n* \\[ ] 用户输入数据时，上下文不会意外改变\n\n***\n\n## 8. 平台特定考量\n\n### iOS\u002FAndroid 差异：\n\n* \\[ ] 在适当的地方使用平台自适应小部件\n* \\[ ] 返回导航处理正确（Android 返回按钮，iOS 滑动返回）\n* \\[ ] 通过 `SafeArea` 小部件处理状态栏和安全区域\n* \\[ ] 平台特定权限在 `AndroidManifest.xml` 和 `Info.plist` 中声明\n\n### 响应式设计：\n\n* \\[ ] 使用 `LayoutBuilder` 或 `MediaQuery` 实现响应式布局\n* \\[ ] 断点定义一致（手机、平板、桌面）\n* \\[ ] 文本在小屏幕上不会溢出——使用 `Flexible`、`Expanded`、`FittedBox`\n* \\[ ] 测试了横屏方向或明确锁定\n* \\[ ] Web 特定：支持鼠标\u002F键盘交互，存在悬停状态\n\n***\n\n## 9. 安全性\n\n### 安全存储：\n\n* \\[ ] 敏感数据（令牌、凭证）使用平台安全存储存储（iOS 上的 Keychain，Android 上的 EncryptedSharedPreferences）\n* \\[ ] 从不以明文存储机密信息\n* \\[ ] 对于敏感操作考虑使用生物识别认证门控\n\n### API 密钥处理：\n\n* \\[ ] API 密钥 NOT 硬编码在 Dart 源代码中——使用 `--dart-define`，`.env` 文件从 VCS 中排除，或使用编译时配置\n* \\[ ] 机密信息未提交到 git——检查 `.gitignore`\n* \\[ ] 对真正的秘密密钥使用后端代理（客户端不应持有服务器机密）\n\n### 输入验证：\n\n* \\[ ] 所有用户输入在发送到 API 前都经过验证\n* \\[ ] 表单验证使用适当的验证模式\n* \\[ ] 没有原始 SQL 或用户输入的字符串插值\n* \\[ ] 深度链接 URL 在导航前经过验证和清理\n\n### 网络安全：\n\n* \\[ ] 所有 API 调用强制使用 HTTPS\n* \\[ ] 对于高安全性应用考虑证书锁定\n* \\[ ] 认证令牌正确刷新和过期\n* \\[ ] 没有记录或打印敏感数据\n\n***\n\n## 10. 包\u002F依赖项审查\n\n### 评估 pub.dev 包：\n\n* \\[ ] 检查 **pub 分数**（目标 130+\u002F160）\n* \\[ ] 检查 **点赞数**和**流行度**作为社区信号\n* \\[ ] 验证发布者在 pub.dev 上**已验证**\n* \\[ ] 检查最后发布日期——过时的包（>1 年）有风险\n* \\[ ] 审查维护者的未解决问题和响应时间\n* \\[ ] 检查许可证与项目的兼容性\n* \\[ ] 验证平台支持是否覆盖您的目标\n\n### 版本约束：\n\n* \\[ ] 对依赖项使用插入符语法（`^1.2.3`）——允许兼容性更新\n* \\[ ] 仅在绝对必要时固定确切版本\n* \\[ ] 定期运行 `flutter pub outdated` 以跟踪过时的依赖项\n* \\[ ] 生产 `pubspec.yaml` 中没有依赖项覆盖——仅用于带有注释\u002F问题链接的临时修复\n* \\[ ] 最小化传递依赖项数量——每个依赖项都是一个攻击面\n\n### 单仓库特定（melos\u002Fworkspace）：\n\n* \\[ ] 内部包仅从公共 API 导入——没有 `package:other\u002Fsrc\u002Finternal.dart`（破坏 Dart 包封装）\n* \\[ ] 内部包依赖项使用工作区解析，而不是硬编码的 `path: ..\u002F..\u002F` 相对字符串\n* \\[ ] 所有子包共享或继承根 `analysis_options.yaml`\n\n***\n\n## 11. 导航和路由\n\n### 通用原则（适用于任何路由解决方案）：\n\n* \\[ ] 一致使用一种路由方法——不混合命令式 `Navigator.push` 和声明式路由器\n* \\[ ] 路由参数是类型化的——没有 `Map\u003CString, dynamic>` 或 `Object?` 转换\n* \\[ ] 路由路径定义为常量、枚举或生成——没有散布在代码中的魔法字符串\n* \\[ ] 认证守卫\u002F重定向集中化——不在各个屏幕中重复\n* \\[ ] 为 Android 和 iOS 配置深度链接\n* \\[ ] 深度链接 URL 在导航前经过验证和清理\n* \\[ ] 导航状态是可测试的——可以在测试中验证路由更改\n* \\[ ] 在所有平台上返回行为正确\n\n***\n\n## 12. 错误处理\n\n### 框架错误处理：\n\n* \\[ ] 重写 `FlutterError.onError` 以捕获框架错误（构建、布局、绘制）\n* \\[ ] 设置 `PlatformDispatcher.instance.onError` 处理 Flutter 未捕获的异步错误\n* \\[ ] 为发布模式自定义 `ErrorWidget.builder`（用户友好而非红屏）\n* \\[ ] 在 `runApp` 周围使用全局错误捕获包装器（例如 `runZonedGuarded`，Sentry\u002FCrashlytics 包装器）\n\n### 错误报告：\n\n* \\[ ] 集成了错误报告服务（Firebase Crashlytics、Sentry 或等效服务）\n* \\[ ] 报告非致命错误并附上堆栈跟踪\n* \\[ ] 状态管理错误观察器连接到错误报告（例如，BlocObserver、ProviderObserver 或适用于您解决方案的等效项）\n* \\[ ] 为调试目的，将用户可识别信息（用户 ID）附加到错误报告\n\n### 优雅降级：\n\n* \\[ ] API 错误导致用户友好的错误 UI，而非崩溃\n* \\[ ] 针对瞬时网络故障的重试机制\n* \\[ ] 优雅处理离线状态\n* \\[ ] 状态管理中的错误状态携带用于显示的错误信息\n* \\[ ] 原始异常（网络、解析）在到达 UI 之前被映射为用户友好的本地化消息——从不向用户显示原始异常字符串\n\n***\n\n## 13. 国际化（l10n）\n\n### 设置：\n\n* \\[ ] 配置了本地化解决方案（Flutter 内置的 ARB\u002Fl10n、easy\\_localization 或等效方案）\n* \\[ ] 在应用配置中声明了支持的语言环境\n\n### 内容：\n\n* \\[ ] 所有用户可见字符串都使用本地化系统——小部件中没有硬编码字符串\n* \\[ ] 模板文件包含翻译人员的描述\u002F上下文\n* \\[ ] 使用 ICU 消息语法处理复数、性别、选择\n* \\[ ] 使用类型定义占位符\n* \\[ ] 跨语言环境没有缺失的键\n\n### 代码审查：\n\n* \\[ ] 在整个项目中一致使用本地化访问器\n* \\[ ] 日期、时间、数字和货币格式化具有语言环境感知能力\n* \\[ ] 如果目标语言是阿拉伯语、希伯来语等，则支持文本方向性（RTL）\n* \\[ ] 本地化文本没有字符串拼接——使用参数化消息\n\n***\n\n## 14. 依赖注入\n\n### 原则（适用于任何 DI 方法）：\n\n* \\[ ] 类在层边界上依赖于抽象（接口），而不是具体实现\n* \\[ ] 依赖项通过构造函数、DI 框架或提供者图从外部提供——而非内部创建\n* \\[ ] 注册区分生命周期：单例 vs 工厂 vs 惰性单例\n* \\[ ] 环境特定绑定（开发\u002F暂存\u002F生产）使用配置，而非运行时 `if` 检查\n* \\[ ] DI 图中没有循环依赖\n* \\[ ] 服务定位器调用（如果使用）没有散布在业务逻辑中\n\n***\n\n## 15. 静态分析\n\n### 配置：\n\n* \\[ ] 存在 `analysis_options.yaml` 并启用了严格设置\n* \\[ ] 严格的分析器设置：`strict-casts: true`、`strict-inference: true`、`strict-raw-types: true`\n* \\[ ] 包含全面的 lint 规则集（very\\_good\\_analysis、flutter\\_lints 或自定义严格规则）\n* \\[ ] 单仓库中的所有子包继承或共享根分析选项\n\n### 执行：\n\n* \\[ ] 提交的代码中没有未解决的分析器警告\n* \\[ ] lint 抑制（`\u002F\u002F ignore:`）有注释说明原因\n* \\[ ] `flutter analyze` 在 CI 中运行，失败会阻止合并\n\n### 无论使用何种 lint 包都要验证的关键规则：\n\n* \\[ ] `prefer_const_constructors`——小部件树中的性能\n* \\[ ] `avoid_print`——使用适当的日志记录\n* \\[ ] `unawaited_futures`——防止即发即弃的异步错误\n* \\[ ] `prefer_final_locals`——变量级别的不可变性\n* \\[ ] `always_declare_return_types`——明确的契约\n* \\[ ] `avoid_catches_without_on_clauses`——具体的错误处理\n* \\[ ] `always_use_package_imports`——一致的导入风格\n\n***\n\n## 状态管理快速参考\n\n下表将通用原则映射到流行解决方案中的实现。使用此表将审查规则调整为项目使用的任何解决方案。\n\n| 原则 | BLoC\u002FCubit | Riverpod | Provider | GetX | MobX | Signals | 内置 |\n|-----------|-----------|----------|----------|------|------|---------|----------|\n| 状态容器 | `Bloc`\u002F`Cubit` | `Notifier`\u002F`AsyncNotifier` | `ChangeNotifier` | `GetxController` | `Store` | `signal()` | `StatefulWidget` |\n| UI 消费者 | `BlocBuilder` | `ConsumerWidget` | `Consumer` | `Obx`\u002F`GetBuilder` | `Observer` | `Watch` | `setState` |\n| 选择器 | `BlocSelector`\u002F`buildWhen` | `ref.watch(p.select(...))` | `Selector` | N\u002FA | computed | `computed()` | N\u002FA |\n| 副作用 | `BlocListener` | `ref.listen` | `Consumer` 回调 | `ever()`\u002F`once()` | `reaction` | `effect()` | 回调 |\n| 处置 | 通过 `BlocProvider` 自动 | `.autoDispose` | 通过 `Provider` 自动 | `onClose()` | `ReactionDisposer` | 手动 | `dispose()` |\n| 测试 | `blocTest()` | `ProviderContainer` | 直接 `ChangeNotifier` | 在测试中 `Get.put` | 直接测试 store | 直接测试 signal | 小部件测试 |\n\n***\n\n## 来源\n\n* [Effective Dart: 风格](https:\u002F\u002Fdart.dev\u002Feffective-dart\u002Fstyle)\n* [Effective Dart: 用法](https:\u002F\u002Fdart.dev\u002Feffective-dart\u002Fusage)\n* [Effective Dart: 设计](https:\u002F\u002Fdart.dev\u002Feffective-dart\u002Fdesign)\n* [Flutter 性能最佳实践](https:\u002F\u002Fdocs.flutter.dev\u002Fperf\u002Fbest-practices)\n* [Flutter 测试概述](https:\u002F\u002Fdocs.flutter.dev\u002Ftesting\u002Foverview)\n* [Flutter 无障碍功能](https:\u002F\u002Fdocs.flutter.dev\u002Fui\u002Faccessibility-and-internationalization\u002Faccessibility)\n* [Flutter 国际化](https:\u002F\u002Fdocs.flutter.dev\u002Fui\u002Faccessibility-and-internationalization\u002Finternationalization)\n* [Flutter 导航和路由](https:\u002F\u002Fdocs.flutter.dev\u002Fui\u002Fnavigation)\n* [Flutter 错误处理](https:\u002F\u002Fdocs.flutter.dev\u002Ftesting\u002Ferrors)\n* [Flutter 状态管理选项](https:\u002F\u002Fdocs.flutter.dev\u002Fdata-and-backend\u002Fstate-mgmt\u002Foptions)\n","# Flutter\u002FDart 代码审查最佳实践\n\n适用于审查 Flutter\u002FDart 应用程序的全面、与库无关的清单。无论使用哪种状态管理方案、路由库或依赖注入框架，这些原则都适用。\n\n***\n\n## 1. 通用项目健康度\n\n* \\[ ] 项目遵循一致的文件夹结构（功能优先或分层优先）\n* \\[ ] 关注点分离得当：UI、业务逻辑、数据层\n* \\[ ] 部件中无业务逻辑；部件纯粹是展示性的\n* \\[ ] `pubspec.yaml` 是干净的 —— 没有未使用的依赖项，版本已适当固定\n* \\[ ] `analysis_options.yaml` 包含严格的 lint 规则集，并启用了严格的分析器设置\n* \\[ ] 生产代码中没有 `print()` 语句 —— 使用 `dart:developer` `log()` 或日志包\n* \\[ ] 生成的文件 (`.g.dart`, `.freezed.dart`, `.gr.dart`) 是最新的或在 `.gitignore` 中\n* \\[ ] 平台特定代码通过抽象进行隔离\n\n***\n\n## 2. Dart 语言陷阱\n\n* \\[ ] **隐式动态类型**：缺少类型注解导致 `dynamic` —— 启用 `strict-casts`, `strict-inference`, `strict-raw-types`\n* \\[ ] **空安全误用**：过度使用 `!`（感叹号操作符）而不是适当的空检查或 Dart 3 模式匹配 (`if (value case var v?)`)\n* \\[ ] **类型提升失败**：在可以使用局部变量类型提升的地方使用了 `this.field`\n* \\[ ] **捕获范围过宽**：`catch (e)` 没有 `on` 子句；应始终指定异常类型\n* \\[ ] **捕获 `Error`**：`Error` 子类型表示错误，不应被捕获\n* \\[ ] **未使用的 `async`**：标记为 `async` 但从未 `await` 的函数 —— 不必要的开销\n* \\[ ] **`late` 过度使用**：在可使用可空类型或构造函数初始化更安全的地方使用了 `late`；将错误推迟到运行时\n* \\[ ] **循环中的字符串拼接**：使用 `StringBuffer` 而不是 `+` 进行迭代式字符串构建\n* \\[ ] **`const` 上下文中的可变状态**：`const` 构造器类中的字段不应是可变的\n* \\[ ] **忽略 `Future` 返回值**：使用 `await` 或显式调用 `unawaited()` 来表明意图\n* \\[ ] **在 `final` 可用时使用 `var`**：局部变量首选 `final`，编译时常量首选 `const`\n* \\[ ] **相对导入**：为保持一致性，使用 `package:` 导入\n* \\[ ] **暴露可变集合**：公共 API 应返回不可修改的视图，而不是原始的 `List`\u002F`Map`\n* \\[ ] **缺少 Dart 3 模式匹配**：优先使用 switch 表达式和 `if-case`，而不是冗长的 `is` 检查和手动类型转换\n* \\[ ] **为多重返回值使用一次性类**：使用 Dart 3 记录 `(String, int)` 代替一次性 DTO\n* \\[ ] **生产代码中的 `print()`**：使用 `dart:developer` `log()` 或项目的日志包；`print()` 没有日志级别且无法过滤\n\n***\n\n## 3. 部件最佳实践\n\n### 部件分解：\n\n* \\[ ] 没有单个部件的 `build()` 方法超过约 80-100 行\n* \\[ ] 部件按封装方式以及按变化方式（重建边界）进行拆分\n* \\[ ] 返回部件的私有 `_build*()` 辅助方法被提取到单独的部件类中（支持元素重用、常量传播和框架优化）\n* \\[ ] 在不需要可变局部状态的地方，优先使用无状态部件而非有状态部件\n* \\[ ] 提取的部件在可复用时放在单独的文件中\n\n### Const 使用：\n\n* \\[ ] 尽可能使用 `const` 构造器 —— 防止不必要的重建\n* \\[ ] 对不变化的集合使用 `const` 字面量 (`const []`, `const {}`)\n* \\[ ] 当所有字段都是 final 时，构造函数声明为 `const`\n\n### Key 使用：\n\n* \\[ ] 在列表\u002F网格中使用 `ValueKey` 以在重新排序时保持状态\n* \\[ ] 谨慎使用 `GlobalKey` —— 仅在确实需要跨树访问状态时使用\n* \\[ ] 避免在 `build()` 中使用 `UniqueKey` —— 它会强制每帧都重建\n* \\[ ] 当身份基于数据对象而非单个值时，使用 `ObjectKey`\n\n### 主题与设计系统：\n\n* \\[ ] 颜色来自 `Theme.of(context).colorScheme` —— 没有硬编码的 `Colors.red` 或十六进制值\n* \\[ ] 文本样式来自 `Theme.of(context).textTheme` —— 没有内联的 `TextStyle` 和原始字体大小\n* \\[ ] 已验证深色模式兼容性 —— 不假设浅色背景\n* \\[ ] 间距和尺寸使用一致的设计令牌或常量，而不是魔法数字\n\n### Build 方法复杂度：\n\n* \\[ ] `build()` 中没有网络调用、文件 I\u002FO 或繁重计算\n* \\[ ] `build()` 中没有 `Future.then()` 或 `async` 工作\n* \\[ ] `build()` 中没有创建订阅 (`.listen()`)\n* \\[ ] `setState()` 局部化到尽可能小的子树\n\n***\n\n## 4. 状态管理（与库无关）\n\n这些原则适用于所有 Flutter 状态管理方案（BLoC、Riverpod、Provider、GetX、MobX、Signals、ValueNotifier 等）。\n\n### 架构：\n\n* \\[ ] 业务逻辑位于部件层之外 —— 在状态管理组件中（BLoC、Notifier、Controller、Store、ViewModel 等）\n* \\[ ] 状态管理器通过依赖注入接收依赖，而不是内部构造它们\n* \\[ ] 服务或仓库层抽象数据源 —— 部件和状态管理器不应直接调用 API 或数据库\n* \\[ ] 状态管理器职责单一 —— 没有处理不相关职责的“上帝”管理器\n* \\[ ] 跨组件依赖遵循解决方案的约定：\n  * 在 **Riverpod** 中：提供者通过 `ref.watch` 依赖其他提供者是预期的 —— 仅标记循环或过度复杂的链\n  * 在 **BLoC** 中：bloc 不应直接依赖其他 bloc —— 优先使用共享仓库或表示层协调\n  * 在其他解决方案中：遵循文档中关于组件间通信的约定\n\n### 不可变性与值相等性（适用于不可变状态解决方案：BLoC、Riverpod、Redux）：\n\n* \\[ ] 状态对象是不可变的 —— 通过 `copyWith()` 或构造函数创建新实例，绝不就地修改\n* \\[ ] 状态类正确实现 `==` 和 `hashCode`（比较中包含所有字段）\n* \\[ ] 机制在整个项目中保持一致 —— 手动覆盖、`Equatable`、`freezed`、Dart 记录或其他方式\n* \\[ ] 状态对象内部的集合不作为原始可变的 `List`\u002F`Map` 暴露\n\n### 响应式纪律（适用于响应式突变解决方案：MobX、GetX、Signals）：\n\n* \\[ ] 状态仅通过解决方案的响应式 API 进行修改（MobX 中的 `@action`，Signals 上的 `.value`，GetX 中的 `.obs`）—— 直接字段修改会绕过变更跟踪\n* \\[ ] 派生值使用解决方案的计算机制，而不是冗余存储\n* \\[ ] 反应和清理器被正确清理（MobX 中的 `ReactionDisposer`，Signals 中的 effect 清理）\n\n### 状态形状设计：\n\n* \\[ ] 互斥状态使用密封类型、联合变体或解决方案内置的异步状态类型（例如 Riverpod 的 `AsyncValue`）—— 而不是布尔标志 (`isLoading`, `isError`, `hasData`)\n* \\[ ] 每个异步操作都将加载、成功和错误建模为不同的状态\n* \\[ ] UI 中详尽处理所有状态变体 —— 没有静默忽略的情况\n* \\[ ] 错误状态携带用于显示的错误信息；加载状态不携带陈旧数据\n* \\[ ] 可空数据不用于作为加载指示器 —— 状态是明确的\n\n```dart\n\u002F\u002F BAD — boolean flag soup allows impossible states\nclass UserState {\n  bool isLoading = false;\n  bool hasError = false; \u002F\u002F isLoading && hasError is representable!\n  User? user;\n}\n\n\u002F\u002F GOOD (immutable approach) — sealed types make impossible states unrepresentable\nsealed class UserState {}\nclass UserInitial extends UserState {}\nclass UserLoading extends UserState {}\nclass UserLoaded extends UserState {\n  final User user;\n  const UserLoaded(this.user);\n}\nclass UserError extends UserState {\n  final String message;\n  const UserError(this.message);\n}\n\n\u002F\u002F GOOD (reactive approach) — observable enum + data, mutations via reactivity API\n\u002F\u002F enum UserStatus { initial, loading, loaded, error }\n\u002F\u002F Use your solution's observable\u002Fsignal to wrap status and data separately\n```\n\n### 重建优化：\n\n* \\[ ] 状态消费者部件（Builder、Consumer、Observer、Obx、Watch 等）的范围尽可能窄\n* \\[ ] 使用选择器仅在特定字段变化时重建 —— 而不是每次状态发射时\n* \\[ ] 使用 `const` 部件来阻止重建在树中传播\n* \\[ ] 计算\u002F派生状态是响应式计算的，而不是冗余存储的\n\n### 订阅与清理：\n\n* \\[ ] 所有手动订阅 (`.listen()`) 在 `dispose()` \u002F `close()` 中被取消\n* \\[ ] 流控制器在不再需要时关闭\n* \\[ ] 定时器在清理生命周期中被取消\n* \\[ ] 优先使用框架管理的生命周期，而不是手动订阅（声明式构建器优于 `.listen()`）\n* \\[ ] 异步回调中在 `setState` 之前检查 `mounted`\n* \\[ ] 在 `await` 之后使用 `BuildContext` 而不检查 `context.mounted`（Flutter 3.7+）—— 过时的上下文会导致崩溃\n* \\[ ] 在异步间隙后，没有在验证部件仍然挂载的情况下进行导航、显示对话框或脚手架消息\n* \\[ ] `BuildContext` 绝不存储在单例、状态管理器或静态字段中\n\n### 本地状态与全局状态：\n\n* \\[ ] 临时 UI 状态（复选框、滑块、动画）使用本地状态 (`setState`, `ValueNotifier`)\n* \\[ ] 共享状态仅提升到所需的高度 —— 不过度全局化\n* \\[ ] 功能作用域的状态在功能不再活跃时被正确清理\n\n***\n\n## 5. 性能\n\n### 不必要的重建：\n\n* \\[ ] 不在根部件级别调用 `setState()` —— 将状态变化局部化\n* \\[ ] 使用 `const` 部件来阻止重建传播\n* \\[ ] 在独立重绘的复杂子树周围使用 `RepaintBoundary`\n* \\[ ] 使用 `AnimatedBuilder` 的 child 参数处理独立于动画的子树\n\n### build() 中的昂贵操作：\n\n* \\[ ] 不在 `build()` 中对大型集合进行排序、过滤或映射 —— 在状态管理层计算\n* \\[ ] 不在 `build()` 中编译正则表达式\n* \\[ ] `MediaQuery.of(context)` 的使用是具体的（例如，`MediaQuery.sizeOf(context)`）\n\n### 图像优化：\n\n* \\[ ] 网络图像使用缓存（适用于项目的任何缓存解决方案）\n* \\[ ] 为目标设备使用适当的图像分辨率（不为缩略图加载 4K 图像）\n* \\[ ] 使用带有 `cacheWidth`\u002F`cacheHeight` 的 `Image.asset` 以按显示尺寸解码\n* \\[ ] 为网络图像提供占位符和错误部件\n\n### 懒加载：\n\n* \\[ ] 对于大型或动态列表，使用 `ListView.builder` \u002F `GridView.builder` 代替 `ListView(children: [...])`（对于小型、静态列表，具体构造器是可以的）\n* \\[ ] 为大型数据集实现分页\n* \\[ ] 在 Web 构建中对重量级库使用延迟加载 (`deferred as`)\n\n### 其他：\n\n* \\[ ] 在动画中避免使用 `Opacity` 部件 —— 使用 `AnimatedOpacity` 或 `FadeTransition`\n* \\[ ] 在动画中避免裁剪 —— 预裁剪图像\n* \\[ ] 不在部件上重写 `operator ==` —— 使用 `const` 构造器代替\n* \\[ ] 固有尺寸部件 (`IntrinsicHeight`, `IntrinsicWidth`) 谨慎使用（额外的布局传递）\n\n***\n\n## 6. 测试\n\n### 测试类型与期望：\n\n* \\[ ] **单元测试**：覆盖所有业务逻辑（状态管理器、仓库、工具函数）\n* \\[ ] **部件测试**：覆盖单个部件的行为、交互和视觉输出\n* \\[ ] **集成测试**：端到端覆盖关键用户流程\n* \\[ ] **Golden 测试**：对设计关键的 UI 组件进行像素级精确比较\n\n### 覆盖率目标：\n\n* \\[ ] 业务逻辑的目标行覆盖率达到 80% 以上\n* \\[ ] 所有状态转换都有对应的测试（加载 → 成功，加载 → 错误，重试等）\n* \\[ ] 测试边缘情况：空状态、错误状态、加载状态、边界值\n\n### 测试隔离：\n\n* \\[ ] 外部依赖（API 客户端、数据库、服务）已被模拟或伪造\n* \\[ ] 每个测试文件仅测试一个类\u002F单元\n* \\[ ] 测试验证行为，而非实现细节\n* \\[ ] 存根仅定义每个测试所需的行为（最小化存根）\n* \\[ ] 测试用例之间没有共享的可变状态\n\n### 小部件测试质量：\n\n* \\[ ] `pumpWidget` 和 `pump` 被正确用于异步操作\n* \\[ ] `find.byType`、`find.text`、`find.byKey` 使用得当\n* \\[ ] 没有依赖于时序的不可靠测试——使用 `pumpAndSettle` 或显式的 `pump(Duration)`\n* \\[ ] 测试在 CI 中运行，失败会阻止合并\n\n***\n\n## 7. 无障碍功能\n\n### 语义化小部件：\n\n* \\[ ] 使用 `Semantics` 小部件在自动标签不足时提供屏幕阅读器标签\n* \\[ ] 使用 `ExcludeSemantics` 处理纯装饰性元素\n* \\[ ] 使用 `MergeSemantics` 将相关小部件组合成单个可访问元素\n* \\[ ] 图像设置了 `semanticLabel` 属性\n\n### 屏幕阅读器支持：\n\n* \\[ ] 所有交互元素均可聚焦并具有有意义的描述\n* \\[ ] 焦点顺序符合逻辑（遵循视觉阅读顺序）\n\n### 视觉无障碍：\n\n* \\[ ] 文本与背景的对比度 >= 4.5:1\n* \\[ ] 可点击目标至少为 48x48 像素\n* \\[ ] 颜色不是状态的唯一指示器（同时使用图标\u002F文本）\n* \\[ ] 文本随系统字体大小设置缩放\n\n### 交互无障碍：\n\n* \\[ ] 没有无操作的 `onPressed` 回调——每个按钮都有作用或处于禁用状态\n* \\[ ] 错误字段建议更正\n* \\[ ] 用户输入数据时，上下文不会意外改变\n\n***\n\n## 8. 平台特定考量\n\n### iOS\u002FAndroid 差异：\n\n* \\[ ] 在适当的地方使用平台自适应小部件\n* \\[ ] 返回导航处理正确（Android 返回按钮，iOS 滑动返回）\n* \\[ ] 通过 `SafeArea` 小部件处理状态栏和安全区域\n* \\[ ] 平台特定权限在 `AndroidManifest.xml` 和 `Info.plist` 中声明\n\n### 响应式设计：\n\n* \\[ ] 使用 `LayoutBuilder` 或 `MediaQuery` 实现响应式布局\n* \\[ ] 断点定义一致（手机、平板、桌面）\n* \\[ ] 文本在小屏幕上不会溢出——使用 `Flexible`、`Expanded`、`FittedBox`\n* \\[ ] 测试了横屏方向或明确锁定\n* \\[ ] Web 特定：支持鼠标\u002F键盘交互，存在悬停状态\n\n***\n\n## 9. 安全性\n\n### 安全存储：\n\n* \\[ ] 敏感数据（令牌、凭证）使用平台安全存储存储（iOS 上的 Keychain，Android 上的 EncryptedSharedPreferences）\n* \\[ ] 从不以明文存储机密信息\n* \\[ ] 对于敏感操作考虑使用生物识别认证门控\n\n### API 密钥处理：\n\n* \\[ ] API 密钥 NOT 硬编码在 Dart 源代码中——使用 `--dart-define`，`.env` 文件从 VCS 中排除，或使用编译时配置\n* \\[ ] 机密信息未提交到 git——检查 `.gitignore`\n* \\[ ] 对真正的秘密密钥使用后端代理（客户端不应持有服务器机密）\n\n### 输入验证：\n\n* \\[ ] 所有用户输入在发送到 API 前都经过验证\n* \\[ ] 表单验证使用适当的验证模式\n* \\[ ] 没有原始 SQL 或用户输入的字符串插值\n* \\[ ] 深度链接 URL 在导航前经过验证和清理\n\n### 网络安全：\n\n* \\[ ] 所有 API 调用强制使用 HTTPS\n* \\[ ] 对于高安全性应用考虑证书锁定\n* \\[ ] 认证令牌正确刷新和过期\n* \\[ ] 没有记录或打印敏感数据\n\n***\n\n## 10. 包\u002F依赖项审查\n\n### 评估 pub.dev 包：\n\n* \\[ ] 检查 **pub 分数**（目标 130+\u002F160）\n* \\[ ] 检查 **点赞数**和**流行度**作为社区信号\n* \\[ ] 验证发布者在 pub.dev 上**已验证**\n* \\[ ] 检查最后发布日期——过时的包（>1 年）有风险\n* \\[ ] 审查维护者的未解决问题和响应时间\n* \\[ ] 检查许可证与项目的兼容性\n* \\[ ] 验证平台支持是否覆盖您的目标\n\n### 版本约束：\n\n* \\[ ] 对依赖项使用插入符语法（`^1.2.3`）——允许兼容性更新\n* \\[ ] 仅在绝对必要时固定确切版本\n* \\[ ] 定期运行 `flutter pub outdated` 以跟踪过时的依赖项\n* \\[ ] 生产 `pubspec.yaml` 中没有依赖项覆盖——仅用于带有注释\u002F问题链接的临时修复\n* \\[ ] 最小化传递依赖项数量——每个依赖项都是一个攻击面\n\n### 单仓库特定（melos\u002Fworkspace）：\n\n* \\[ ] 内部包仅从公共 API 导入——没有 `package:other\u002Fsrc\u002Finternal.dart`（破坏 Dart 包封装）\n* \\[ ] 内部包依赖项使用工作区解析，而不是硬编码的 `path: ..\u002F..\u002F` 相对字符串\n* \\[ ] 所有子包共享或继承根 `analysis_options.yaml`\n\n***\n\n## 11. 导航和路由\n\n### 通用原则（适用于任何路由解决方案）：\n\n* \\[ ] 一致使用一种路由方法——不混合命令式 `Navigator.push` 和声明式路由器\n* \\[ ] 路由参数是类型化的——没有 `Map\u003CString, dynamic>` 或 `Object?` 转换\n* \\[ ] 路由路径定义为常量、枚举或生成——没有散布在代码中的魔法字符串\n* \\[ ] 认证守卫\u002F重定向集中化——不在各个屏幕中重复\n* \\[ ] 为 Android 和 iOS 配置深度链接\n* \\[ ] 深度链接 URL 在导航前经过验证和清理\n* \\[ ] 导航状态是可测试的——可以在测试中验证路由更改\n* \\[ ] 在所有平台上返回行为正确\n\n***\n\n## 12. 错误处理\n\n### 框架错误处理：\n\n* \\[ ] 重写 `FlutterError.onError` 以捕获框架错误（构建、布局、绘制）\n* \\[ ] 设置 `PlatformDispatcher.instance.onError` 处理 Flutter 未捕获的异步错误\n* \\[ ] 为发布模式自定义 `ErrorWidget.builder`（用户友好而非红屏）\n* \\[ ] 在 `runApp` 周围使用全局错误捕获包装器（例如 `runZonedGuarded`，Sentry\u002FCrashlytics 包装器）\n\n### 错误报告：\n\n* \\[ ] 集成了错误报告服务（Firebase Crashlytics、Sentry 或等效服务）\n* \\[ ] 报告非致命错误并附上堆栈跟踪\n* \\[ ] 状态管理错误观察器连接到错误报告（例如，BlocObserver、ProviderObserver 或适用于您解决方案的等效项）\n* \\[ ] 为调试目的，将用户可识别信息（用户 ID）附加到错误报告\n\n### 优雅降级：\n\n* \\[ ] API 错误导致用户友好的错误 UI，而非崩溃\n* \\[ ] 针对瞬时网络故障的重试机制\n* \\[ ] 优雅处理离线状态\n* \\[ ] 状态管理中的错误状态携带用于显示的错误信息\n* \\[ ] 原始异常（网络、解析）在到达 UI 之前被映射为用户友好的本地化消息——从不向用户显示原始异常字符串\n\n***\n\n## 13. 国际化（l10n）\n\n### 设置：\n\n* \\[ ] 配置了本地化解决方案（Flutter 内置的 ARB\u002Fl10n、easy\\_localization 或等效方案）\n* \\[ ] 在应用配置中声明了支持的语言环境\n\n### 内容：\n\n* \\[ ] 所有用户可见字符串都使用本地化系统——小部件中没有硬编码字符串\n* \\[ ] 模板文件包含翻译人员的描述\u002F上下文\n* \\[ ] 使用 ICU 消息语法处理复数、性别、选择\n* \\[ ] 使用类型定义占位符\n* \\[ ] 跨语言环境没有缺失的键\n\n### 代码审查：\n\n* \\[ ] 在整个项目中一致使用本地化访问器\n* \\[ ] 日期、时间、数字和货币格式化具有语言环境感知能力\n* \\[ ] 如果目标语言是阿拉伯语、希伯来语等，则支持文本方向性（RTL）\n* \\[ ] 本地化文本没有字符串拼接——使用参数化消息\n\n***\n\n## 14. 依赖注入\n\n### 原则（适用于任何 DI 方法）：\n\n* \\[ ] 类在层边界上依赖于抽象（接口），而不是具体实现\n* \\[ ] 依赖项通过构造函数、DI 框架或提供者图从外部提供——而非内部创建\n* \\[ ] 注册区分生命周期：单例 vs 工厂 vs 惰性单例\n* \\[ ] 环境特定绑定（开发\u002F暂存\u002F生产）使用配置，而非运行时 `if` 检查\n* \\[ ] DI 图中没有循环依赖\n* \\[ ] 服务定位器调用（如果使用）没有散布在业务逻辑中\n\n***\n\n## 15. 静态分析\n\n### 配置：\n\n* \\[ ] 存在 `analysis_options.yaml` 并启用了严格设置\n* \\[ ] 严格的分析器设置：`strict-casts: true`、`strict-inference: true`、`strict-raw-types: true`\n* \\[ ] 包含全面的 lint 规则集（very\\_good\\_analysis、flutter\\_lints 或自定义严格规则）\n* \\[ ] 单仓库中的所有子包继承或共享根分析选项\n\n### 执行：\n\n* \\[ ] 提交的代码中没有未解决的分析器警告\n* \\[ ] lint 抑制（`\u002F\u002F ignore:`）有注释说明原因\n* \\[ ] `flutter analyze` 在 CI 中运行，失败会阻止合并\n\n### 无论使用何种 lint 包都要验证的关键规则：\n\n* \\[ ] `prefer_const_constructors`——小部件树中的性能\n* \\[ ] `avoid_print`——使用适当的日志记录\n* \\[ ] `unawaited_futures`——防止即发即弃的异步错误\n* \\[ ] `prefer_final_locals`——变量级别的不可变性\n* \\[ ] `always_declare_return_types`——明确的契约\n* \\[ ] `avoid_catches_without_on_clauses`——具体的错误处理\n* \\[ ] `always_use_package_imports`——一致的导入风格\n\n***\n\n## 状态管理快速参考\n\n下表将通用原则映射到流行解决方案中的实现。使用此表将审查规则调整为项目使用的任何解决方案。\n\n| 原则 | BLoC\u002FCubit | Riverpod | Provider | GetX | MobX | Signals | 内置 |\n|-----------|-----------|----------|----------|------|------|---------|----------|\n| 状态容器 | `Bloc`\u002F`Cubit` | `Notifier`\u002F`AsyncNotifier` | `ChangeNotifier` | `GetxController` | `Store` | `signal()` | `StatefulWidget` |\n| UI 消费者 | `BlocBuilder` | `ConsumerWidget` | `Consumer` | `Obx`\u002F`GetBuilder` | `Observer` | `Watch` | `setState` |\n| 选择器 | `BlocSelector`\u002F`buildWhen` | `ref.watch(p.select(...))` | `Selector` | N\u002FA | computed | `computed()` | N\u002FA |\n| 副作用 | `BlocListener` | `ref.listen` | `Consumer` 回调 | `ever()`\u002F`once()` | `reaction` | `effect()` | 回调 |\n| 处置 | 通过 `BlocProvider` 自动 | `.autoDispose` | 通过 `Provider` 自动 | `onClose()` | `ReactionDisposer` | 手动 | `dispose()` |\n| 测试 | `blocTest()` | `ProviderContainer` | 直接 `ChangeNotifier` | 在测试中 `Get.put` | 直接测试 store | 直接测试 signal | 小部件测试 |\n\n***\n\n## 来源\n\n* [Effective Dart: 风格](https:\u002F\u002Fdart.dev\u002Feffective-dart\u002Fstyle)\n* [Effective Dart: 用法](https:\u002F\u002Fdart.dev\u002Feffective-dart\u002Fusage)\n* [Effective Dart: 设计](https:\u002F\u002Fdart.dev\u002Feffective-dart\u002Fdesign)\n* [Flutter 性能最佳实践](https:\u002F\u002Fdocs.flutter.dev\u002Fperf\u002Fbest-practices)\n* [Flutter 测试概述](https:\u002F\u002Fdocs.flutter.dev\u002Ftesting\u002Foverview)\n* [Flutter 无障碍功能](https:\u002F\u002Fdocs.flutter.dev\u002Fui\u002Faccessibility-and-internationalization\u002Faccessibility)\n* [Flutter 国际化](https:\u002F\u002Fdocs.flutter.dev\u002Fui\u002Faccessibility-and-internationalization\u002Finternationalization)\n* [Flutter 导航和路由](https:\u002F\u002Fdocs.flutter.dev\u002Fui\u002Fnavigation)\n* [Flutter 错误处理](https:\u002F\u002Fdocs.flutter.dev\u002Ftesting\u002Ferrors)\n* [Flutter 状态管理选项](https:\u002F\u002Fdocs.flutter.dev\u002Fdata-and-backend\u002Fstate-mgmt\u002Foptions)\n",{"name":5,"origin":24,"description":7},"ECC","master","d6ca01da0f24a3b0e26e4a8b7b66cbd25d429f5d","everything-claude-code\u002Fdocs\u002Fzh-CN\u002Fskills\u002Fflutter-dart-code-review",0,"https:\u002F\u002Fgithub.com\u002FSriramGandhiS\u002FSkills","https:\u002F\u002Fgithub.com\u002FSriramGandhiS","https:\u002F\u002Fsriram.website\u002F","Curious guy who keeps tinkering until something works","2026-05-20 16:21:34",{"source":8,"skillName":5,"commands":35,"prompt":45,"zipAvailable":46},[36,39,42],{"tool":37,"command":38},"npx","npx skills add SriramGandhiS\u002FSkills --skill flutter-dart-code-review",{"tool":40,"command":41},"bunx","bunx skills add SriramGandhiS\u002FSkills --skill flutter-dart-code-review",{"tool":43,"command":44},"pnpm","pnpm dlx skills add SriramGandhiS\u002FSkills --skill flutter-dart-code-review","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FSriramGandhiS\u002FSkills\u002Fblob\u002Fmaster\u002Feverything-claude-code\u002Fdocs\u002Fzh-CN\u002Fskills\u002Fflutter-dart-code-review\u002FSKILL.md",true,[],[49,57,62,68,75,82],{"skillNo":50,"name":51,"nameZh":6,"description":52,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":53,"categories":54,"keywords":55,"publishedAt":56},"01M732609EPJWV13PVTX3GT4TM","webgpu-threejs-tsl","Comprehensive guide for developing WebGPU-enabled Three.js applications using TSL (Three.js Shading Language). Covers WebGPU renderer setup, TSL syntax and node materials, compute shaders, post-processing effects, and WGSL integration. Use this skill when working with Three.js WebGPU, TSL shaders, node materials, or GPU compute in Three.js.","https:\u002F\u002Fgithub.com\u002FSriramGandhiS\u002FSkills\u002Fblob\u002Fmaster\u002Fwebgpu-threejs-tsl\u002Fskills\u002Fwebgpu-threejs-tsl\u002FSKILL.md",[],[],"2026-11-11 15:11:14",{"skillNo":58,"name":51,"nameZh":6,"description":52,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":59,"categories":60,"keywords":61,"publishedAt":56},"01M7325XM47AGWB6K6C4VXKE6B","https:\u002F\u002Fgithub.com\u002FSriramGandhiS\u002FSkills\u002Fblob\u002Fmaster\u002Fwebgpu-threejs-tsl\u002FSKILL.md",[],[],{"skillNo":63,"name":64,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":65,"categories":66,"keywords":67,"publishedAt":56},"01M7325WP6DES69JKC840VMFEP","verification-loop","https:\u002F\u002Fgithub.com\u002FSriramGandhiS\u002FSkills\u002Fblob\u002Fmaster\u002Fweb-assets\u002Fdocs\u002Fzh-TW\u002Fskills\u002Fverification-loop\u002FSKILL.md",[],[],{"skillNo":69,"name":70,"nameZh":6,"description":71,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":72,"categories":73,"keywords":74,"publishedAt":56},"01M7325TFQF1DZTQ6J3WGQQ1VR","tdd-workflow","Use this skill when writing new features, fixing bugs, or refactoring code. Enforces test-driven development with 80%+ coverage including unit, integration, and E2E tests.","https:\u002F\u002Fgithub.com\u002FSriramGandhiS\u002FSkills\u002Fblob\u002Fmaster\u002Fweb-assets\u002Fdocs\u002Fzh-TW\u002Fskills\u002Ftdd-workflow\u002FSKILL.md",[],[],{"skillNo":76,"name":77,"nameZh":6,"description":78,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":79,"categories":80,"keywords":81,"publishedAt":56},"01M7325RGV9AY9PK92D2V8KKPW","strategic-compact","Suggests manual context compaction at logical intervals to preserve context through task phases rather than arbitrary auto-compaction.","https:\u002F\u002Fgithub.com\u002FSriramGandhiS\u002FSkills\u002Fblob\u002Fmaster\u002Fweb-assets\u002Fdocs\u002Fzh-TW\u002Fskills\u002Fstrategic-compact\u002FSKILL.md",[],[],{"skillNo":83,"name":84,"nameZh":6,"description":85,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":86,"categories":87,"keywords":88,"publishedAt":56},"01M7325MZC28SE86E7NMCNEFS4","security-review","Use this skill when adding authentication, handling user input, working with secrets, creating API endpoints, or implementing payment\u002Fsensitive features. Provides comprehensive security checklist and patterns.","https:\u002F\u002Fgithub.com\u002FSriramGandhiS\u002FSkills\u002Fblob\u002Fmaster\u002Fweb-assets\u002Fdocs\u002Fzh-TW\u002Fskills\u002Fsecurity-review\u002FSKILL.md",[],[]]