SuperAPI AI 工具集

flutter

编程与开发

查看项目

更新于 10-16 08:23

技能介绍

用途

本技能面向 Flutter 原生移动应用的生产级开发,提供架构、状态管理、导航、模型、主题、测试与代码生成等方面的实践指导。内容基于 Flutter 团队官方架构指南(2024)、Riverpod 文档、Very Good Ventures 模式以及 Andrea Bizzotto 的架构系列。涉及 API 契约设计、领域建模、设计系统与可观测性时,资料分别指向 /api-design、/domain-design、/ux-design、/observability。

主要能力

架构:MVVM 与分层数据

采用两个强制层加一个可选层。UI 层包含 View(Widget)与 ViewModel(Notifier/Cubit);数据层包含 Repository(每种数据类型单一数据源)与 Service(包装外部 API/数据库,不含业务逻辑)。可选领域层(use cases)仅用于具有跨 ViewModel 共享逻辑的大型应用。

层规则:View 只做无状态渲染,不含业务逻辑、异步、API 调用,不将 BuildContext 泄漏进 ViewModel;ViewModel 每个 View 一个,负责转换展示数据、持有 UI 状态、暴露命令,不引用 Widget、不调用导航、不调用平台 API;Repository 是每种数据类型的单一数据源,抽象数据源、处理缓存、离线优先,且互不感知;Service 是 API/数据库的薄包装,不含业务逻辑。

数据流为单向:用户点击 → View → ViewModel.command() → Repository → Service → API,随后 Repository 发出新状态 → ViewModel 通知 → View 重建。状态向下流动,事件向上流动。

当项目有 OpenAPI 规范时,应生成 API 客户端而非手写:使用 Dart 原生生成器(如 Tonik、swagger_parser),生成的客户端即 Service 层,Repository 包装它;生成代码放在 packages/ 目录并视为不可变,接入项目的 just gen 流水线。具体生成器与命令需查看项目的 CLAUDE.md。

官方设计模式包括:Command 模式(包装 ViewModel 方法,处理 running/complete/error 状态)、Result 返回类型(替代抛异常)、Repository 模式(离线优先、抽象数据源、缓存)、乐观状态(立即更新 UI,失败回滚)。

项目结构:按功能优先

围绕用户行为而非代码类型组织。lib/src 下包含 common_widgets、constants、exceptions、features(每个功能含 presentation/domain/data)、localization、routing、utils。功能是用户所做的事(如 authentication、budgets),而非屏幕名称,每个功能拥有自己的层。

状态管理:Riverpod

使用 flutter_riverpod + riverpod_generator。核心规则:build() 内用 ref.watch(响应式、触发重建),build() 外用 ref.read(一次性、用于事件处理),不可交叉;生成的 provider 默认 autoDispose 以防内存泄漏;状态在 build() 中初始化而非 Notifier 构造函数;Notifier 不暴露公共属性;Notifier build() 中无副作用;异步间隙后使用 ref 需检查 mounted;避免不稳定的 provider 参数。Provider 选择交由 riverpod_generator 通过注解自动决定。仅当监管合规要求事件驱动审计追踪(如严格日志要求的金融应用)时才使用 BLoC。

导航:go_router

Flutter 团队官方推荐,声明式、基于 URL、支持深链接。关键模式:认证守卫用 redirect 参数(必须同步,异步认证检查需变通);底部导航用 StatefulShellRoute 为每个标签维护独立导航栈;深链接定义 URL 模式后由 go_router 自动处理;类型安全参数用 state.pathParameters['id'] 加空值检查。

模型:Freezed

不可变领域模型配合代码生成,是 Riverpod 状态正确性的必要条件。生成 copyWith、==、hashCode、toString、JSON 序列化与联合类型。若项目从 OpenAPI 规范生成模型则直接使用;手写 Freezed 模型仅用于本地领域对象、Drift 数据库伴生对象、视图特定状态对象。规则:模型变更后运行 dart run build_runner build;不手改 *.g.dart 或 *.freezed.dart;货币值用 String 而非 double,匹配后端 BigDecimal/Numeric 契约;所有领域模型用 Freezed,API 响应的 DTO 仅用 json_serializable。

