[鸿蒙2025领航者闯关] Flutter + OpenHarmony 模块化架构设计：大型应用的可维护性与协作之道

[鸿蒙2025领航者闯关]📦 Flutter + OpenHarmony 模块化架构设计：大型应用的可维护性与协作之道

作者 ：晚霞的不甘
日期 ：2025年12月5日
标签：Flutter · OpenHarmony · 模块化 · Clean Architecture · 依赖注入 · 多团队协作 · 鸿蒙生态

---

引言：当项目从"能跑"走向"可持续"

初期，一个 Flutter + OpenHarmony 应用可能只有：

• 一个 main.dart
• 几个页面
• 简单的网络请求

但随着业务扩张，代码迅速膨胀：

• 50+ 页面
• 10+ 分布式能力调用
• 多语言、多主题、多设备适配
• 跨团队并行开发

若缺乏清晰架构，项目将陷入：

• 修改一处，崩坏十处
• 新人上手需两周
• 测试覆盖率不足 20%
• 发布周期长达月余

模块化，不是可选项，而是大型项目的生存必需品。

本文基于 Clean Architecture + Feature-Sliced Design ，结合 OpenHarmony 特性，提供一套高内聚、低耦合、易测试、可并行的模块化架构方案。

---

一、架构全景：三层六模块

┌──────────────────────────────────────┐
│           Presentation Layer          │ ← UI & 用户交互
│  ┌───────────┐  ┌─────────────────┐  │
│  │  Features │  │   Shared UI     │  │
│  │ (独立业务)│  │ (通用组件/主题) │  │
└──┴───────────┴──┴─────────────────┴──┘
┌──────────────────────────────────────┐
│           Domain Layer               │ ← 业务规则 & 实体
│  ┌───────────────────────────────┐  │
│  │        Use Cases / Entities    │  │
└──┴───────────────────────────────┴──┘
┌──────────────────────────────────────┐
│           Data Layer                 │ ← 数据源实现
│  ┌───────────┐  ┌─────────────────┐  │
│  │  Features │  │   Shared Data   │  │
│  │ (数据适配)│  │ (网络/DB/缓存)  │  │
└──┴───────────┴──┴─────────────────┴──┘

✅ 核心原则：

• Feature 模块自治：每个业务功能（如"健康监测"）自包含 UI + 逻辑 + 数据
• Shared 模块稳定：通用能力集中管理，版本严格控制
• 依赖方向向下：Presentation → Domain → Data，禁止反向依赖

---

二、模块划分策略

2.1 按业务功能划分（Feature Modules）

模块名	职责	示例
feature_health	健康数据展示与分析	心率图表、睡眠报告
feature_navigation	车机导航核心流程	路线规划、语音播报
feature_settings	设置中心	账号、隐私、通知

每个 Feature 模块结构：

feature_health/
├── lib/
│   ├── presentation/    # 页面、Widget、ViewModel
│   ├── domain/         # UseCase、Entity
│   └── data/           # Repository 实现、DataSource
└── pubspec.yaml        # 仅依赖 shared 模块和基础库

2.2 共享模块（Shared Modules）

模块	内容
shared_ui	按钮、卡片、主题、响应式布局工具
shared_data	网络客户端、数据库封装、缓存策略
shared_domain	通用实体（User、Device）、全局 UseCase（Auth）
shared_utils	日期格式化、加密、日志

🔒 约束 ：Shared 模块必须 无业务逻辑 ，且 API 稳定。

---

三、依赖管理：Pub + 工作区（Workspace）

3.1 使用本地路径依赖（开发阶段）

# feature_health/pubspec.yaml
dependencies:
  flutter:
    sdk: flutter
  shared_ui:
    path: ../shared_ui
  shared_data:
    path: ../shared_data

3.2 发布为私有包（生产阶段）

# 使用语义化版本
shared_ui: ^2.1.0

3.3 根项目聚合

# app/pubspec.yaml
dependencies:
  feature_health: ^1.0.0
  feature_navigation: ^1.0.0
  shared_ui: ^2.1.0

🛠️ 工具推荐 ：使用 melos 管理多模块工作区，支持一键版本同步、发布。

