132 lines
4.4 KiB
Markdown
132 lines
4.4 KiB
Markdown
---
|
||
name: Flutter App Expert
|
||
description: 包含 Flutter 开发的专家级规则、架构规范和最佳实践。
|
||
---
|
||
|
||
# Flutter App Expert Skill
|
||
|
||
此 Skill 旨在指导 AI 助手作为一名 Flutter 专家进行编码，遵循 Clean Architecture、Riverpod 状态管理和 Freezed 不可变数据模型等业界最佳实践。
|
||
|
||
## 核心原则
|
||
|
||
1. **Clean Architecture (整洁架构)**：严格分层，依赖向内。
|
||
2. **Immutability (不可变性)**：优先使用不可变状态和数据类。
|
||
3. **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)。
|
||
* **示例**:
|
||
```dart
|
||
@riverpod
|
||
class AuthController extends _$AuthController {
|
||
@override
|
||
FutureOr<void> build() {}
|
||
|
||
Future<void> signIn() async {
|
||
state = const AsyncLoading();
|
||
state = await AsyncValue.guard(() => _repository.signIn());
|
||
}
|
||
}
|
||
```
|
||
|
||
### Freezed 规范
|
||
* **Entity 定义**:
|
||
```dart
|
||
@freezed
|
||
class User with _$User {
|
||
const factory User({
|
||
required String id,
|
||
required String name,
|
||
}) = _User;
|
||
}
|
||
```
|
||
* **State 定义**:
|
||
```dart
|
||
@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` (除非项目明确指定)，保持架构统一。
|