Widget 组合

build() 需保持轻量(动画期间每帧调用);积极使用 const 构造函数(减少 30-40% 重建);可复用 UI 优先用 StatelessWidget 而非辅助方法;将 setState() 局限到最小子树;按变化模式而非仅按大小拆分 Widget。反模式包括:动画中用 Opacity(应用 AnimatedOpacity 或 FadeInImage)、构建大型具体子列表(应用 builder 回调)、saveLayer() 极昂贵(动画中避免 ShaderMask、ColorFilter)、用辅助函数替代 Widget、在 Widget 上重写 operator==。性能工具:RepaintBoundary、ListView.builder/GridView.builder、Isolate.run() 或 compute()。帧预算 60Hz 为 16ms、120Hz 为 8ms,始终在 release 模式分析(flutter run --release),debug 模式慢 10 倍。

主题:Material 3

Flutter 3.16 起 M3 为默认。使用基于种子的颜色系统 ColorScheme.fromSeed,明暗主题用同一种子色;不随意覆盖单个 ColorScheme 颜色;通过 Theme.of(context).colorScheme 访问颜色而非硬编码十六进制。三级覆盖层级:ColorScheme(种子)、组件主题、Widget 级。M3 不存在的令牌(间距、品牌色)通过 ThemeExtension 自定义。深色模式用 MaterialApp 的 theme/darkTheme/themeMode: ThemeMode.system。

测试

奖杯形分布:Widget 测试(flutter_test,约 50%)、单元测试(test,约 30%)、Golden 测试(alchemist,约 10%)、E2E(patrol,约 10%)。原则:用 Fake 而非 Mock(官方推荐);将测试下推;不跨层重复。Mocking 推荐 Mocktail(无代码生成、空安全),大型代码库可用 Mockito。为便于用 Fake 测试,创建抽象 Repository 接口。Golden 测试用于稳定可复用组件的视觉回归,在 CI 中无头运行并作为 PR 门禁。Patrol 处理 integration_test 无法完成的原生交互(系统对话框、权限、生物识别、跨应用测试)。

平台通道

用于原生 iOS/Android 代码集成(生物识别、推送通知、文件系统)。始终处理 PlatformException;流数据(传感器、位置更新)用 EventChannel;优先使用现有插件(local_auth、firebase_messaging)而非自定义通道。

代码生成工作流

模型/provider 变更后运行 dart run build_runner build --delete-conflicting-outputs;开发时用 watch 模式。生成文件(.freezed.dart、.g.dart、*.gen.dart)不可手改。是否提交到版本库由项目决定,但需保持一致。

关键包

状态:flutter_riverpod + riverpod_generator;导航:go_router;模型:freezed + json_serializable;代码生成:build_runner;HTTP:dio;本地存储:drift(SQL)或 shared_preferences(KV);Lint:flutter_lints + custom_lint;测试:mocktail、patrol、alchemist;主题代码生成:theme_tailor。

反模式摘要

ref.read 用于 build()(数据陈旧)、ref.watch 用于 build() 外(不必要重建)、View 中含业务逻辑、货币用 double、可复用 UI 用辅助函数、debug 模式分析性能、动画中用 Opacity、Repository 互相感知、Notifier 构造函数中含逻辑、使用 GetX(维护模式、魔法全局)。

共享资源

当 Web 与移动端共享同一 API 时也共享翻译:Web 语言文件(JSON/i18next)为事实来源,通过转换脚本从 Web JSON 生成移动端 ARB 文件,接入构建流水线保持同步,不手动跨平台重复翻译键。存在 OpenAPI 规范时,从同一规范为所有平台生成客户端,派生链为:API 代码 → OpenAPI 规范 → 生成的客户端。

使用方式

资料未提供该技能的具体安装命令或调用步骤,暂未提供。

适用场景

适用于 Flutter 原生移动应用的生产级开发,尤其是需要清晰分层架构、可测试状态管理、声明式导航与代码生成工作流的项目。

限制

资料未说明该技能的收费、价格、平台支持范围或效果保证,暂未提供。