YagniLauncher 架构深度解析:Clean Architecture五层设计与模块依赖规则完整指南

原创2026-11-03 20:49:081,863 阅读

YagniLauncher 架构深度解析:Clean Architecture五层设计与模块依赖规则完整指南

YagniLauncher 是一款从零实现的 Stock Android 启动器,完整采用 Clean Architecture(整洁架构)五层设计与严格的模块依赖规则,将 Domain、Data、Framework、Presentation、Entry Points 彻底解耦。本文带你快速看懂这套架构的分工、依赖方向,以及新手如何高效阅读这个 40 模块的 Gradle 工程。

📐 一图看懂:洋葱模型与"依赖只向内"规则

YagniLauncher 的模块结构遵循 Clean Architecture 的"洋葱"思想,官方文档在 docs/ARCHITECTURE.md 中给出了分层定义与依赖规则(第 27~39 行):

依赖只能指向内侧:Entry Points 依赖 Presentation、Framework、Data、Domain;Presentation 依赖 Framework 与 Domain;Data 依赖 Domain;Framework 依赖 Domain。Domain 不依赖项目中任何其他模块,任何内层都绝不引用外层。

用一张文字版"洋葱图"感受一下(由外向内):

┌─────────────────────────────────────────────────────┐
│  Android Entry Points:app、service(最外层装配层)   │
│  ┌───────────────────────────────────────────────┐  │
│  │  Presentation:feature:*、ui、design-system   │  │
│  │  ┌─────────────────────────────────────────┐  │  │
│  │  │  Framework:framework:* 系统 API 薄封装   │  │  │
│  │  │  ┌───────────────────────────────────┐  │  │  │
│  │  │  │  Domain:纯 Kotlin,核心业务模型    │  │  │  │
│  │  │  │  (model / repository / use-case /  │  │  │  │
│  │  │  │   grid / framework / common)       │  │  │  │
│  │  │  └───────────────────────────────────┘  │  │  │
│  │  └─────────────────────────────────────────┘  │  │
│  │  Data:room、datastore、repository(持久化)   │  │
│  └───────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────┘

🧩 五层速览:每层有哪些模块?

在 settings.gradle.kts 中,项目一次性声明了约 40 个 Gradle 模块。按 Clean Architecture 五层归类如下:

层次 模块 核心职责 是否依赖 Android SDK
① Domain domain:model、domain:repository、domain:framework、domain:use-case、domain:grid、domain:common 实体/值对象、仓库接口、系统服务抽象接口、业务用例、网格布局算法 ❌ 纯 Kotlin
② Data data:room、data:datastore、data:datastore-proto、data:repository Room 数据库、Proto DataStore 设置持久化、仓库实现 ✅
③ Framework framework:launcher-apps、framework:package-manager、framework:wallpaper-manager、framework:widget-manager 等 13 个 一对一封装 Android 系统 API ✅
④ Presentation feature:home、feature:action、feature:pin、feature:settings:* 等、ui、design-system Compose 界面、ViewModel、UI 状态 ✅
⑤ Entry Points app、service Application/Activity 图、后台 Service,全局装配 ✅

另有共享基础设施:common(应用级 Hilt 绑定,见 CommonModule.kt)与 build-logic/ 中的 Gradle Convention Plugin。

🔵 Domain 层:纯 Kotlin 内核,零 Android 依赖

Domain 是整个架构最核心、最稳定的一层,没有任何 Android SDK import,因此所有逻辑都可以脱离设备、在 JVM 上独立单元测试。

模块 职责 代表文件
domain:model 所有层共享的实体与值对象(74 个文件) domain/model/
domain:repository 仓库接口,描述领域需要的数据操作 GridRepository.kt
domain:framework Android 系统服务的抽象接口(9 个) LauncherAppsWrapper.kt
domain:use-case 应用业务逻辑,由仓库与框架接口组合而成(47 个文件) MoveGridItemUseCase.kt
domain:grid 网格布局与碰撞解决算法(拖拽/缩放时) MoveGridItem.kt
domain:common 横切抽象,如协程 Dispatcher 限定符 domain/common/

domain:use-case 的构建脚本 domain/use-case/build.gradle.kts 应用的是 jvmLibrary 约定插件(而非 Android 插件),只依赖 domain:* 兄弟模块与协程库——这就是"纯 Kotlin"承诺的落地证据。

🗄️ Data 层:Room + Proto DataStore 双持久化

