2026-02-06 18:19:26 +08:00

4.4 KiB

Raw Blame History

name, description

name	description
Flutter App Expert	包含 Flutter 开发的专家级规则、架构规范和最佳实践。

Flutter App Expert Skill

此 Skill 旨在指导 AI 助手作为一名 Flutter 专家进行编码，遵循 Clean Architecture、Riverpod 状态管理和 Freezed 不可变数据模型等业界最佳实践。

核心原则

Clean Architecture (整洁架构)：严格分层，依赖向内。
Immutability (不可变性)：优先使用不可变状态和数据类。
Feature-First (功能优先)：按功能模块而非技术层级组织代码。

1. 架构分层规范

项目必须遵循以下三层架构：

Domain Layer (核心层)

位置: lib/features/<feature_name>/domain/
内容:
- Entities: 业务对象 (使用 Freezed)。
- Repositories: 抽象接口定义 (Interface)。
- Failures: 业务错误定义。
规则:
- 纯 Dart 代码，不依赖 Flutter UI 库。
- 不依赖 Data 层或 Presentation 层。
- 不包含 JSON 序列化逻辑。

Data Layer (基础设施层)

位置: lib/features/<feature_name>/data/
内容:
- Repositories Impl: 接口的具体实现。
- Data Sources: 远程 API (Dio) 或本地数据库 (Hive/Drift) 调用。
- DTOs (Models): 数据传输对象，负责 JSON 序列化 (使用 json_serializable)。
规则:
- DTO 必须通过 Mapper 转换为 Domain Entity。
- Repository 实现不应直接抛出异常，应返回 Either<Failure, T> 或抛出自定义业务异常。

Presentation Layer (表现层)

位置: lib/features/<feature_name>/presentation/
内容:
- Widgets/Pages: UI 组件。
- Controllers/Notifiers: 状态管理 (Riverpod StateNotifier/AsyncNotifier)。
- States: UI 状态定义 (使用 Freezed)。
规则:
- UI 组件应尽可能为 StatelessWidget (配合 ConsumerWidget)。
- 业务逻辑必须委托给 Controller，UI 只负责渲染状态。

2. 这里的常用库与模式 (Tech Stack)

状态管理: [Riverpod] (使用 Generator 语法 @riverpod 优先)。
数据类: [Freezed] + [json_serializable]。
导航: [GoRouter] (强类型路由)。
网络: [Dio] + [Retrofit] (可选)。
依赖注入: [Riverpod] 本身即为 DI 容器。

3. 这里的编码规范 (Coding Rules)

通用

文件名使用 snake_case (如 user_repository.dart)。
类名使用 PascalCase (如 UserRepository)。
变量名使用 camelCase (如 currentUser)。
优先使用 const 构造函数。

Riverpod 规范

避免在 Repository 中使用 ref。
优先使用 AsyncValue 处理异步状态 (Loading/Error/Data)。

示例:

@riverpod
class AuthController extends _$AuthController {
  @override
  FutureOr<void> build() {}

  Future<void> signIn() async {
    state = const AsyncLoading();
    state = await AsyncValue.guard(() => _repository.signIn());
  }
}

Freezed 规范

Entity 定义:

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

State 定义:

@freezed
class LoginState with _$LoginState {
  const factory LoginState.initial() = _Initial;
  const factory LoginState.loading() = _Loading;
  const factory LoginState.success() = _Success;
  const factory LoginState.error(String message) = _Error;
}

4. 这里的 AI 提示词建议 (System Prompts)

当您要求 AI 写代码时，可以附加以下指令：

"请使用 Flutter Clean Architecture 风格，基于 Riverpod 和 Freezed 实现。请确保 Domain 层不依赖 Data 层，UI 逻辑与业务逻辑分离。"

"生成代码时，请优先使用 Flutter 3.x 新特性，使用 GoRouter 进行路由管理。"

"为这个功能编写 Widget Test，遵循 Given-When-Then 格式，并 Mock 相关的 Providers。"

5. 禁止行为

❌ 禁止在 Domain 层引入 flutter/material.dart。
❌ 禁止在 UI 中直接调用 API，必须通过 Controller。
❌ 禁止手动编写 JSON 解析代码，必须使用 json_serializable。
❌ 禁止使用 GetX (除非项目明确指定)，保持架构统一。

4.4 KiB Raw Blame History Unescape Escape