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 overlay 中檢查重建次數，隔離耗時的 build() 呼叫，套用 const 或將狀態移至更接近消費者

參考指南

根據情境載入詳細指引：

主題	參考文件	載入時機
Riverpod	references/riverpod-state.md	狀態管理、provider、notifier
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 consumer
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()；確認 finder 選擇器
加入套件後建置失敗	不相容的依賴版本	執行 flutter pub upgrade --major-versions；檢查 pub.dev 相容性
卡頓 / 掉幀	耗時的 build() 呼叫、未快取的 widget、主執行緒大量工作	使用 RepaintBoundary，將大量工作移至 compute()，加入 const
Hot reload 未反映變更	狀態保留在未重設的 StateNotifier 中	使用 hot restart（終端機按 R）重設完整應用狀態

輸出模板

實作 Flutter 功能時，提供：

1. 正確使用 const 的 widget 程式碼
2. Provider/Bloc 定義
3. 路由設定（若需要）
4. 測試檔案結構

文件