Everything Claude Code 的 dart-flutter-patterns Skill 是一套面向生产环境的 Dart/Flutter 代码模式库，涵盖 null safety、不可变状态、异步组合、主流状态管理（BLoC、Riverpod）、GoRouter 导航、Dio 网络、Freezed 代码生成等关键场景。它为使用 Claude Code、Codex、Cursor 等 AI 编程助手的开发者提供了可直接复用的高质量模式和代码片段，显著提升 Flutter 项目的开发效率、代码安全性与可维护性。

Everything Claude Code Dart Flutter Patterns Skill：null safety、BLoC/Riverpod/GoRouter/Freezed 生产级模式

在 Dart/Flutter 项目中，如何高效落地 null safety、状态管理、导航、不可变数据、异步处理等最佳实践，一直是团队迈向生产级质量的关键。Everything Claude Code 的 dart-flutter-patterns Skill，正是为此而生：它将社区主流的 Flutter 架构模式、常见生态库（如 BLoC、Riverpod、GoRouter、Dio、Freezed）和易错点，整理为一套可直接调用的 AI 辅助技能，极大降低了从“会用”到“用对”的门槛。

无论你是新建 Flutter 功能、重构遗留代码、还是为团队制定统一的代码规范，这个 Skill 都能为你和 AI 编程助手提供结构化、可落地的决策依据和代码模板。它既适用于初学者，也支持深度定制和扩展，是 Everything Claude Code Skill/Agent/Hook/Rules 体系 在 Dart/Flutter 领域的核心能力之一。

1. 适用场景与激活时机

dart-flutter-patterns Skill 会在以下典型场景被自动触发或建议使用：

• 新建 Flutter 功能或页面，需要选型状态管理、导航、数据访问等架构模式时
• 代码审查/重构，希望统一 null safety、sealed types、不可变数据等规范
• 集成 BLoC、Riverpod、Provider 等主流状态管理方案时
• 实现安全的 HTTP 客户端、WebView、本地存储 等基础设施时
• 为 Widget、Cubit、Provider 编写测试用例，或需要 mock/fake 支持时
• 配置 GoRouter 路由守卫、实现登录跳转、权限控制 时

Skill 会根据当前代码上下文、任务类型和相关 Agent 的请求自动推荐对应模式，也支持通过命令行或 MCP 直接调用。

2. 使用流程 Step by Step

步骤 1：确定目标场景

假设你要新建一个带登录鉴权、商品列表、购物车的 Flutter 应用，需要：

• null 安全和不可变数据
• 选择状态管理（如 BLoC 或 Riverpod）
• 配置路由和导航守卫（如 GoRouter）
• 网络请求与错误处理（如 Dio）
• 便于测试和扩展

步骤 2：激活 Skill 并选择模式

在 Claude Code/Codex/Cursor 等 AI 编程助手中：

• 输入任务描述（如“实现带鉴权的购物车页面，要求 Riverpod 管理状态、GoRouter 控制导航”）
• AI 自动匹配并调用 dart-flutter-patterns Skill，结合上下文给出推荐模式和代码片段

步骤 3：复用/定制代码模板

Skill 会输出结构化的代码建议，覆盖以下典型模式：

Null Safety（空安全）

// 推荐写法，避免 ! 运算符
final name = user?.name ?? 'Unknown';

// 复杂场景推荐 Dart 3 pattern matching
final display = switch (user) {
  User(:final name, :final email) => '$name <$email>',
  null => 'Guest',
};

不可变状态与 Freezed

@freezed
class User with _$User {
  const factory User({
    required String id,
    required String name,
    required String email,
    @Default(false) bool isAdmin,
  }) = _User;
}

BLoC/Cubit 状态管理

class AuthCubit extends Cubit<AuthState> {
  // ...
  Future<void> login(String email, String password) async {
    emit(const AuthState.loading());
    try {
      final user = await _authService.login(email, password);
      emit(AuthState.authenticated(user));
    } on AuthException catch (e) {
      emit(AuthState.error(e.message));
    }
  }
}

Riverpod 状态管理

@riverpod
class CartNotifier extends _$CartNotifier {
  @override
  List<CartItem> build() => [];

  void add(Product product) {
    // ...
  }
}

GoRouter 导航与鉴权

