使用 Gradle 组织项目结构 - Gradle 构建系统

组织 Gradle 项目结构以优化构建性能非常重要。多项目构建是 Gradle 中的标准方式。

多项目构建包含一个根项目和一个或多个子项目。Gradle 可以在单次执行中构建根项目和任意数量的子项目。

项目位置

多项目构建在 Gradle 视为根路径的目录中包含一个根项目：.。

子项目物理上位于根路径下：./subproject。

子项目有路径，用于表示该子项目在多项目构建中的位置。在大多数情况下，项目路径与其在文件系统中的位置一致。

项目结构在 settings.gradle(.kts) 文件中创建。该 settings 文件必须存在于根目录中。

一个简单的多项目构建

让我们看一个包含根项目和单个子项目的基本多项目构建示例。

根项目名为 basic-multiproject，位于您机器的某个位置。从 Gradle 的角度来看，根目录是顶层目录 .。

项目包含一个名为 ./app 的子项目。

.
├── app
│   ...
│   └── build.gradle.kts
└── settings.gradle.kts

.
├── app
│   ...
│   └── build.gradle
└── settings.gradle

这是启动任何 Gradle 项目的推荐项目结构。build init 插件也会生成遵循此结构的骨架项目 - 即一个包含单个子项目的根项目。

settings.gradle(.kts) 文件向 Gradle 描述了项目结构。

settings.gradle.kts

rootProject.name = "basic-multiproject"
include("app")

settings.gradle

rootProject.name = 'basic-multiproject'
include 'app'

在这种情况下，Gradle 会在 ./app 目录中寻找 app 子项目的构建文件。

您可以通过运行 projects 命令来查看多项目构建的结构。

$ ./gradlew -q projects

Projects:

------------------------------------------------------------
Root project 'basic-multiproject'
------------------------------------------------------------

Root project 'basic-multiproject'
\--- Project ':app'

To see a list of the tasks of a project, run gradle <project-path>:tasks
For example, try running gradle :app:tasks

在这个示例中，app 子项目是一个 Java 应用程序，它应用了application 插件并配置了主类。该应用程序会在控制台打印 Hello World。

app/build.gradle.kts

plugins {
    id("application")
}

application {
    mainClass = "com.example.Hello"
}

app/build.gradle

plugins {
    id 'application'
}

application {
    mainClass = 'com.example.Hello'
}

app/src/main/java/com/example/Hello.java

package com.example;

public class Hello {
    public static void main(String[] args) {
        System.out.println("Hello, world!");
    }
}

您可以通过在项目根目录中执行application 插件提供的 run 任务来运行该应用程序。

$ ./gradlew -q run
Hello, world!

添加子项目

在 settings 文件中，您可以使用 include 方法向根项目添加另一个子项目。

settings.gradle.kts

include("project1", "project2:child1", "project3:child1")

settings.gradle

include 'project1', 'project2:child1', 'project3:child1'

include 方法接受项目路径作为参数。项目路径被假定等于相对物理文件系统路径。例如，路径 services:api 默认映射到文件夹 ./services/api（相对于项目根目录 .）。

关于如何使用项目路径的更多示例可以在 Settings.include(java.lang.String[]) 的 DSL 文档中找到。

让我们向上一个创建的项目添加另一个名为 lib 的子项目。

我们只需要在根 settings 文件中添加另一个 include 语句即可。

settings.gradle.kts

rootProject.name = "basic-multiproject"
include("app")
include("lib")

settings.gradle

rootProject.name = 'basic-multiproject'
include 'app'
include 'lib'

Gradle 随后会在 ./lib/ 目录中寻找新的 lib 子项目的构建文件。

.
├── app
│   ...
│   └── build.gradle.kts
├── lib
│   ...
│   └── build.gradle.kts
└── settings.gradle.kts

.
├── app
│   ...
│   └── build.gradle
├── lib
│   ...
│   └── build.gradle
└── settings.gradle

项目描述符

为了向 Gradle 进一步描述项目架构，settings 文件提供了项目描述符。

您可以随时在 settings 文件中修改这些描述符。

要访问描述符，您可以

settings.gradle.kts

include("project-a")
println(rootProject.name)
println(project(":project-a").name)

settings.gradle

include('project-a')
println rootProject.name
println project(':project-a').name

使用此描述符，您可以更改项目的名称、项目目录和构建文件。

settings.gradle.kts

rootProject.name = "main"
include("project-a")
project(":project-a").projectDir = file("custom/my-project-a")
project(":project-a").buildFileName = "project-a.gradle.kts"

settings.gradle

rootProject.name = 'main'
include('project-a')
project(':project-a').projectDir = file('custom/my-project-a')
project(':project-a').buildFileName = 'project-a.gradle'

有关更多信息，请查阅 API 文档中的 ProjectDescriptor 类。

修改子项目路径

让我们举一个具有以下结构的假设项目。

.
├── app
│   ...
│   └── build.gradle.kts
├── subs // Gradle may see this as a subproject
│   └── web // Gradle may see this as a subproject
│       └── my-web-module // Intended subproject
│           ...
│           └── build.gradle.kts
└── settings.gradle.kts

.
├── app
│   ...
│   └── build.gradle
├── subs // Gradle may see this as a subproject
│   └── web // Gradle may see this as a subproject
│       └── my-web-module // Intended subproject
│           ...
│           └── build.gradle
└── settings.gradle

如果您的 settings.gradle(.kts) 文件如下所示。

include(':subs:web:my-web-module')

Gradle 会将一个逻辑项目名称为 :subs:web:my-web-module 的子项目，以及两个可能并非故意的、逻辑名称为 :subs 和 :subs:web 的其他子项目都视为子项目。这可能导致出现幻影构建目录，尤其是在使用 allprojects{} 或 subproject{} 时。

为避免这种情况，您可以使用

include(':my-web-module')
project(':my-web-module').projectDir = "subs/web/my-web-module"

这样您最终只会得到一个名为 :my-web-module 的子项目。

因此，虽然物理项目布局相同，但逻辑结果不同。

命名建议

随着项目规模的增长，命名和一致性变得越来越重要。为了保持构建的可维护性，我们建议如下：

保持子项目的默认项目名称：可以在 settings 文件中配置自定义项目名称。但是，这会给开发者带来不必要的额外工作来跟踪哪些项目属于哪些文件夹。
对所有项目名称使用小写连字符：所有字母都是小写，单词之间用短划线（-）字符分隔。
在 settings 文件中定义根项目名称：rootProject.name 有效地为构建分配一个名称，该名称用于构建扫描等报告中。如果未设置根项目名称，则名称将是容器目录名称，这可能不稳定（即，您可以在任何目录中检出您的项目）。如果未设置根项目名称并检出到文件系统的根目录（例如 / 或 C:\），则会随机生成名称。

此页面有帮助吗？