YagniLauncher 架构深度解析:Clean Architecture五层设计与模块依赖规则完整指南
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消费的.protoschema 定义(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 为例,看这个经典三步走:
- 定接口:
domain:framework声明 LauncherAppsWrapper(纯 Kotlin 接口,只涉及 Domain 模型类型); - 做实现:
framework:launcher-apps编写 DefaultLauncherAppsWrapper.kt,内部才真正调用android.content.pm.LauncherApps; - 用 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 系统直接对话的两个模块,也是唯一被允许同时依赖整个模块图的地方:
app— Hilt 装配、EblanApplication.kt、根 Activity 与导航图。app/build.gradle.kts 中implementation(projects.xxx)清单几乎覆盖了所有 feature、framework 与 data 模块,正是"最外层负责接线"的角色。service— 后台服务:EblanAccessibilityService.kt(无障碍)、EblanNotificationListenerService.kt(通知监听)、IconPackService.kt(图标包更新)。
🔍 新手快速阅读路线:从依赖图到源码
给想进入这个代码库的你一份实操路线:
- 先读官方文档:docs/ARCHITECTURE.md 是架构的"宪法",20 分钟可通读;
- 再读模块清单:settings.gradle.kts 中
include(":xxx")一行就是一个模块,配合前文表格快速建立全景; - 跟踪一条业务链路(推荐"移动网格项"):
feature:home的 HomeViewModel.kt →domain:use-case的 MoveGridItemUseCase.kt →domain:grid的 MoveGridItem.kt →data:repository落库。你会发现整条链上没有任何一层"越级"引用; - 看构建规范:build-logic/convention/ 中的
AndroidFeatureConventionPlugin、AndroidHiltConventionPlugin等约定插件统一了各模块的构建配置,feature 模块对ui/design-system的自动依赖就来自这里; - 跑测试验证:
domain:grid自带 test/ 单元测试,data:room配有完整迁移测试,纯 Domain 层的可测试性一目了然。
✅ 总结:这套架构给普通开发者的启示
- 依赖只向内——外层可随技术栈更替(换 UI 框架、换持久化方案),内层业务毫发无损;
- 接口在 Domain,实现在外层——Domain 依赖抽象,Hilt 在运行时注入实现;
- 模块即边界——一个系统 API 一个 framework 模块、一个功能一个 feature 模块,边界清晰到写进了 build-logic/ 的约定插件里;
- 测试分层落地——纯 Kotlin 的 Domain 直接 JVM 单测,Room 迁移用 androidTest 守护。
理解并实践这套五层设计与依赖规则,你不仅能读懂 YagniLauncher 的每一行代码,更能把它迁移到自己从零搭建的 Android 项目中。🚀