Data 层为 domain:repository 中的每个接口提供具体持久化实现:

  • data:room — 本地 SQLite 数据库,存储网格项、已安装应用、Widget、快捷方式、图标包。数据库 schema 已演进到第 21 版(data/room/schemas/),并配有 Migration20To21Test.kt 等迁移测试,保证升级不丢数据。
  • data:datastore — 用户设置持久化(UserDataStore.kt),基于 Proto DataStore。
  • data:datastore-proto — 供 data:datastore 消费的 .proto schema 定义(18 个文件)。
  • data:repository — 组合 Room 与 DataStore 的 16 个仓库实现 + 8 个 Mapper,如 DefaultGridRepository.kt。

依赖关系非常克制:data/room/build.gradle.kts 只 implementation 了 domain:model 与 domain:repository;data/repository/build.gradle.kts 只依赖 data:datastore、data:room 和 domain:repository——没有任何一条指向 Presentation 或 Framework。

📲 Framework 层:给系统 API 套上"薄壳"

Framework 层是理解本项目架构思想的最佳切入点,其核心规则只有一条:每个 framework:* 模块封装一个 Android 系统 API,其余代码永远不直接 import 它。

以 framework:launcher-apps 为例,看这个经典三步走:

  1. 定接口:domain:framework 声明 LauncherAppsWrapper(纯 Kotlin 接口,只涉及 Domain 模型类型);
  2. 做实现:framework:launcher-apps 编写 DefaultLauncherAppsWrapper.kt,内部才真正调用 android.content.pm.LauncherApps;
  3. 用 Hilt 绑定:LauncherAppsModule.kt 把实现绑定到接口上。

其构建脚本 framework/wallpaper-manager/build.gradle.kts 同样印证了这一点:依赖只有 domain:common 和 domain:framework 两个 Domain 模块,方向始终向内。

💡 少数模块(如 framework:user-manager、framework:settings)直接封装系统 API 而不经过 domain:framework 接口,因为目前 Domain 层无需通过抽象消费它们——架构文档对此有明确说明(docs/ARCHITECTURE.md)。

🎨 Presentation 层:feature、ui、design-system 的边界

三个模块组同属 Presentation 层,但职责泾渭分明(见 docs/ARCHITECTURE.md):

模块组 定位 依赖特征
design-system 通用视觉原语:主题、图标、动画、对话框,model-free 零 Domain 依赖,不含任何业务模型
ui 应用感知的共享 UI,如 SelectApplicationDialog.kt 依赖 design-system + domain:model,向 feature 暴露 framework:* 实现
feature:* 单一功能的屏幕、ViewModel 与 UI 状态 自动依赖 design-system 与 ui(由 Convention Plugin 注入)

以 feature/home/build.gradle.kts 为例,它应用 feature 约定插件,声明依赖 domain:use-case、domain:grid 等——正是"功能模块只声明自己需要的用例"这一原则的体现。

🚪 Entry Points:唯一允许"横跨全局"的装配层

app 与 service 是 Android 系统直接对话的两个模块,也是唯一被允许同时依赖整个模块图的地方:

🔍 新手快速阅读路线:从依赖图到源码

给想进入这个代码库的你一份实操路线:

  1. 先读官方文档:docs/ARCHITECTURE.md 是架构的"宪法",20 分钟可通读;
  2. 再读模块清单:settings.gradle.kts 中 include(":xxx") 一行就是一个模块,配合前文表格快速建立全景;
  3. 跟踪一条业务链路(推荐"移动网格项"):feature:home 的 HomeViewModel.kt → domain:use-case 的 MoveGridItemUseCase.kt → domain:grid 的 MoveGridItem.kt → data:repository 落库。你会发现整条链上没有任何一层"越级"引用;
  4. 看构建规范:build-logic/convention/ 中的 AndroidFeatureConventionPlugin、AndroidHiltConventionPlugin 等约定插件统一了各模块的构建配置,feature 模块对 ui/design-system 的自动依赖就来自这里;
  5. 跑测试验证:domain:grid 自带 test/ 单元测试,data:room 配有完整迁移测试,纯 Domain 层的可测试性一目了然。

✅ 总结:这套架构给普通开发者的启示

  • 依赖只向内——外层可随技术栈更替(换 UI 框架、换持久化方案),内层业务毫发无损;
  • 接口在 Domain,实现在外层——Domain 依赖抽象,Hilt 在运行时注入实现;
  • 模块即边界——一个系统 API 一个 framework 模块、一个功能一个 feature 模块,边界清晰到写进了 build-logic/ 的约定插件里;
  • 测试分层落地——纯 Kotlin 的 Domain 直接 JVM 单测,Room 迁移用 androidTest 守护。

理解并实践这套五层设计与依赖规则,你不仅能读懂 YagniLauncher 的每一行代码,更能把它迁移到自己从零搭建的 Android 项目中。🚀

登录后查看全文
YagniLauncher