1. 多模块项目结构：settings.gradle 配置、根项目与子项目、include 与项目路径

1.1 为什么需要多模块结构

单体项目随着业务增长会逐渐膨胀，编译时间、代码耦合度、团队协作效率都会急剧下降。多模块结构将工程按业务边界或技术层拆分为独立子项目，每个子项目拥有独立构建脚本，根项目只负责编排和聚合。Gradle 通过 settings.gradle 文件定义模块拓扑，这是多模块构建的唯一入口。

1.2 根项目与子项目：两种角色

根项目本身也可以包含源代码（不推荐），多数场景只作为聚合容器。子项目在 settings.gradle 中通过 include 声明后被自动识别，并继承根项目的 allprojects 或 subprojects 配置块。

1.3 settings.gradle 的核心作用

settings.gradle 位于项目根目录，Gradle 启动时第一个读取的就是它。其核心职责包括：

• 声明项目名称（rootProject.name）
• 注册子模块（include 语句）
• 定义项目路径与物理目录的映射
• 配置模块间的依赖查找策略
• 引入复合构建或插件管理

// settings.gradle — 最小化多模块配置示例
rootProject.name = "my-platform"

include "core"
include "service:user-service"
include "service:order-service"
include "web:admin-console"

1.4 include 与项目路径语法

include 接受一个或多个字符串参数，每个字符串代表一个逻辑项目路径。路径中的冒号 : 是 Gradle 的路径分隔符，对应文件系统的子目录层级。下表列出常见模式：

项目引用名（:core、:service:user-service）在跨模块依赖声明、任务名称引用、Gradle 命令行中统一使用。

// 在 build.gradle 中引用子项目的路径
dependencies {
    implementation project(":core")
    implementation project(":service:user-service")
    testImplementation project(":libs:security")
}

1.5 多模块项目结构图

下图展示了一个典型多模块 Gradle 项目的物理目录与逻辑项目路径的对应关系。根项目作为聚合根，子项目按业务域分层组织。

1.6 命令行验证模块结构

配置完成后，通过 Gradle 内置任务可以快速验证模块是否被正确识别：

# 列出所有项目（含根项目）
gradle projects

# 输出示例：
# Root project 'my-platform'
# +--- Project ':core'
# +--- Project ':service'
#      +--- Project ':service:user-service'
#      +--- Project ':service:order-service'
# +--- Project ':web'
#      +--- Project ':web:admin-console'

# 查看特定子项目的属性
gradle :core:properties

1.7 常见错误与解决方案

1.8 性能优化：合理控制模块粒度

多模块并非越多越好。每个子项目都会增加配置阶段的开销。推荐原则：

• 按变更边界拆分：一个模块对应一个独立交付单元或业务域
• 避免过度嵌套：层级深度控制在 2～3 层，过深会增加路径解析成本
• 利用 includeFlat 快速集成同级模块（适用于扁平结构）
• 启用配置缓存：在 gradle.properties 中设置 org.gradle.configuration-cache=true

// gradle.properties — 开启配置缓存与并行执行
org.gradle.parallel=true
org.gradle.configuration-cache=true
org.gradle.caching=true