Groovy 构建脚本入门

理想情况下，Groovy 构建脚本看起来主要像配置：设置项目的一些属性，配置依赖项，声明任务等等。该配置基于 Groovy 语言结构。本入门指南旨在解释这些结构是什么，以及——最重要的是——它们如何与 Gradle 的 API 文档相关联。

`Project` 对象

由于 Groovy 是基于 Java 的面向对象语言，因此其属性和方法适用于对象。在某些情况下，对象是隐式的——特别是在构建脚本的顶层，即不在 {} 块内嵌套。

考虑以下构建脚本片段，其中包含一个无限定属性和块

version = '1.0.0.GA'

configurations {
    ...
}

version 和 configurations {} 都是 org.gradle.api.Project 的一部分。

此示例反映了每个 Groovy 构建脚本都由 Project 的隐式实例支持。如果您看到一个无限定元素并且不知道它在哪里定义，请始终检查 Project API 文档以查看它是否来自那里。

避免在构建脚本中使用 Groovy 元类编程技术。Gradle 提供了自己的 API 用于添加动态运行时属性。

使用特定于 Groovy 的元编程会导致构建在构建之间保留大量内存，最终会导致 Gradle 守护进程出现内存不足错误。

属性

<obj>.<name>                // Get a property value
<obj>.<name> = <value>      // Set a property to a new value
"$<name>"                   // Embed a property value in a string
"${<obj>.<name>}"           // Same as previous (embedded value)

示例

version = '1.0.1'
myCopyTask.description = 'Copies some files'

file("$projectDir/src")
println "Destination: ${myCopyTask.destinationDir}"

属性表示对象的一些状态。= 符号的存在是您正在查看属性的明确指示。否则，限定名称（以 <obj>. 开头）——没有任何其他修饰也是一个属性。

如果名称未限定，则它可能是以下之一

具有该名称的任务实例。
关于 Project 的属性。
在项目的其他地方定义的额外属性。
块内隐式对象的一个属性。
在构建脚本中之前定义的局部变量。

请注意，插件可以将自己的属性添加到 Project 对象中。 API 文档列出了核心插件添加的所有属性。如果您难以找到属性的来源，请查看构建使用的插件的文档。

在构建脚本中引用非核心插件添加的项目属性时，请考虑在它前面加上 project. —— 这样就很清楚该属性属于项目对象。

API 文档中的属性

Groovy DSL 参考显示了属性在构建脚本中的使用方式，但 Javadocs 仅显示方法。这是因为属性在幕后是作为方法实现的。

如果存在名为 get<PropertyName> 的方法，该方法没有参数并返回与属性相同的类型，则可以读取属性。
如果存在名为 set<PropertyName> 的方法，该方法有一个参数，该参数与属性具有相同的类型，返回值类型为 void，则可以修改属性。

请注意，属性名称通常以小写字母开头，但该字母在方法名称中为大写。因此，getter 方法 getProjectVersion() 对应于属性 projectVersion。当名称以至少两个大写字母开头时，此约定不适用，在这种情况下，大小写不会改变。例如，getRAM() 对应于属性 RAM。

示例

project.getVersion()
project.version

project.setVersion('1.0.1')
project.version = '1.0.1'

方法

<obj>.<name>()              // Method call with no arguments
<obj>.<name>(<arg>, <arg>)  // Method call with multiple arguments
<obj>.<name> <arg>, <arg>   // Method call with multiple args (no parentheses)

示例

myCopyTask.include '**/*.xml', '**/*.properties'

ext.resourceSpec = copySpec()   // `copySpec()` comes from `Project`

file('src/main/java')
println 'Hello, World!'

方法表示对象的某些行为，尽管 Gradle 通常也使用方法来配置对象的状态。方法可以通过其参数或空括号来识别。请注意，有时需要括号，例如当方法没有参数时，因此您可能会发现始终使用括号最简单。

Gradle 遵循一种约定，如果一个方法与一个基于集合的属性同名，那么该方法会将它的值追加到该集合中。

代码块

代码块也是方法，只是最后一个参数的类型是特定的。

<obj>.<name> {
     ...
}

<obj>.<name>(<arg>, <arg>) {
     ...
}

示例

plugins {
    id 'java-library'
}

configurations {
    assets
}

sourceSets {
    main {
        java {
            srcDirs = ['src']
        }
    }
}

dependencies {
    implementation project(':util')
}

代码块是一种机制，可以一次性配置构建元素的多个方面。它们还提供了一种嵌套配置的方式，从而形成结构化数据。

关于代码块，有两个重要的方面需要了解

它们被实现为具有特定签名的方法。
它们可以更改未限定方法和属性的目标（“委托”）。

两者都基于 Groovy 语言特性，我们将在以下部分中解释它们。

代码块方法签名

您可以通过方法的签名，更具体地说，通过其参数类型，轻松地识别出作为代码块实现的方法。如果一个方法对应于一个代码块

它必须至少有一个参数。
最后一个参数必须是 groovy.lang.Closure 或 org.gradle.api.Action 类型。

例如，Project.copy(Action) 符合这些要求，因此您可以使用以下语法

copy {
    into layout.buildDirectory.dir("tmp")
    from 'custom-resources'
}

这引出了一个问题，即 into() 和 from() 如何工作。它们显然是方法，但在 API 文档中您会在哪里找到它们？答案来自理解对象委托。

委托

关于属性的部分列出了未限定属性可能存在的位置。一个常见的位置是在 Project 对象上。但是，在代码块内部，对于那些未限定的属性和方法，还有一个替代来源：代码块的委托对象。

为了帮助解释这个概念，请考虑上一节中的最后一个示例

copy {
    into layout.buildDirectory.dir("tmp")
    from 'custom-resources'
}

此示例中的所有方法和属性都是未限定的。您可以在 Project API 文档中轻松找到 copy() 和 layout，但 into() 和 from() 呢？这些方法是针对 copy {} 代码块的委托对象解析的。该委托对象的类型是什么？您需要查看 API 文档以了解这一点。

根据代码块方法的签名，有两种方法可以确定委托类型

对于Action参数，请查看类型的参数。

在上面的示例中，方法签名为copy(Action<? super CopySpec>)，它是在尖括号内的部分，告诉您委托类型 - 在这种情况下为CopySpec。
对于Closure参数，文档将在描述中明确说明正在配置的类型或委托类型（相同事物的不同术语）。

因此，您可以在CopySpec上找到into()和from()。您甚至可能会注意到，这两个方法都有以Action作为最后一个参数的变体，这意味着您可以使用块语法与它们一起使用。

所有新的 Gradle API 都声明了Action参数类型而不是Closure，这使得挑选委托类型变得非常容易。即使是旧的 API 也有Action变体，除了旧的Closure变体之外。

局部变量

def <name> = <value>        // Untyped variable
<type> <name> = <value>     // Typed variable

示例

def i = 1
String errorMsg = 'Failed, because reasons'

局部变量是 Groovy 的构造 - 与额外属性不同 - 可以用来在构建脚本中共享值。

避免在项目的根目录中使用局部变量，即作为伪项目属性。它们不能在构建脚本之外读取，Gradle 对它们一无所知。

在更窄的上下文中 - 例如配置任务 - 局部变量有时可能会有所帮助。

此页面是否有帮助？