组织 Gradle 项目 - Gradle 构建系统

每个软件项目的源代码和构建逻辑都应该以有意义的方式组织。本页介绍了实现可读、可维护项目的最佳实践。以下部分还将讨论常见问题以及如何避免这些问题。

分离特定语言的源文件

Gradle 的语言插件建立了用于发现和编译源代码的约定。例如，应用了 Java 插件的项目将自动编译目录 src/main/java 中的代码。其他语言插件遵循相同的模式。目录路径的最后一部分通常表示源文件的预期语言。

一些编译器能够在同一源目录中交叉编译多种语言。Groovy 编译器可以处理将 Java 和 Groovy 源文件混合放置在 src/main/groovy 中的情况。Gradle 建议您根据语言将源文件放在不同的目录中，因为这样做可以提高构建性能，并且用户和构建都可以做出更强的假设。

以下源文件树包含 Java 和 Kotlin 源文件。Java 源文件位于 src/main/java 中，而 Kotlin 源文件位于 src/main/kotlin 中。

.
├── build.gradle.kts
└── src
    └── main
        ├── java
        │   └── HelloWorld.java
        └── kotlin
            └── Utils.kt

.
├── build.gradle
└── src
    └── main
        ├── java
        │   └── HelloWorld.java
        └── kotlin
            └── Utils.kt

每种测试类型分离源文件

项目定义和执行不同类型的测试（例如单元测试、集成测试、功能测试或冒烟测试）是很常见的。理想情况下，每种测试类型的测试源代码应存储在专门的源目录中。分离测试源代码对可维护性和关注点分离有积极影响，因为您可以独立运行不同类型的测试。

请参阅此示例，它演示了如何向基于 Java 的项目添加单独的集成测试配置。

尽可能使用标准约定

所有 Gradle 核心插件都遵循软件工程范例约定优于配置。插件逻辑在特定上下文中为用户提供了合理的默认值和标准，即约定。以Java 插件为例。

它将目录 src/main/java 定义为默认的编译源目录。
编译后的源代码和其他 artifacts（如 JAR 文件）的输出目录是 build。

通过遵循默认约定，项目的新开发者可以立即知道如何找到方向。虽然这些约定可以重新配置，但这会使构建脚本的用户和作者更难管理构建逻辑及其结果。除非需要适应遗留项目的布局，否则请尽量遵循默认约定。请参阅相关插件的参考页面，了解其默认约定。

始终定义 settings 文件

每次调用构建时，Gradle 都会尝试查找 settings.gradle (Groovy DSL) 或 settings.gradle.kts (Kotlin DSL) 文件。为此，运行时会遍历目录树的层级，直到根目录。一旦找到 settings 文件，算法就会停止搜索。

始终在构建的根目录中添加 settings.gradle 文件，以避免初始性能影响。该文件可以是空的，也可以定义项目的期望名称。

多项目构建必须在多项目层次结构的根项目中包含 settings.gradle(.kts) 文件。这是必需的，因为 settings 文件定义了哪些项目参与多项目构建。除了定义包含的项目外，您可能还需要它来将库添加到构建脚本的 classpath 中。

以下示例显示了标准的 Gradle 项目布局

.
├── settings.gradle.kts
├── subproject-one
│   └── build.gradle.kts
└── subproject-two
    └── build.gradle.kts

.
├── settings.gradle
├── subproject-one
│   └── build.gradle
└── subproject-two
    └── build.gradle

使用 `buildSrc` 抽象命令式逻辑

复杂的构建逻辑通常适合封装为自定义任务或二进制插件。自定义任务和插件的实现不应该直接写在构建脚本中。只要代码不需要在多个独立的项目之间共享，使用 buildSrc 是一个非常方便的方式。

目录 buildSrc 被视为包含的构建。一旦发现该目录，Gradle 会自动编译其中的代码并将其放到构建脚本的 classpath 中。对于多项目构建，只能有一个 buildSrc 目录，它必须位于根项目目录中。buildSrc 应该优先于脚本插件，因为它更容易维护、重构和测试代码。

buildSrc 使用与 Java 和 Groovy 项目相同的源代码约定。它还提供对 Gradle API 的直接访问。额外的依赖项可以在 buildSrc 下专门的 build.gradle 文件中声明。

示例 1. 自定义 buildSrc 构建脚本

buildSrc/build.gradle.kts

repositories {
    mavenCentral()
}

dependencies {
    testImplementation("junit:junit:4.13")
}

buildSrc/build.gradle

repositories {
    mavenCentral()
}

dependencies {
    testImplementation 'junit:junit:4.13'
}

一个包含 buildSrc 的典型项目布局如下。buildSrc 下的任何代码都应使用类似于应用程序代码的包结构。可选地，如果需要额外的配置（例如应用插件或声明依赖项），buildSrc 目录可以包含一个构建脚本。

