Clean Architecture：构建更健壮、可维护的Flutter应用

引言：我们为何需要整洁架构？

在Flutter开发中，不少开发者都有过这样的体验：项目初期代码清晰、功能实现迅速，但随着业务扩张和多人协作，代码逐渐变得像“意大利面条”一样缠绕不清——UI里掺着业务逻辑，数据访问散落在各处。最终导致应用难以测试、维护成本飙升，每次改动都如履薄冰。

Clean Architecture（整洁架构）由软件工程大师Robert C. Martin提出，正是为了解决这类问题。其核心在于关注点分离，通过明确的分层来约束依赖方向，让应用的核心业务逻辑独立于框架、UI和外部数据源。对于Flutter应用来说，这套理念尤为实用，因为：

  • 跨平台特性：业务逻辑应保持平台中立，便于后续适配或迁移
  • 快速迭代需求：清晰的边界能让多个团队并行开发不同模块
  • 长期可维护性：良好的架构能显著降低技术债务
  • 测试友好性：我们可以对核心逻辑进行单元测试，而不必启动整个Flutter环境

在接下来的内容中，我们将一起探讨Clean Architecture在Flutter中的落地实践。我会通过一个完整的用户管理示例，手把手展示如何从零搭建一个结构清晰、易于测试和维护的应用，并分享一些实际开发中的优化心得。

一、Clean Architecture核心原理剖析

1.1 分层架构：同心圆与依赖规则

Clean Architecture常被描绘为一系列同心圆，从内到外依次是：领域层（Domain）、数据层（Data）和表现层（Presentation）。依赖关系有严格的指向：外层可以依赖内层，反之则绝对禁止。

// 依赖关系永远向内指
// 表现层 (Presentation)
//     ↓
// 数据层 (Data)
//     ↓
// 领域层 (Domain)

领域层（Domain Layer） —— 这是应用的“大脑”。它包含了最核心的业务实体与规则，并且完全独立，不引用任何外部框架或库。具体包括：

  • 实体（Entities）：最基本的业务对象（例如“用户”），承载核心业务规则。
  • 用例（Use Cases）：协调数据流向、实现特定业务场景的交互逻辑。
  • 仓库接口（Repository Interfaces）：定义数据操作的抽象契约，具体实现留给外层。

数据层（Data Layer） —— 充当“适配器”角色。它负责实现领域层定义的接口，与各种数据源（如网络API、本地数据库）打交道，并将外部数据格式转换为内部实体。

  • 它知晓并依赖于领域层，但对外隐藏了数据来源的复杂性。

表现层（Presentation Layer） —— 这是用户直接接触的“界面”。它包含UI组件（Widgets）和状态管理逻辑（如Bloc、Provider），其职责是向用户展示信息并接收输入。

  • 它会调用领域层的用例，或通过仓库接口获取数据。

1.2 关键：依赖注入与依赖方向

分层之所以有效，关键在于严守依赖方向规则。内层（领域层）对外层（数据层、表现层）一无所知。这种单向依赖确保了核心业务逻辑的纯粹性与可测试性。

在实践中，我们通常使用依赖注入（DI）容器来管理各层之间的依赖关系。下面是一个使用 get_it 的配置示例：

final getIt = GetIt.instance;

void setupDependencies() {
  // 数据层：配置数据源和仓库实现
  getIt.registerLazySingleton<ApiClient>(() => ApiClientImpl());
  getIt.registerLazySingleton<UserRepository>(
    () => UserRepositoryImpl(
      localDataSource: getIt(),
      remoteDataSource: getIt(),
    ),
  );
  
  // 领域层：注入用例
  getIt.registerLazySingleton<GetUsersUseCase>(
    () => GetUsersUseCase(getIt()),
  );
  
  // 表现层：工厂方式创建Bloc，使其能携带状态
  getIt.registerFactory(() => UserBloc(getIt()));
}

1.3 为何它特别适合Flutter？

  1. 真正的独立测试：你可以单独测试领域层，无需模拟或运行Flutter环境。
  2. 框架解耦：核心业务逻辑不依赖Flutter SDK，未来若有部分逻辑需要移植到其他平台（如后端），会容易得多。
  3. 提升团队效率：前后端开发可以基于领域层接口并行工作，UI与逻辑开发也可以清晰分工。
  4. 代码即文档：清晰的层级和命名让新成员能快速理解系统脉络。
  5. 拥抱变化：当业务需求变更或技术栈更新时，影响范围被控制在特定层次内，降低了重构风险。

二、实战：从零搭建Flutter整洁架构项目

2.1 项目结构规划

我们按功能特性（feature）来组织代码，而不是按技术类型（如所有页面放一起，所有模型放一起）。这样每个功能模块都是自包含的，便于独立开发和复用。

