佛系程序员_ Flutter 项目目录全解析（结合实际文件，例子 + 大白话）

学习笔记

网站开发

发布日期: 2026-01-18 14:17:24

喜欢量: 6 个

阅读次数: 55

presentation（页面/组件） &rarr; providers（状态管理） &rarr; domain（实体/仓库接口） &rarr; data（仓库实现） &rarr; core（网络/存储/常量）

缘起：对于完全不懂的Flutter，AI生成代码后，对目录截图，发给AI解释。于是有了下面的：

# 📦 你的 Flutter 项目目录全解析（结合你的实际文件，例子+大白话）
我帮你把这两张图里的文件，按「**目录分组+文件作用+实战例子**」讲清楚，你就能一眼看懂整个项目的分工逻辑，以后维护代码也更清晰。

---

## 🎯 一、`lib/app/` 项目全局配置与启动
这是整个 App 的「总控中心」，负责全局配置和启动。
- **`app.dart`**
  👉 App 的根配置文件，定义 `MaterialApp` 全局配置（主题、路由、语言等），相当于项目的「入口配置文件」。
  例：在这里设置全局主题色、绑定路由表、配置错误页面。
- **`router.dart` / `router.g.dart`**
  👉 路由配置文件，`router.dart` 是你手写的路由定义，`router.g.dart` 是 `auto_route` 自动生成的路由代码。
  例：你在 `router.dart` 里写 `@MaterialAutoRouter` 定义所有页面路由，执行 `build_runner` 就会生成 `router.g.dart`，里面包含路由跳转的具体实现。
- **`theme.dart`**
  👉 全局主题样式配置，定义 App 的颜色、字体、按钮样式等。
  例：在这里定义主色调 `primaryColor: Colors.blue`，所有页面的按钮、导航栏都会自动使用这个颜色。

---

## 🎯 二、`lib/core/` 项目核心基础层
这是项目的「基础设施层」，所有模块都会依赖这里的代码，是整个项目的技术底座。

### 🛠️ `core/constants/` 全局常量
- **`api_constants.dart`**
  👉 存放 API 接口地址常量，避免硬编码。
  例：`const String baseUrl = "https://your-backend.com/api";`、`const String goodsList = "/goods/list";`。
- **`app_constants.dart`**
  👉 存放 App 全局常量，比如版本号、缓存过期时间、页面标题。
  例：`const String appName = "移动贸易平台";`、`const int cacheExpireTime = 3600;`。
- **`storage_keys.dart`**
  👉 本地存储的 Key 常量，统一管理，避免拼写错误。
  例：`const String userInfoKey = "user_info";`、`const String tokenKey = "auth_token";`。

### 🛠️ `core/network/` 网络请求封装
- **`api_client.dart` / `dio_client.dart` / `dio_client.g.dart`**
  👉 网络请求的核心封装，`dio_client.dart` 是基于 `dio` 的底层封装，`api_client.dart` 是业务层的 API 调用封装，`.g.dart` 是 `retrofit` 自动生成的代码。
  例：你在 `api_client.dart` 里用 `@GET("/goods/list")` 定义接口，执行 `build_runner` 就会生成 `dio_client.g.dart`，里面包含完整的请求逻辑。
- **`interceptors/`**
  👉 存放 Dio 的拦截器，比如请求头拦截器、响应拦截器、错误拦截器。
  例：在这里给所有请求自动加上 `token` 请求头，或者统一处理 401 未授权错误。

### 🛠️ `core/providers/` 全局状态管理
- **`user_type_provider.dart` / `user_type_provider.g.dart`**
  👉 全局状态提供者，用 Riverpod 管理用户类型（代理商/供应商）的状态，`.g.dart` 是 Riverpod 自动生成的代码。
  例：你在 `user_type_provider.dart` 里写 `@riverpod` 定义状态，执行 `build_runner` 生成 `.g.dart`，其他页面可以通过 `ref.watch(userTypeProvider)` 获取当前用户类型。

### 🛠️ `core/services/` 全局服务
- **`api_service.dart` / `api_service.g.dart`**
  👉 业务层的 API 服务封装，基于 `retrofit` 生成，统一管理所有接口调用。
  例：你在这里定义 `getGoodsList()`、`createOrder()` 等方法，直接调用即可发起网络请求，不用每次都写 `dio.get()`。
- **`hive_service.dart` / `secure_storage.dart`**
  👉 本地存储服务封装，`hive_service` 是基于 Hive 的轻量级存储，`secure_storage` 是安全存储（存 token、敏感信息）。
  例：用 `hive_service.saveUserInfo(userInfo)` 保存用户信息，用 `secure_storage.getToken()` 获取登录 token。

