Flutter Development

Flutter跨端开发技能 (Flutter Development Skill)

快速规则（日常开发时自动加载，只需读到这里）

[Flutter核心清单] ① Widget树保持浅层，提取子Widget而非巨型build() ② 状态管理选型统一（Riverpod/Bloc/Provider三选一），❌禁止混用多种方案 ③ 平台通道优先Pigeon类型安全代码生成，❌禁止手写字符串key的MethodChannel [跨端三禁] ❌在build()中做IO/网络/重计算（build可能每帧调用，阻塞=卡顿） ❌忽略平台差异直接假设行为一致 ❌硬编码像素值不用MediaQuery/LayoutBuilder适配 [硬件铁律] 硬件通信必须有超时+重试+断连处理 | BLE操作必须在连接状态检查后执行 | 传感器数据必须节流(throttle)

写/改Flutter代码时，强制遵守：

1. Widget拆分：单个build()不超过80行，超过→提取为独立Widget/方法。禁止500行的build()（巨型build=diff计算慢+无法局部刷新+不可维护）
2. 状态管理：项目统一一种方案，禁止混用Provider+Bloc+GetX（混用=状态流转不可追踪，debug噩梦）
3. 平台通道：优先Pigeon代码生成→dart:ffi(C/C++)→MethodChannel手写。禁止手写字符串key的MethodChannel不做类型检查（字符串typo=运行时崩溃且编译器无法捕获）
4. 异步处理：所有Future必须处理错误（.catchError或try-catch），禁止裸Future不处理异常（未处理的Future异常=静默失败，数据丢失用户无感知）
5. 生命周期：StatefulWidget中initState初始化，dispose释放（Timer/StreamSubscription/AnimationController），禁止不dispose（内存泄漏+后台持续消耗资源）
6. 适配：用MediaQuery/LayoutBuilder/Expanded/Flexible适配不同屏幕，禁止硬编码像素值（硬编码=小屏溢出大屏留白）
7. Key使用：列表中动态项必须用ValueKey/ObjectKey，禁止用index做key（index做key=增删项时状态错乱，输入框内容跳到错误行）
8. const优化：不变的Widget用const构造，减少不必要的rebuild

完整审查流程（手动 /flutter-development 或专项审查时执行）

Phase 1: 项目结构与配置

1. 标准项目结构：

lib/
├── main.dart              # 入口
├── app.dart               # MaterialApp/CupertinoApp配置
├── core/                  # 核心工具（网络/存储/常量/主题）
│   ├── network/
│   ├── storage/
│   ├── theme/
│   └── constants/
├── features/              # 功能模块（按业务划分）
│   └── feature_name/
│       ├── data/          # 数据层（Repository/DataSource/Model）
│       ├── domain/        # 领域层（Entity/UseCase）
│       └── presentation/  # 表现层（Screen/Widget/Controller）
├── shared/                # 共享组件
│   ├── widgets/
│   └── utils/
└── l10n/                  # 国际化

2. pubspec.yaml规范：

   • 依赖版本锁定（^x.y.z），禁止any或无版本约束（无约束=下次pub get可能拉到不兼容版本导致编译失败）
   • flutter_lints或very_good_analysis启用严格lint
   • 按字母顺序排列dependencies
   • dev_dependencies与dependencies分开

3. Dart语言规范：

   • 启用null safety（Dart 3.x默认）
   • 用final声明不变变量，禁止全用var（var丢失不可变意图，增加误修改风险）
   • 模式匹配（Dart 3.0+）：switch表达式、if-case、解构
   • sealed class替代枚举+联合类型（Dart 3.0+）
   • extension type替代typedef（Dart 3.3+）
   • Records(int, String)替代临时类/Tuple

Phase 2: Widget与UI开发

4. Widget选择速查：

5. 主题与样式：

   • 用Theme.of(context)获取主题色，禁止硬编码Color(0xFF...)（硬编码=换主题时散落各处无法统一修改）
   • Material 3：useMaterial3: true+ColorScheme.fromSeed()
   • 文字样式用Theme.of(context).textTheme.bodyMedium
   • 间距用常量定义（const gap4 = 4.0等）

6. 动画：

   • 简单动画：AnimatedContainer/AnimatedOpacity/AnimatedSwitcher（隐式动画）
   • 复杂动画：AnimationController+Tween（显式动画，dispose中释放controller）
   • Hero动画：Hero(tag:)跨页面元素过渡
   • 禁止在build()中创建AnimationController（每次rebuild创建新controller=内存泄漏+动画混乱）

Phase 3: 状态管理

7. 推荐方案对比：

8. 状态管理铁律：
   • 状态分层：UI状态(loading/error/success) vs 业务状态(用户数据/配置) vs 临时状态(表单输入)
   • UI状态用Widget本地State，业务状态用全局方案
   • 禁止在Widget中直接调HTTP/数据库（Widget只负责展示，数据操作在Repository层）
   • 状态不可变(immutable)：用copyWith()产生新状态，禁止直接修改状态对象属性（直接修改=框架检测不到变化，UI不刷新）

