1. 模块化拆分原则：单一职责与分层依赖

Gradle 模块拆分是大型 Android 工程治理的第一道防线。合理的模块划分能让构建加速、团队解耦、复用提升；反之则会出现循环依赖、构建缓慢、改一处坏全局的问题。本章从三个核心维度出发：划分原则、单一职责、分层依赖，并给出完整的实现流程与避坑指南。

1.1 模块划分三大原则

• 高内聚低耦合 — 模块内的类、资源、功能紧密关联，对外暴露最小接口。
• 业务与基础设施分离 — 业务模块只依赖抽象接口，基础设施模块提供实现（网络、数据库、DI等）。
• 复用粒度适中 — 太细导致模块爆炸，太粗失去拆分意义；以“业务域”为粒度（如登录、订单、支付）。

1.2 单一职责：每个模块只做一件事

“单一职责”在 Gradle 模块化中意味着：一个模块不应同时承担业务逻辑、数据缓存和 UI 渲染。典型的职责边界如下：

1.3 分层依赖：自上而下，不跨层

依赖方向必须保持单向：

1. 顶层 — 应用壳依赖所有 :feature:* 模块。
2. 中间层 — 业务模块依赖 :core:data、:core:ui，不能反向依赖。
3. 底层 — 核心模块依赖 :libraries:* 或纯 Kotlin/Java 库。

跨层依赖（如业务模块直接依赖库模块中的 AppCompat）是允许的，但业务模块绝不能依赖另一个业务模块的 internal 包。消除循环依赖的唯一手段是引入接口模块或依赖倒置。

1.4 分层依赖结构图

1.5 实现流程：从单模块到多模块

1. 识别模块边界 — 在当前的 app/src/main/java 下通过 package 组织，判断哪些功能可被独立复用或独立部署。
2. 创建 Gradle 子项目 — 在 settings.gradle.kts 中声明：

   include(":feature:login")
   include(":core:data")
   include(":libraries:utils")

3. 移动代码 — 将业务逻辑、资源文件按包迁移至对应模块，调整 import 语句。
4. 配置依赖 — 在 :feature:login 的 build.gradle.kts 中添加 implementation(project(":core:data"))，并确保无循环引用。
5. 验证构建 — 运行 ./gradlew :app:assembleDebug 并检查依赖图中是否有 cycle 警告。

./gradlew :app:dependencies --configuration debugRuntimeClasspath

1.6 常见错误与性能优化

1.7 部署与调试要点

模块拆分后，CI/CD 流水线应增加模块级并行编译。同时借助 gradle-module-plugins 统一版本号，确保每个模块 publish 时无遗漏。调试时可通过 --stacktrace 定位模块间配置冲突。