# flutter_app_framework

**Repository Path**: GrapeM/flutter_app_framework

## Basic Information

- **Project Name**: flutter_app_framework
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-08
- **Last Updated**: 2025-12-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Flutter 多模块应用框架

基于 Flutter 官方推荐的 Monorepo 结构，使用[melos](https://melos.invertase.dev/)管理依赖，使用 GetX 进行状态管理、路由和依赖注入。




## 📁 项目结构

```
app_framework/
├── app/                           # 主应用（壳工程）
│   ├── lib/
│   │   └── main.dart
│   ├── android/
│   ├── ios/
│   ├── test/
│   └── pubspec.yaml
├── packages/                      # 模块目录
│   ├── shared/                    # 共享基础模块
│   │   ├── lib/
│   │   │   ├── shared.dart        # 统一导出
│   │   │   └── src/
│   │   │       ├── base/          # 基础类
│   │   │       ├── constants/     # 常量
│   │   │       ├── extensions/    # 扩展
│   │   │       ├── i18n/          # 国际化
│   │   │       ├── network/       # 网络层
│   │   │       ├── services/      # 全局服务
│   │   │       ├── theme/         # 主题
│   │   │       ├── utils/         # 工具类
│   │   │       └── widgets/       # 通用组件
│   │   └── pubspec.yaml
│   ├── feature_home/              # 首页功能模块
│   ├── feature_settings/          # 设置功能模块
│   └── feature_user/              # 用户功能模块
├── melos.yaml                     # Melos 配置（多模块管理）
├── pubspec.yaml                   # 工作区配置
├── analysis_options.yaml          # 代码分析配置
└── README.md
```

## 🔗 模块依赖关系

```
┌─────────────────────────────────────────┐
│              app/ (主应用)               │
│           应用入口、路由整合              │
├─────────────────────────────────────────┤
│        packages/feature_xxx/             │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│  │  home    │ │settings  │ │  user    │ │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│       └────────────┼────────────┘       │
├────────────────────┼────────────────────┤
│           packages/shared/               │
│   (主题、组件、UI服务、国际化、常量)       │
│                    ↓                     │
├─────────────────────────────────────────┤
│           packages/core/                 │
│   (网络、存储、日志、工具类、基础类)       │
└─────────────────────────────────────────┘
```

**依赖说明：**
- `core`: 纯 Dart 核心功能，无 UI 依赖
- `shared`: UI 相关共享功能，依赖 core
- `feature_xxx`: 业务功能模块，依赖 shared（自动包含 core）

## 📚 核心模块详解

### Core 模块（packages/core/）

**定位：** 纯 Dart 核心功能层，不依赖 Flutter UI

**包含：**
- `base/` - 基础抽象类（BaseRepository, BaseUseCase 等）
- `network/` - 网络层封装（Dio, HTTP client, API client）
- `storage/` - 本地存储（SharedPreferences, Hive, SQLite）
- `logger/` - 日志系统
- `utils/` - 通用工具类（日期、加密、验证等）
- `extensions/` - Dart 扩展方法

**特点：**
- ✅ 无 Flutter 依赖，可用于纯 Dart 项目
- ✅ 可独立测试
- ✅ 可复用到其他项目

### Shared 模块（packages/shared/）

**定位：** UI 基础层，提供通用 UI 组件和服务

**包含：**
- `base/` - UI 基础类（BaseController, BasePage）
- `theme/` - 应用主题（颜色、文本样式、主题配置）
- `widgets/` - 通用 UI 组件（按钮、输入框、加载组件等）
- `constants/` - UI 常量
- `i18n/` - 国际化翻译
- `services/` - UI 相关服务（主题服务、语言服务）
- `utils/` - UI 工具类（对话框、Toast 等）

**特点：**
- ✅ 依赖 core 模块
- ✅ 重新导出 core，feature 模块只需依赖 shared
- ✅ 提供统一的 UI 基础设施

### Feature 模块（packages/feature_xxx/）

**定位：** 业务功能模块

**包含：**
- `xxx_page.dart` - 页面 UI
- `xxx_controller.dart` - GetX 控制器
- `xxx_binding.dart` - 依赖注入
- `xxx_routes.dart` - 路由定义

**特点：**
- ✅ 只依赖 shared（自动包含 core）
- ✅ 业务逻辑独立
- ✅ 可独立开发和测试

## 🚀 快速开始

### 方式一：手动获取依赖

```bash
# 1. 获取 core 依赖
cd packages/core && flutter pub get

# 2. 获取 shared 依赖
cd ../shared && flutter pub get

# 3. 获取功能模块依赖
cd ../feature_home && flutter pub get
cd ../feature_settings && flutter pub get
cd ../feature_user && flutter pub get

# 4. 获取主应用依赖
cd ../../app && flutter pub get

# 4. 运行应用
flutter run
```

### 方式二：使用 Melos（推荐）

```bash
# 1. 安装 melos
dart pub global activate melos

# 2. 初始化项目
melos bootstrap

# 3. 运行主应用
cd app && flutter run
```

## 📦 如何新建功能模块

### 1. 创建模块

```bash
cd packages
flutter create --template=package feature_xxx
```

### 2. 配置 pubspec.yaml

```yaml
name: feature_xxx
description: xxx 功能模块
version: 1.0.0
publish_to: 'none'

environment:
  sdk: ^3.10.1
  flutter: ">=1.17.0"

dependencies:
  flutter:
    sdk: flutter

  shared:
    path: ../shared

flutter:
```

### 3. 创建模块文件结构

```bash
cd feature_xxx/lib
# 删除默认的 src 目录
rm -rf src

# 创建模块文件（直接在 lib/ 下）
# xxx_page.dart
# xxx_controller.dart
# xxx_binding.dart
# xxx_routes.dart
```

### 4. 创建统一导出文件

```dart
// lib/feature_xxx.dart
library feature_xxx;

export 'xxx_page.dart';
export 'xxx_controller.dart';
export 'xxx_binding.dart';
export 'xxx_routes.dart';
```

### 5. 在主应用中添加依赖

```yaml
# app/pubspec.yaml
dependencies:
  feature_xxx:
    path: ../packages/feature_xxx
```

### 6. 注册路由

```dart
// app/lib/main.dart
import 'package:feature_xxx/feature_xxx.dart';

getPages: [
  ...XxxRoutes.routes,
]
```

## 🛠️ Melos 常用命令

```bash
melos bootstrap     # 初始化所有模块依赖
melos run get       # 获取所有依赖
melos run clean     # 清理所有模块
melos run analyze   # 分析所有代码
melos run test      # 运行所有测试
melos run build:apk # 构建 APK
```

## 📐 模块组织方式

**本项目的模块导出方式：**
```dart
// feature_home.dart - 统一导出文件
library feature_home;

export 'home_page.dart';
export 'home_controller.dart';
export 'home_binding.dart';
export 'home_routes.dart';
```

外部使用时只需导入顶层文件：
```dart
import 'package:feature_home/feature_home.dart';
```

## ✅ 架构优势

- **官方推荐结构** - 符合 Flutter Monorepo 最佳实践
- **主应用独立** - app/ 目录包含完整的应用代码
- **模块统一管理** - packages/ 下管理所有模块
- **清晰的分层** - core (无UI) → shared (UI基础) → features (业务)
- **单向依赖** - feature → shared → core，无循环依赖
- **扁平化结构** - 小型模块无需 src/ 嵌套，简洁高效
- **易于扩展** - 可轻松添加多个应用（如管理端、用户端）
- **Melos 支持** - 统一管理多模块项目