# Flutter_mvvm_clean_demo

**Repository Path**: vper/flutter_mvvm_clean_demo

## Basic Information

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

## Statistics

- **Stars**: 4
- **Forks**: 3
- **Created**: 2025-12-05
- **Last Updated**: 2025-12-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Flutter MVVM Clean Architecture Demo

这是一个展示如何在Flutter中实现MVVM(Model-View-ViewModel)架构结合Clean Architecture原则的演示项目。

## 📋 目录

- [架构概述](#架构概述)
- [项目结构](#项目结构)
- [核心概念](#核心概念)
- [技术栈](#技术栈)
- [开始使用](#开始使用)
- [功能特性](#功能特性)

## 🏗️ 架构概述

本项目采用Clean Architecture和MVVM模式的结合，实现了清晰的分层架构和关注点分离。

### Clean Architecture原则

Clean Architecture是一种软件设计哲学，通过将软件组织成层次结构来实现关注点分离：

1. **独立性** - 各层相互独立，可以独立开发和测试
2. **依赖反转** - 内层不依赖外层，外层依赖内层
3. **可测试性** - 业务逻辑与UI框架分离，便于单元测试
4. **可维护性** - 修改一层不会影响其他层

### MVVM模式

MVVM(Model-View-ViewModel)是一种UI架构模式：

- **Model** - 数据和业务逻辑
- **View** - UI界面，负责展示数据
- **ViewModel** - 连接Model和View的桥梁，处理UI逻辑

## 📁 项目结构

```
lib/
├── app/                    # 应用程序配置和路由
│   ├── config/            # API配置
│   └── router/            # 路由配置
├── core/                  # 核心功能
│   ├── di/               # 依赖注入
│   ├── error/            # 错误处理
│   └── network/          # 网络配置
├── data/                  # 数据层
│   ├── datasources/      # 数据源
│   ├── models/           # 数据模型
│   └── repositories/     # 仓库实现
├── domain/                # 领域层
│   ├── entities/         # 实体
│   ├── repositories/     # 仓库接口
│   └── usecases/         # 用例
└── presentation/          # 表现层
    ├── pages/            # 页面
    ├── viewmodels/       # 视图模型
    └── widgets/          # 公共UI组件
```

## 🧩 核心概念

### 1. 领域层 (Domain Layer)

领域层是架构的核心，包含业务规则和实体：

- **实体(Entities)**: 代表业务对象，如User
- **仓库接口(Repository Interfaces)**: 定义数据访问契约
- **用例(Use Cases)**: 封装特定业务规则

```dart
// 实体示例
class User {
  final int id;
  final String name;
  final String email;
  // ...
}

// 仓库接口示例
abstract class UserRepository {
  Future<List<User>> getUserInfo();
}

// 用例示例
class GetUserInfo {
  final UserRepository userRepository;
  
  GetUserInfo(this.userRepository);
  
  Future<List<User>> call() async {
    return userRepository.getUserInfo();
  }
}
```

### 2. 数据层 (Data Layer)

数据层负责从各种数据源获取数据：

- **数据源(Data Sources)**: 实现具体的数据获取逻辑
- **数据模型(Data Models)**: 用于数据传输和序列化
- **仓库实现(Repository Implementations)**: 实现领域层定义的接口

```dart
// 数据源示例
class UserRemoteDataSource {
  final DioClient dioClient;
  
  UserRemoteDataSource(this.dioClient);
  
  Future<List<UserModel>> getUsers() async {
    final response = await dioClient.get(Api.user);
    return (response.data as List).map((e) => UserModel.fromJson(e)).toList();
  }
}

// 仓库实现示例
class UserRepositoryImpl implements UserRepository {
  final UserRemoteDataSource remoteDataSource;
  final UserLocalDataSource localDataSource;
  
  UserRepositoryImpl({
    required this.remoteDataSource,
    required this.localDataSource,
  });
  
  @override
  Future<List<User>> getUserInfo() async {
    try {
      return await remoteDataSource.getUsers();
    } catch (e) {
      return localDataSource.getUsers();
    }
  }
}
```

### 3. 表现层 (Presentation Layer)

表现层负责UI展示和用户交互：

- **页面(Pages)**: UI界面
- **视图模型(ViewModels)**: 处理UI状态和用户交互
- **公共UI组件(Common Widgets)**: 可复用的UI组件，确保整个应用的UI一致性

```dart
// 视图模型示例
class UserViewModel extends StateNotifier<UserState> {
  final GetUserInfo getUserInfo;
  
  UserViewModel(this.getUserInfo) : super(UserState.initial());
  
  Future<void> loadUsers() async {
    state = state.copyWith(isLoading: true, error: null);
    try {
      final users = await getUserInfo();
      state = state.copyWith(users: users, isLoading: false);
    } catch (e) {
      state = state.copyWith(isLoading: false, error: e.toString());
    }
  }
}
```

### 4. 公共UI组件 (Common UI Components)

为了保持整个应用的UI风格一致性，我们抽取了以下公共组件：

- **AppPageScaffold**: 统一的页面框架，包含AppBar和下拉刷新功能
- **PageStateWidget**: 处理加载、错误和空数据状态的统一显示
- **ListItemCard**: 统一的列表项卡片样式
- **AvatarWidget**: 统一的头像显示组件
- **InfoItemWidget**: 带图标的信息项显示组件
- **StatItemWidget**: 统计数据项显示组件
- **ActionItemWidget**: 可点击操作项组件

这些组件确保了整个应用程序的UI风格一致性，提高了代码的可维护性和复用性。

## 🛠 技术栈

- **Flutter** - 跨平台UI框架
- **Riverpod** - 状态管理和依赖注入
- **Dio** - HTTP客户端
- **JSON Serialization** - 数据序列化/反序列化

## 🚀 开始使用

### 前置要求

- Flutter SDK (>=3.10.1)
- Dart SDK (>=3.0.0)

### 安装步骤

1. 克隆仓库
```bash
git clone https://github.com/yourusername/flutter_mvvm_clean_demo.git
cd flutter_mvvm_clean_demo
```

2. 安装依赖
```bash
flutter pub get
```

3. 运行应用
```bash
flutter run
```

## ✨ 功能特性

- [x] 清晰的分层架构
- [x] MVVM模式实现
- [x] 依赖注入
- [x] 错误处理
- [x] 状态管理
- [x] 网络请求
- [x] 数据回退机制
- [x] 统一的UI组件库
- [x] 响应式UI设计

## 📸 应用截图

### 应用预览
应用程序已在模拟器上成功运行，您可以通过以下链接查看应用运行状态：

- **Dart VM Service**: http://127.0.0.1:3131/mmEXCuLPVVc=/
- **Flutter DevTools**: http://127.0.0.1:3131/mmEXCuLPVVc=/devtools/?uri=ws://127.0.0.1:3131/mmEXCuLPVVc=/ws

### 页面展示
应用包含三个主要页面，均使用统一的UI组件库：

1. **用户页面** - 展示用户信息列表，包含头像、姓名、邮箱、电话和网站信息
2. **文章页面** - 展示文章列表，包含标题、内容预览和作者信息
3. **任务页面** - 展示任务列表，包含任务标题、状态和完成情况

所有页面都使用以下公共组件：
- AppPageScaffold - 统一的页面框架
- PageStateWidget - 统一的状态处理
- ListItemCard - 统一的列表项样式
- AvatarWidget - 统一的头像显示
- InfoItemWidget - 统一的信息项展示

## 🧪 测试

运行测试:
```bash
flutter test
```

## 🤝 贡献

欢迎提交问题和拉取请求！

## 📄 许可证

本项目采用MIT许可证 - 查看[LICENSE](LICENSE)文件了解详情。