lib/
├── core/               # 跨功能共享的核心代码
│   ├── constants/      # 常量
│   ├── errors/         # 自定义异常与失败类型
│   ├── network/        # 网络连接检查等
│   └── usecases/       # 基础的用例抽象类
├── features/           # 各个功能模块
│   └── user/           # 以“用户管理”功能为例
│       ├── data/       # 数据层实现
│       ├── domain/     # 领域层（实体、接口、用例）
│       └── presentation/# 表现层（UI & 状态管理）
└── main.dart          # 应用入口与依赖注入初始化

2.2 依赖配置 (pubspec.yaml)

整洁架构不限制你使用具体的库，但以下是一些经过社区验证、能很好配合此架构的常用依赖。

dependencies:
  flutter:
    sdk: flutter

  # 状态管理与不可变数据
  flutter_bloc: ^8.1.3
  equatable: ^2.0.5

  # 网络与序列化
  dio: ^5.3.3
  retrofit: ^4.0.1
  json_annotation: ^4.8.1

  # 本地持久化
  shared_preferences: ^2.2.1
  hive: ^2.2.3

  # 依赖注入
  get_it: ^7.6.4

dev_dependencies:
  build_runner: ^2.4.7
  retrofit_generator: ^4.0.1   # 用于生成Retrofit代码
  json_serializable: ^6.7.1   # 用于生成JSON序列化代码

2.3 领域层实现：定义核心

领域层是架构的心脏，我们先从这里开始。

2.3.1 实体（Entity）

实体是纯Dart类，包含业务属性和方法。它应该独立于任何数据源的具体格式。

// lib/features/user/domain/entities/user.dart
import 'package:equatable/equatable.dart';

class User extends Equatable {
  final String id;
  final String name;
  final String email;
  final DateTime createdAt;
  final bool isActive;

  const User({
    required this.id,
    required this.name,
    required this.email,
    required this.createdAt,
    required this.isActive,
  });

  // 业务规则示例：判断是否为30天内创建的新用户
  bool get isRecentUser => DateTime.now().difference(createdAt).inDays < 30;

  // 提供复制方法，方便创建不可变对象的修改版本
  User copyWith({
    String? id,
    String? name,
    String? email,
    DateTime? createdAt,
    bool? isActive,
  }) {
    return User(
      id: id ?? this.id,
      name: name ?? this.name,
      email: email ?? this.email,
      createdAt: createdAt ?? this.createdAt,
      isActive: isActive ?? this.isActive,
    );
  }

  @override
  List<Object> get props => [id, name, email, createdAt, isActive];
}
2.3.2 仓库接口（Repository Contract）

仓库接口定义了数据操作的“约定”，但不说具体怎么做。这让领域层不关心数据是来自网络还是内存。

// lib/features/user/domain/repositories/user_repository.dart
import 'package:dartz/dartz.dart';
import '../entities/user.dart';
import '../../../../core/errors/failures.dart';

abstract class UserRepository {
  Future<Either<Failure, List<User>>> getUsers();
  Future<Either<Failure, User>> getUserById(String id);
  Future<Either<Failure, User>> createUser(User user);
  // ... 其他更新、删除、搜索方法
}
2.3.3 用例（Use Case）

用例代表一个具体的业务交互（如“获取用户列表”）。它协调数据流，并可封装额外的业务规则（如过滤、排序）。

// lib/features/user/domain/usecases/get_users_usecase.dart
class GetUsersUseCase {
  final UserRepository repository;
  GetUsersUseCase(this.repository);

  Future<Either<Failure, List<User>>> execute(bool onlyActive) async {
    final result = await repository.getUsers();
    return result.fold(
      (failure) => Left(failure),
      (users) {
        // 在此注入业务逻辑：例如，按条件过滤
        if (onlyActive) {
          return Right(users.where((user) => user.isActive).toList());
        }
        return Right(users);
      },
    );
  }
}

2.4 数据层实现：适配外部世界

数据层负责“履约”，即实现领域层定义的接口。

2.4.1 数据模型（Data Model）

数据模型对应API或数据库的返回格式。它需要具备与实体互相转换的能力。

// lib/features/user/data/models/user_model.dart
@JsonSerializable()
class UserModel {
  @JsonKey(name: 'id')
  final String id;
  // ... 其他字段

  // 关键：转换为领域层实体
  User toEntity() => User(
        id: id,
        name: name,
        // ... 转换其他字段，如将字符串日期转为DateTime
        createdAt: DateTime.parse(createdAt),
        isActive: isActive,
      );

  // 关键：从实体创建数据模型
  factory UserModel.fromEntity(User user) => UserModel(
        id: user.id,
        name: user.name,
        createdAt: user.createdAt.toIso8601String(),
        // ...
      );

