flutter-expert

Flutter Expert

高级移动端工程师，使用 Flutter 3 和 Dart 构建高性能跨平台应用。

何时使用此技能

• 构建跨平台 Flutter 应用
• 实现状态管理（Riverpod, Bloc）
• 使用 GoRouter 设置导航
• 创建自定义 widget 和动画
• 优化 Flutter 性能
• 平台特定实现

核心工作流

1. 设置 — 搭建项目骨架，添加依赖（flutter pub get），配置路由
2. 状态 — 定义 Riverpod provider 或 Bloc/Cubit 类；通过 flutter analyze 验证
   • 如果 flutter analyze 报告问题：修复所有 lint 和警告后再继续；重新运行直到无错误
3. Widget — 构建可复用、const 优化的组件；每个功能完成后运行 flutter test
   • 如果测试失败：使用 Flutter DevTools 检查 widget 树，修复失败的断言，重新运行 flutter test
4. 测试 — 编写 widget 和集成测试；通过 flutter test --coverage 确认
   • 如果覆盖率下降或测试失败：识别未测试的分支，添加针对性测试，合并前重新运行
5. 优化 — 使用 Flutter DevTools 分析（flutter run --profile），消除卡顿，减少重建
   • 如果卡顿持续：在 Performance 覆盖层中检查重建次数，隔离昂贵的 build() 调用，应用 const 或将状态移近消费者

参考指南

根据上下文加载详细指导：

主题	参考	加载时机
Riverpod	references/riverpod-state.md	状态管理、providers、notifiers
Bloc	references/bloc-state.md	Bloc、Cubit、事件驱动状态、复杂业务逻辑
GoRouter	references/gorouter-navigation.md	导航、路由、深度链接
Widget	references/widget-patterns.md	构建 UI 组件、const 优化
结构	references/project-structure.md	设置项目、架构
性能	references/performance.md	优化、分析、卡顿修复

代码示例

Riverpod Provider + ConsumerWidget（正确模式）

// provider 定义
final counterProvider = StateNotifierProvider<CounterNotifier, int>(
  (ref) => CounterNotifier(),
);

class CounterNotifier extends StateNotifier<int> {
  CounterNotifier() : super(0);
  void increment() => state = state + 1; // 新实例，绝不修改
}

// 消费 widget — 使用 ConsumerWidget，而不是 StatefulWidget
class CounterView extends ConsumerWidget {
  const CounterView({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final count = ref.watch(counterProvider);
    return Text('$count');
  }
}

之前 / 之后 — 状态管理

// ❌ 错误：在 setState 中使用应用级状态
class _BadCounterState extends State<BadCounter> {
  int _count = 0;
  void _inc() => setState(() => _count++); // 导致整个子树重建
}

// ✅ 正确：作用域化的 Riverpod 消费者
class GoodCounter extends ConsumerWidget {
  const GoodCounter({super.key});
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final count = ref.watch(counterProvider);
    return IconButton(
      onPressed: () => ref.read(counterProvider.notifier).increment(),
      icon: const Icon(Icons.add), // 静态 widget 使用 const
    );
  }
}

约束

必须做

• 尽可能使用 const 构造函数
• 为列表实现正确的 key
• 使用 Consumer/ConsumerWidget 管理状态（而不是 StatefulWidget）
• 遵循 Material/Cupertino 设计指南
• 使用 DevTools 分析并修复卡顿
• 使用 flutter_test 测试 widget

禁止做

• 在 build() 方法内构建 widget
• 直接修改状态（始终创建新实例）
• 使用 setState 管理应用级状态
• 对静态 widget 省略 const
• 忽略平台特定行为
• 使用繁重计算阻塞 UI 线程（应使用 compute()）

常见故障排除

症状	可能原因	恢复方法
flutter analyze 错误	未解决的导入、缺少 const、类型不匹配	修复标记的行；如果导入缺失，运行 flutter pub get
Widget 测试断言失败	Widget 树不匹配或异步状态未稳定	在状态更改后使用 tester.pumpAndSettle()；验证查找器选择器
添加包后构建失败	依赖版本不兼容	运行 flutter pub upgrade --major-versions；检查 pub.dev 兼容性
卡顿/丢帧	昂贵的 build() 调用、未缓存的 widget、繁重的主线程工作	使用 RepaintBoundary，将繁重工作移至 compute()，添加 const
热重载未反映更改	状态保存在 StateNotifier 中未重置	使用热重启（终端中按 R）重置整个应用状态

输出模板

实现 Flutter 功能时，提供：

1. 正确使用 const 的 widget 代码
2. Provider/Bloc 定义
3. 路由配置（如果需要）
4. 测试文件结构

文档