# quick_frame_work

**Repository Path**: caojingCode/quick_frame_work

## Basic Information

- **Project Name**: quick_frame_work
- **Description**: Flutter快速开发框架
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 0
- **Created**: 2026-05-27
- **Last Updated**: 2026-06-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Flutter Quick Framework

这是一套基于 Flutter 官方推荐最佳实践搭建的 **企业级快速开发脚手架**。
采用按业务模块（Feature-based）与按层级（Layer-based）相结合的混合架构，核心集成了目前最主流的黄金技术栈，帮助团队实现“开箱即用”。

## 核心技术栈选型

*   **状态管理**: [Riverpod](https://riverpod.dev/) - 天然支持异步数据流，类型安全，极其适合快速生成 UI 状态。
*   **路由管理**: [GoRouter](https://pub.dev/packages/go_router) - 声明式路由，完美支持深度链接 (Deep Link) 与路由拦截。
*   **网络请求**: [Dio](https://pub.dev/packages/dio) - 强大的网络库，已内置全局异常拦截与基础模型转换。
*   **依赖注入**: [GetIt](https://pub.dev/packages/get_it) - 负责管理全局单例服务（如本地缓存实例、HTTP 服务等）。
*   **本地存储**: [SharedPreferences](https://pub.dev/packages/shared_preferences) - 轻量级 KV 存储。
*   **代码生成**: `build_runner`, `json_serializable`, `flutter_gen`。

---

## 目录结构说明

项目采用“高内聚，低耦合”的设计思想，目录结构如下：

```text
lib/
├── app/                  # 应用全局配置 (与具体业务无关的全局配置)
│   ├── app_binding.dart  # 全局依赖注入注册 (GetIt)
│   ├── config/           # 全局常量、环境配置 (如 Env)
│   ├── routes/           # 路由管理 (包含 GoRouter 拦截器)
│   └── theme/            # 全局皮肤、主题、字体样式
├── core/                 # 核心公共基础模块 (基建)
│   ├── http/             # Dio 二次封装、网络拦截器、标准返回体 ApiResponse
│   ├── storage/          # 本地缓存封装
│   └── utils/            # 通用工具类 (如日志、扩展、Toast)
├── features/             # 业务功能模块 (按业务拆分包)
│   ├── auth/             # 示例：登录/鉴权模块
│   │   ├── data/         # 鉴权相关数据源与模型
│   │   ├── logic/        # 鉴权相关状态管理 (Riverpod Providers)
│   │   └── views/        # 登录相关的 UI (Page/Widget)
│   └── home/             # 示例：首页模块
└── main.dart             # 应用入口，包含初始化逻辑
```

---

## 快速上手 (How to Use)

### 1. 新建业务模块 (Feature)
当你需要开发一个新功能（如“个人中心 Profile”）时：
1. 在 `lib/features/` 下新建 `profile` 文件夹。
2. 在内部创建 `views` (UI组件)、`logic` (状态管理)、`data` (网络模型) 三个文件夹。
3. 业务代码严格收拢在该文件夹下。

### 2. 发起网络请求
框架已经在 `lib/core/http/http_service.dart` 中对 Dio 进行了标准化封装，并返回统一的 `ApiResponse<T>`。

```dart
// 1. 获取网络服务实例
final http = locator<HttpService>();

// 2. 发起请求
final response = await http.get<Map<String, dynamic>>('/api/user/info');

// 3. 处理结果
if (response.isSuccess) {
  print(response.data); 
} else {
  // 错误信息已由底层统一处理并抛出
  print(response.message); 
}
```
> **注意**：你需要前往 `http_service.dart` 将 `baseUrl` 替换为你实际的后端域名。若后端返回的数据结构不同，请同步修改 `api_response.dart` 中的 `fromJson` 解析逻辑。

### 3. 添加页面路由与拦截
所有的路由配置都在 `lib/app/routes/app_router.dart` 中。

```dart
GoRoute(
  path: '/profile',
  builder: (context, state) => const ProfileScreen(),
),
```

**鉴权拦截器 (Auth Guard)：**
框架已内置了一个简单的全局登录拦截逻辑：
在 `GoRouter` 的 `redirect` 回调中，会自动检查 `StorageService` 中是否存有 `token`。如果没有，则自动拦截重定向到 `/login` 页面。

### 4. 依赖注入与单例获取
当你需要使用本地存储或其他全局服务时，无需自己维护单例，直接通过 `locator` 获取：

```dart
// 存储数据
final storage = locator<StorageService>();
await storage.setString('token', 'your_jwt_token_here');

// 读取数据
final token = storage.getString('token');
```
> 若需新增全局服务，请前往 `lib/app/app_binding.dart` 中进行注册。

### 5. 状态管理 (Riverpod)
应用顶层已注入 `ProviderScope`。在业务模块的 `logic` 层编写你的 Provider，并在 `views` 层的 UI 中使用 `ConsumerWidget` 或 `Consumer` 进行状态绑定即可。

---

## 开发避坑与最佳实践

1. **组合优于继承**：尽量避免将页面基类 (BasePage) 的继承层级设计得太深，建议使用 Wrapper 模式（如封装一个通用的 `LoadingStateWrapper` Widget 来包裹实际页面）。
2. **保持第三方库弹性**：网络层的封装已经提供了基础的 Error Handling，如果某些特殊接口需要自定义 header，直接通过 `http.get(options: Options(...))` 传入即可，不要把 Dio 封装得太死。
3. **拥抱代码生成**：复杂 JSON 解析建议搭配 `json_serializable`，图片资源管理建议搭配 `flutter_gen`，以此避免由于拼写错误带来的低级 Bug。

---

> 开始享受高效的 Flutter 开发之旅吧