---

四、依赖注入（DI）：解耦的关键

4.1 使用 Riverpod 实现模块化 DI

// feature_health/lib/data/di.dart
final healthRepositoryProvider = Provider<HealthRepository>((ref) {
  final remoteDataSource = ref.read(healthRemoteDataSourceProvider);
  final localDataSource = ref.read(healthLocalDataSourceProvider);
  return HealthRepositoryImpl(remoteDataSource, localDataSource);
});

final fetchHealthDataUseCaseProvider = Provider<FetchHealthDataUseCase>((ref) {
  return FetchHealthDataUseCase(ref.read(healthRepositoryProvider));
});

4.2 根容器注册

// app/lib/main.dart
void main() {
  runApp(
    ProviderScope(
      overrides: [
        // 注册所有 Feature 的 Provider
        ...healthDiOverrides,
        ...navigationDiOverrides,
      ],
      child: MyApp(),
    ),
  );
}

✅ 优势：

• 测试时可轻松 mock 依赖
• 模块间无硬编码引用
• 编译期依赖检查

---

五、OpenHarmony 特性集成

5.1 分布式能力按模块封装

• feature_health 仅调用 ohos.health 相关 API
• feature_navigation 封装 ohos.car.navigation 能力
• 各模块通过 插件接口 访问原生能力（见上一篇插件指南）

5.2 多 HAP 支持

OpenHarmony 允许一个应用包含多个 HAP（Harmony Ability Package）：

• Entry HAP：主应用，聚合所有 Feature
• Feature HAP：按需下载（如车机专属模块）

模块化架构天然支持此模型：

• 每个 Feature 可独立编译为 HAP
• Shared 模块作为公共依赖

---

六、团队协作与 CI/CD

6.1 Git 分支策略

• main：稳定发布分支
• develop：集成分支
• feature/xxx：各模块独立开发分支

6.2 自动化质量门禁

CI 流程包含：

1. 模块独立测试：每个 Feature 运行单元测试 + Widget 测试
2. 依赖合规检查：禁止 Feature 间直接依赖
3. 代码规范扫描 ：使用 very_good_analysis
4. 集成构建：验证根项目能否正常编译

6.3 发布流程

Feature 开发 → 单元测试 → MR 合并 → 集成测试 → 发布 Shared/Feature 包 → 主应用升级

---

七、性能与包体积优化

7.1 按需加载（Lazy Loading）

// 使用 deferred import
import 'package:feature_health/health_page.dart' deferred as health;

ElevatedButton(
  onPressed: () async {
    await health.loadLibrary(); // 运行时加载
    Navigator.push(context, MaterialPageRoute(builder: (_) => health.HealthPage()));
  },
)

💡 效果：首包体积减少 30%，启动速度提升

7.2 Tree Shaking 保障

• 所有模块使用 纯 Dart 实现（避免平台特定代码污染）
• 未使用的 Feature 不会被打包进最终 HAP

---

八、演进路线图

阶段	架构状态	行动
初创期	单体应用	抽离 shared_ui 和 shared_data
成长期	3--5 个 Feature	引入 DI，建立模块边界
成熟期	10+ Feature，多团队	拆分为独立 HAP，启用按需加载
生态期	开源部分模块	发布到私有 Pub 仓库

---

结语：架构，是写给未来的自己和团队的情书

好的模块化架构，让：

• 新人第一天就能贡献代码
• 修复 Bug 不再提心吊胆
• 新功能上线只需"拼积木"

🧱 行动建议：

1. 今天就创建 shared_ui 模块
2. 明天将首页抽离为 feature_home
3. 下周制定团队模块边界规范

因为可维护的代码，才是最有价值的资产。

---

附录：推荐目录结构

my_oh_app/
├── app/                # 根应用（聚合入口）
├── features/
│   ├── feature_health/
│   ├── feature_navigation/
│   └── feature_settings/
├── shared/
│   ├── shared_ui/
│   ├── shared_data/
│   ├── shared_domain/
│   └── shared_utils/
└── melos.yaml          # 多模块管理配置

---

复杂系统的优雅，在于模块间的默契，而非代码的堆砌。