.
├── buildSrc
│   ├── build.gradle.kts
│   └── src
│       ├── main
│       │   └── java
│       │       └── com
│       │           └── enterprise
│       │               ├── Deploy.java
│       │               └── DeploymentPlugin.java
│       └── test
│           └── java
│               └── com
│                   └── enterprise
│                       └── DeploymentPluginTest.java
├── settings.gradle.kts
├── subproject-one
│   └── build.gradle.kts
└── subproject-two
    └── build.gradle.kts

.
├── buildSrc
│   ├── build.gradle
│   └── src
│       ├── main
│       │   └── java
│       │       └── com
│       │           └── enterprise
│       │               ├── Deploy.java
│       │               └── DeploymentPlugin.java
│       └── test
│           └── java
│               └── com
│                   └── enterprise
│                       └── DeploymentPluginTest.java
├── settings.gradle
├── subproject-one
│   └── build.gradle
└── subproject-two
    └── build.gradle

buildSrc 中的更改会导致整个项目变为过时。

因此，当进行小的增量更改时，--no-rebuild 命令行选项通常有助于更快地获得反馈。请记住定期运行完整构建。

在 `gradle.properties` 文件中声明属性

在 Gradle 中，属性可以在构建脚本中、gradle.properties 文件中或作为命令行参数定义。

对于临时场景，通常在命令行上声明属性。例如，您可能希望传入一个特定的属性值来仅控制本次构建的运行时行为。构建脚本中的属性很容易成为维护的难题，并使构建脚本逻辑变得复杂。gradle.properties 有助于将属性与构建脚本分离，应作为可行的选项加以探索。它是放置控制构建环境的属性的好位置。

典型的项目设置将 gradle.properties 文件放在构建的根目录中。或者，如果您希望它应用于机器上的所有构建，该文件也可以放在 GRADLE_USER_HOME 目录中。

.
├── gradle.properties
└── settings.gradle.kts
├── subproject-a
│   └── build.gradle.kts
└── subproject-b
    └── build.gradle.kts

.
├── gradle.properties
└── settings.gradle
├── subproject-a
│   └── build.gradle
└── subproject-b
    └── build.gradle

避免任务输出重叠

任务应定义输入和输出，以获得增量构建功能带来的性能优势。声明任务的输出时，请确保用于写入输出的目录在项目的所有任务中都是唯一的。

不同任务产生的输出文件混淆或覆盖会损害最新检查，导致构建变慢。反过来，这些文件系统更改可能会阻止 Gradle 的构建缓存正确识别和缓存原本可以缓存的任务。

使用自定义 Gradle 发布版标准化构建

企业经常希望通过定义通用约定或规则来标准化组织中所有项目的构建平台。您可以通过初始化脚本来实现这一点。初始化脚本可以非常轻松地将构建逻辑应用于单台机器上的所有项目。例如，声明内部仓库及其凭据。

这种方法有一些缺点。首先，您必须在公司所有开发者之间沟通设置过程。此外，统一更新初始化脚本逻辑可能会具有挑战性。

自定义 Gradle 发布版是解决这个问题的实用方案。自定义 Gradle 发布版包含标准 Gradle 发布版以及一个或多个自定义初始化脚本。初始化脚本与发布版捆绑在一起，并在每次运行构建时应用。开发者只需将其提交的Wrapper 文件指向自定义 Gradle 发布版的 URL。

自定义 Gradle 发布版还可以在发布版的根目录中包含一个 gradle.properties 文件，该文件提供组织范围内的一组控制构建环境的属性。

创建自定义 Gradle 发布版通常需要以下步骤

实现下载和重新打包 Gradle 发布版的逻辑。
定义一个或多个具有所需逻辑的初始化脚本。
将初始化脚本与 Gradle 发布版捆绑在一起。
将 Gradle 发布版存档上传到 HTTP 服务器。
更改所有项目的 Wrapper 文件，使其指向自定义 Gradle 发布版的 URL。

示例 2. 构建自定义 Gradle 发布版

build.gradle

plugins {
    id 'base'
}

// This is defined in buildSrc
import org.gradle.distribution.DownloadGradle

version = '0.1'

tasks.register('downloadGradle', DownloadGradle) {
    description = 'Downloads the Gradle distribution with a given version.'
    gradleVersion = '4.6'
}

tasks.register('createCustomGradleDistribution', Zip) {
    description = 'Builds custom Gradle distribution and bundles initialization scripts.'

    dependsOn downloadGradle

    def projectVersion = project.version
    archiveFileName = downloadGradle.gradleVersion.map { gradleVersion ->
        "mycompany-gradle-${gradleVersion}-${projectVersion}-bin.zip"
    }

    from zipTree(downloadGradle.destinationFile)

    from('src/init.d') {
        into "${downloadGradle.distributionNameBase.get()}/init.d"
    }
}

本页面有帮助吗？