Phase 4: 平台通道与原生交互

9. 平台通道选型（优先级从高到低）：

10. Pigeon使用（推荐方式）：

// 定义接口（pigeons/messages.dart）
@ConfigurePigeon(PigeonOptions(
  dartOut: 'lib/src/messages.g.dart',
  kotlinOut: 'android/app/src/.../Messages.g.kt',
  swiftOut: 'ios/Runner/Messages.g.swift',
))
@HostApi()  // Dart调原生
abstract class DeviceApi {
  @async
  String getDeviceInfo();
  @async
  bool connectDevice(String deviceId);
}

@FlutterApi()  // 原生调Dart
abstract class DeviceCallbackApi {
  void onDeviceDisconnected(String deviceId);
  void onDataReceived(Uint8List data);
}

11. MethodChannel手写（仅简单场景）：

// ❌ 错误：硬编码字符串，无类型安全
final result = await channel.invokeMethod('getDevice', {'id': '123'});

// ✅ 正确：封装+类型安全+错误处理
class DeviceChannel {
  static const _channel = MethodChannel('com.app/device');
  
  Future<DeviceInfo> getDevice(String id) async {
    try {
      final result = await _channel.invokeMethod<Map>('getDevice', {'id': id});
      return DeviceInfo.fromMap(result!);
    } on PlatformException catch (e) {
      throw DeviceException('Failed to get device: ${e.message}');
    }
  }
}

Phase 5: 硬件对接专项

12. BLE蓝牙（推荐库：flutter_blue_plus）：

    • 扫描前检查蓝牙状态+权限（Android需位置权限）
    • 连接必须有超时（默认15秒），禁止无超时连接（设备不响应=永久挂起）
    • 每次操作前检查连接状态，禁止假设已连接（BLE随时可能断连）
    • 读写特征值必须有错误处理+重试（BLE通信不可靠）
    • 断连监听+自动重连策略（指数退避，最多3次）
    • MTU协商：requestMtu(512) 提升吞吐量
    • Android 12+需BLUETOOTH_SCAN/BLUETOOTH_CONNECT权限

13. 传感器/硬件通用规则：

    • 数据流必须节流（throttle/debounce），禁止每次传感器变化都setState（60Hz传感器=每秒60次rebuild=卡死）
    • 后台时暂停监听，前台时恢复（WidgetsBindingObserver.didChangeAppLifecycleState）
    • 硬件不可用时必须有降级方案（模拟数据/提示用户）
    • USB通信（usb_serial）：打开/关闭端口必须配对，异常时确保端口释放

14. 权限处理（permission_handler）：

// 正确的权限请求流程
final status = await Permission.bluetooth.request();
if (status.isGranted) {
  // 执行操作
} else if (status.isPermanentlyDenied) {
  // 引导用户到设置页
  openAppSettings();
} else {
  // 显示说明为什么需要此权限
}

Phase 6: 性能优化

15. 渲染性能：

    • const构造器减少rebuild
    • RepaintBoundary隔离频繁重绘区域
    • 列表用ListView.builder/ListView.separated懒加载
    • 避免Opacity Widget（触发离屏渲染），用AnimatedOpacity或直接改颜色alpha
    • 图片缓存：CachedNetworkImage+cacheWidth/cacheHeight限制解码尺寸

16. 内存管理：

    • dispose中释放所有controller/subscription/timer
    • 大图用ResizeImage或cacheWidth/cacheHeight
    • 避免在State中持有大集合，考虑分页加载
    • 使用DevTools Memory tab检查泄漏

17. 编译与包体积：

    • --split-debug-info分离调试符号
    • --obfuscate代码混淆
    • --tree-shake-icons移除未用图标
    • 分析包体积：flutter build apk --analyze-size

Phase 7: 常见坑与解决方案

18. 高频踩坑清单：

19. 平台差异速查：

Phase 8: 测试与发布

20. 测试策略：

    • Widget测试：testWidgets()+WidgetTester，验证UI渲染和交互
    • 集成测试：integration_test包，真机/模拟器运行
    • 平台通道Mock：TestDefaultBinaryMessengerBinding
    • Golden测试：截图对比UI回归

21. 发布检查清单：

约束

• 项目内只用一种状态管理方案，禁止混用（混用=状态流不可追踪，bug无法定位）
• 平台通道优先Pigeon/FFI代码生成，禁止大量手写字符串key的MethodChannel（字符串typo=运行时崩溃，编译器无法提前发现）
• 硬件通信必须有超时+错误处理+断连恢复，禁止假设连接永远可用（硬件通信天然不可靠，无容错=生产环境频繁崩溃）
• 列表/网格必须用builder懒加载，禁止一次性加载全部数据到Widget（全量加载=OOM+卡顿，100项就能感知到）
• dispose中必须释放所有controller/subscription/timer，禁止遗漏（遗漏=内存泄漏+后台持续执行+电量消耗）
• 传感器/BLE数据流必须节流，禁止每次变化都rebuild（高频rebuild=UI卡死，用户体验为零）