final router = GoRouter(
  refreshListenable: GoRouterRefreshStream(authCubit.stream),
  redirect: (context, state) {
    final authed = context.read<AuthCubit>().state is AuthAuthenticated;
    if (!authed && !state.matchedLocation.startsWith('/login')) return '/login';
    return null;
  },
  routes: [...],
);

Dio 网络请求与 Token 刷新

dio.interceptors.add(InterceptorsWrapper(
  onRequest: (options, handler) async {
    final token = await secureStorage.read(key: 'auth_token');
    if (token != null) options.headers['Authorization'] = 'Bearer $token';
    handler.next(options);
  },
  onError: (error, handler) async {
    // 只重试一次，防止无限循环
    final isRetry = error.requestOptions.extra['_isRetry'] == true;
    if (!isRetry && error.response?.statusCode == 401) {
      final refreshed = await attemptTokenRefresh();
      if (refreshed) {
        error.requestOptions.extra['_isRetry'] = true;
        return handler.resolve(await dio.fetch(error.requestOptions));
      }
    }
    handler.next(error);
  },
));

测试模式

testWidgets('CartBadge shows item count', (tester) async {
  await tester.pumpWidget(
    ProviderScope(
      overrides: [cartNotifierProvider.overrideWith(() => FakeCartNotifier(count: 3))],
      child: const MaterialApp(home: CartBadge()),
    ),
  );
  expect(find.text('3'), findsOneWidget);
});

步骤 4：结合 Agent/Skill 协作

• 代码审查：与 Flutter Dart Code Review Skill 联动，自动检查模式落地情况
• 构建/调试：配合 Dart Build Resolver Agent 快速定位构建和依赖问题
• 文档/规范：结合 Rules 体系 自动补全注释、风格和安全规则

Skill 也支持与自动化 Hook（如 PreToolUse、PostToolUse）集成，实现代码生成、审查、测试的流水线自动化。更多自动化配置可参考 Everything Claude Code Hooks 实战。

步骤 5：持续迭代与自定义

• 可根据团队实际需求，扩展 Skill 支持的模式（如自定义 Provider、异步缓存、复杂导航等）
• 支持与 MCP/Agent Harness 等高级特性集成，打造团队专属的 Flutter 研发工作流

3. 输出预期与示例

Skill 输出内容结构清晰，通常包括：

• 推荐模式的简要说明
• 可直接复制的代码片段
• 适用场景与常见坑提示
• 与当前项目/Agent 的集成建议

示例输出片段：

// 推荐：sealed class 管理异步状态
sealed class AsyncState<T> {}
final class Loading<T> extends AsyncState<T> {}
final class Success<T> extends AsyncState<T> { final T data; const Success(this.data); }
final class Failure<T> extends AsyncState<T> { final Object error; const Failure(this.error); }

4. 常见配套 Agent 与 Skill 协作

• 代码质量/安全审查：Flutter Dart Code Review Skill
• 构建与依赖修复：Dart Build Resolver Agent
• 文档自动补全：Doc Updater Agent
• 规则与风格统一：Rules 体系

Skill 设计为库无关（library-agnostic），但对主流生态包（如 Riverpod、BLoC、GoRouter、Freezed、Dio）有专门适配，适合大中型 Flutter 项目和团队协作场景。

5. 常见问题与注意事项

• Skill 输出代码是否可直接用于生产？
  是，所有模式均为生产级最佳实践，建议结合团队实际需求和代码风格适当调整。

• 支持哪些 Flutter 生态库？
  Skill 默认覆盖 BLoC、Riverpod、Provider、GoRouter、Dio、Freezed 等主流库，也支持自定义扩展。

• 如何与其他 Claude Code 组件集成？
  可与 Agent、Hooks、Rules 体系无缝协作，详见 Everything Claude Code 完全指南 与 Hooks 实战。

---

FAQ

Q: Skill 会自动选用 BLoC 还是 Riverpod 吗？
A: Skill 会根据上下文和项目依赖自动推荐适合的状态管理模式，也支持用户指定。

Q: 输出的模式能否和现有代码无缝集成？
A: 可以，Skill 设计时充分考虑与遗留代码和团队风格的兼容性，支持渐进式接入。

Q: 如何自定义或扩展 Skill 支持的模式？
A: 可通过 Skill 配置文件或 MCP 扩展，添加自定义 Provider、异步缓存等团队专用模式。

---