---

## 🎯 三、`lib/features/` 业务功能模块
这是项目的「业务层」，按功能划分模块（订单、商品、询价等），每个模块都是独立的，遵循 **Clean Architecture** 分层思想，是 Flutter 大型项目的标准写法。

### 📋 以 `features/order/`（订单模块）为例
这是一个完整的业务模块，包含「数据层→领域层→表现层」的完整分层。
1.  **`data/repositories/order_repository_impl.dart`**
    👉 数据实现层，实现领域层定义的仓库接口，负责调用 API、操作本地存储，获取原始数据。
    例：在这里调用 `api_service.getOrderList()` 获取订单列表，然后转换成领域层的 `Order` 实体。
2.  **`domain/entities/order.dart` / `order.freezed.dart` / `order.g.dart`**
    👉 领域实体层，定义订单的数据模型，用 `freezed` + `json_serializable` 生成，是整个模块的数据核心。
    例：你在 `order.dart` 里写 `@freezed` 定义订单的属性（订单号、金额、状态），执行 `build_runner` 生成 `.freezed.dart` 和 `.g.dart`，包含 JSON 转换、copyWith 等方法。
3.  **`domain/repositories/order_repository.dart`**
    👉 领域仓库层，定义订单模块的接口契约，数据层必须实现这些接口，保证领域层和数据层的解耦。
    例：在这里定义 `Future<List<Order>> getOrderList()`、`Future<void> cancelOrder(String orderId)` 等接口，数据层 `order_repository_impl.dart` 来实现这些方法。
4.  **`presentation/pages/`**
    👉 表现层的页面，负责 UI 渲染和用户交互。
    - `order_list_page.dart`：订单列表页（你之前问过的商品列表页就是同一种写法）
    - `order_detail_page.dart`：订单详情页
    - `order_payment_page.dart`：订单支付页
5.  **`presentation/providers/order_providers.dart` / `order_providers.g.dart`**
    👉 模块内的状态管理，用 Riverpod 管理订单模块的局部状态，`.g.dart` 是自动生成的代码。
    例：在这里定义 `orderListNotifierProvider` 管理订单列表的加载状态，页面通过 `ref.watch(orderListNotifierProvider)` 获取数据。
6.  **`presentation/widgets/order_card.dart`**
    👉 模块内的复用组件，订单列表的每个 item 都是这个组件，只负责展示订单信息，逻辑简单。
    例：接收 `Order` 实体，渲染订单号、金额、状态等信息，点击跳转到详情页。

---

## 🎯 四、`.g.dart` 结尾的文件是什么？
你会发现很多文件后面带 `.g.dart`，这些都是 **自动生成的代码文件**，不需要你手写，是通过 `dart run build_runner watch` 命令生成的，核心作用是帮你减少重复代码：
- **`retrofit` 生成**：`dio_client.g.dart`、`api_service.g.dart` → 生成网络请求的具体实现
- **`freezed` 生成**：`order.freezed.dart` → 生成数据模型的 copyWith、toString 等方法
- **`json_serializable` 生成**：`order.g.dart` → 生成 JSON 转实体类的代码
- **`Riverpod` 生成**：`user_type_provider.g.dart`、`order_providers.g.dart` → 生成状态管理的底层代码
- **`auto_route` 生成**：`router.g.dart` → 生成路由跳转的代码

✅ 记住：**永远不要手动修改 `.g.dart` 文件**，修改源文件（比如 `order.dart`、`user_type_provider.dart`）后，执行 `build_runner` 命令重新生成即可。

---

## 🎯 五、整个项目的依赖关系（帮你打通全局逻辑）
```
presentation（页面/组件） → providers（状态管理） → domain（实体/仓库接口） → data（仓库实现） → core（网络/存储/常量）
```
1.  页面通过 `ref.watch()` 获取 providers 的状态
2.  providers 调用 domain 层的仓库接口
3.  仓库接口由 data 层实现，调用 core 层的网络/存储服务
4.  core 层提供基础能力，所有模块共享

这种分层结构的好处是：**业务模块解耦、代码复用性高、维护性强**，比如你要换网络库（从 dio 换成 http），只需要改 `core/network/` 里的代码，所有业务模块都不用动。

---

接下来：整理一份 **模块开发流程清单**，从新建一个功能模块到完成页面开发，一步步告诉你每个文件该写什么，让你按标准流程快速开发新功能。

yyii

http://www.amtb.info/show/Mjg0

本博客所有文章除特別声明外,转载请注明来源佛系程序员 !