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

Project 对象

由于 Groovy 是一种基于 Java 的面向对象语言，其属性和方法适用于对象。在某些情况下，对象是隐式的——尤其是在构建脚本的顶层，即未嵌套在 {} 代码块中。

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

version = '1.0.0.GA'

configurations {
    ...
}

version 和 configurations {} 都属于 org.gradle.api.Project。

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

避免在构建脚本中使用 Groovy MetaClass 元编程技术。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 对象添加自己的属性。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')
}

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

您应该理解代码块的两个重要方面

  1. 它们实现为具有特定签名的方法。

  2. 它们可以改变非限定方法和属性的目标（“委托对象”）。

两者都基于 Groovy 语言特性，我们将在后续章节中解释它们。

代码块方法签名

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

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

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

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

委托（Delegation）

属性部分列出了非限定属性的可能来源。一个常见的地方是 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 也除了旧的 Closure 版本外，还提供了 Action 变体。

局部变量

def <name> = <value>        // Untyped variable
<type> <name> = <value>     // Typed variable
示例
def i = 1
String errorMsg = 'Failed, because reasons'

局部变量是 Groovy 的一个结构——与附加属性不同——可用于在构建脚本内共享值。

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

在更窄的上下文中——例如配置任务——局部变量偶尔会很有用。