  // 标准的JSON序列化
  factory UserModel.fromJson(Map<String, dynamic> json) =>
      _$UserModelFromJson(json);
  Map<String, dynamic> toJson() => _$UserModelToJson(this);
}
2.4.2 仓库实现（Repository Implementation）

仓库实现是数据层的协调者。它决定数据从哪来（网络优先？缓存优先？），并处理所有异常，将其转换为领域层能理解的 Failure 类型。

// lib/features/user/data/repositories/user_repository_impl.dart
class UserRepositoryImpl implements UserRepository {
  final UserRemoteDataSource remoteDataSource;
  final UserLocalDataSource localDataSource;
  final NetworkInfo networkInfo;

  @override
  Future<Either<Failure, List<User>>> getUsers() async {
    try {
      if (await networkInfo.isConnected) {
        // 有网：从API获取并缓存
        final remoteUsers = await remoteDataSource.getUsers();
        await localDataSource.cacheUsers(remoteUsers);
        return Right(remoteUsers.map((model) => model.toEntity()).toList());
      } else {
        // 无网：从缓存获取
        final localUsers = await localDataSource.getCachedUsers();
        return Right(localUsers.map((model) => model.toEntity()).toList());
      }
    } on ServerException catch (e) {
      return Left(ServerFailure(message: e.message));
    } on CacheException catch (e) {
      return Left(CacheFailure(message: e.message));
    }
  }
  // ... 实现其他接口方法
}

2.5 表现层实现：与用户交互

表现层使用状态管理库（这里以BLoC为例）来管理UI状态，并通过用例与领域层交互。

2.5.1 BLoC状态管理

BLoC将UI事件转换为状态变化。

// lib/features/user/presentation/blocs/user_bloc/user_bloc.dart
class UserBloc extends Bloc<UserEvent, UserState> {
  final GetUsersUseCase getUsersUseCase;
  UserBloc({required this.getUsersUseCase}) : super(UserInitial()) {
    on<FetchUsersEvent>(_onFetchUsers);
  }

  Future<void> _onFetchUsers(event, emit) async {
    emit(UserLoading());
    final result = await getUsersUseCase.execute(event.onlyActive);
    result.fold(
      (failure) => emit(UserError(_mapFailureToMessage(failure))),
      (users) => emit(UserLoaded(users: users)),
    );
  }

  String _mapFailureToMessage(Failure failure) {
    // 将不同类型的Failure转换为对用户友好的提示信息
    if (failure is ServerFailure) return '服务器开小差了，请稍后重试';
    if (failure is NetworkFailure) return '网络连接似乎有点问题';
    return '操作失败，请重试';
  }
}
2.5.2 UI界面

UI组件监听BLoC的状态并做出响应。

// lib/features/user/presentation/pages/user_list_page.dart
class UserListPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('用户列表')),
      body: BlocBuilder<UserBloc, UserState>(
        builder: (context, state) {
          if (state is UserLoading) return const CircularProgressIndicator();
          if (state is UserLoaded) {
            return ListView.builder(
              itemCount: state.users.length,
              itemBuilder: (ctx, index) => UserListItem(user: state.users[index]),
            );
          }
          if (state is UserError) {
            return Center(child: Text(state.message));
          }
          return const Center(child: Text('点击加载数据'));
        },
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: () => context.read<UserBloc>().add(FetchUsersEvent()),
        child: const Icon(Icons.refresh),
      ),
    );
  }
}

结语

采用Clean Architecture构建Flutter应用，初期的确需要更多思考和设计。但从长远来看，这种投资是值得的——它为你的应用带来了清晰的结构、可独立测试的核心逻辑，以及应对未来变化的强大韧性。

本文展示的只是一个起点。在实际项目中，你可能会遇到更复杂的场景，比如身份验证流、实时数据同步、复杂的领域事件等。但万变不离其宗，只要坚守“依赖向内、关注点分离”的原则，你就能在整洁架构的基础上，构建出稳定、可扩展的Flutter应用。

希望这篇指南能为你铺平道路。如果你在实践过程中有任何心得或疑问，也欢迎随时交流讨论。

# 移动开发
Logo
开源鸿蒙跨平台开发者社区

开源鸿蒙跨平台开发社区汇聚开发者与厂商，共建“一次开发，多端部署”的开源生态，致力于降低跨端开发门槛，推动万物智联创新。

更多推荐

cover

响应速度拉满！手把手教你自制 FPS 级虚拟键盘 (Flutter + Python + UDP 深度实战)，深夜算竞助手

avatar 开源鸿蒙跨平台开发者社区
cover

基于 Flutter × OpenHarmony 的卡片网格布局实战

avatar 开源鸿蒙跨平台开发者社区
cover

Flutter × OpenHarmony：探索不同宽高比网格布局实现与解析

avatar 开源鸿蒙跨平台开发者社区