组织 Gradle 项目 - Gradle 中文

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

分离特定语言的源文件

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

一些编译器能够在同一源目录中交叉编译多种语言。Groovy 编译器可以处理混合位于 src/main/groovy 中的 Java 和 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 定义为编译的默认源目录。
已编译源代码和其他工件（如 JAR 文件）的输出目录为 build。

通过坚持使用默认约定，新开发人员可以立即了解如何找到项目中的相关内容。虽然可以重新配置这些约定，但它会让构建脚本用户和作者更难管理构建逻辑及其结果。除非需要适应旧项目的布局，否则请尽可能坚持使用默认约定。请参阅相关插件的参考页面，了解其默认约定。

始终定义设置文件

每次调用构建时，Gradle 都会尝试找到 settings.gradle（Groovy DSL）或 settings.gradle.kts（Kotlin DSL）文件。为此，运行时会向上遍历目录树层次结构，直到根目录。算法会在找到设置文件后停止搜索。

始终将 settings.gradle 添加到构建的根目录，以避免最初的性能影响。该文件可以为空，也可以定义项目的所需名称。

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

以下示例显示了标准 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 会自动编译和测试此代码，并将其放入构建脚本的类路径中。对于多项目构建，只能有一个 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 发行版加上一个或多个自定义初始化脚本组成。初始化脚本与发行版捆绑在一起，并在每次运行构建时应用。开发人员只需将其签入的包装器文件指向自定义 Gradle 发行版的 URL 即可。

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

创建自定义 Gradle 发行版的典型步骤如下

实现下载和重新打包 Gradle 发行版的逻辑。
使用所需的逻辑定义一个或多个初始化脚本。
将初始化脚本与 Gradle 发行版捆绑在一起。
将 Gradle 发行版存档上传到 HTTP 服务器。
更改所有项目的包装器文件，使其指向自定义 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"
    }
}

此页面有帮助吗？