实现二进制插件 - Gradle 中文

二进制插件是指编译为 JAR 文件并以 JAR 文件形式分发的插件。这些插件通常用 Java 或 Kotlin 编写，并为 Gradle 构建提供自定义功能或任务。

使用插件开发插件

Gradle 插件开发插件可用于帮助开发 Gradle 插件。

此插件将自动应用Java 插件，将gradleApi()依赖项添加到api配置，在生成的 JAR 文件中生成所需的插件描述符，并在发布时配置要使用的插件标记工件。

要应用和配置插件，请将以下代码添加到构建文件中

build.gradle.kts

plugins {
    `java-gradle-plugin`
}

gradlePlugin {
    plugins {
        create("simplePlugin") {
            id = "org.example.greeting"
            implementationClass = "org.example.GreetingPlugin"
        }
    }
}

build.gradle

plugins {
    id 'java-gradle-plugin'
}

gradlePlugin {
    plugins {
        simplePlugin {
            id = 'org.example.greeting'
            implementationClass = 'org.example.GreetingPlugin'
        }
    }
}

编写和使用自定义任务类型是开发插件时推荐的做法，因为它自动受益于增量构建。将插件应用到项目的一个额外好处是，任务validatePlugins会自动检查自定义任务类型实现中定义的每个公共属性的现有输入/输出注释。

创建插件 ID

插件 ID 旨在全局唯一，类似于 Java 包名称（即反向域名）。此格式有助于防止命名冲突，并允许对具有相似所有权的插件进行分组。

明确的插件标识符简化了将插件应用到项目。插件 ID 应结合反映命名空间（指向您或您的组织的合理指针）和它提供的插件名称的组件。例如，如果您的 Github 帐户名为 foo，您的插件名为 bar，则合适的插件 ID 可能为 com.github.foo.bar。类似地，如果该插件是在 baz 组织中开发的，则插件 ID 可能为 org.baz.bar。

插件 ID 应遵守以下准则

可以包含任何字母数字字符、“.” 和 “-”。
必须至少包含一个 “.” 字符，以将命名空间与插件的名称分隔开。
惯例上对命名空间使用小写反向域名约定。
惯例上在名称中仅使用小写字符。
不得使用 org.gradle、com.gradle 和 com.gradleware 命名空间。
不能以 “.” 字符开头或结尾。
不能包含连续的 “.” 字符（即 “..”）。

标识所有权和名称的命名空间足以作为插件 ID。

在单个 JAR 工件中捆绑多个插件时，建议遵循相同的命名约定。此做法有助于将相关的插件逻辑分组。

在单个项目中可以定义和注册的插件数量没有限制（由不同的标识符）。

作为类编写的插件的标识符应在包含插件类的项目的构建脚本中定义。为此，需要应用 java-gradle-plugin

buildSrc/build.gradle.kts

plugins {
    id("java-gradle-plugin")
}

gradlePlugin {
    plugins {
        create("androidApplicationPlugin") {
            id = "com.android.application"
            implementationClass = "com.android.AndroidApplicationPlugin"
        }
        create("androidLibraryPlugin") {
            id = "com.android.library"
            implementationClass = "com.android.AndroidLibraryPlugin"
        }
    }
}

buildSrc/build.gradle

plugins {
    id 'java-gradle-plugin'
}

gradlePlugin {
    plugins {
        androidApplicationPlugin {
            id = 'com.android.application'
            implementationClass = 'com.android.AndroidApplicationPlugin'
        }
        androidLibraryPlugin {
            id = 'com.android.library'
            implementationClass = 'com.android.AndroidLibraryPlugin'
        }
    }
}

使用文件

在开发插件时，最好在接受文件位置的输入配置时保持灵活性。

建议使用 Gradle 的托管属性和 project.layout 来选择文件或目录位置。这将启用延迟配置，以便仅在需要文件时才解析实际位置，并且可以在构建配置期间随时重新配置。

此 Gradle 构建文件定义了一个任务 GreetingToFileTask，用于向文件写入问候语。它还注册了两个任务：greet，用于创建包含问候语的文件，和 sayGreeting，用于打印文件内容。greetingFile 属性用于指定问候语的文件路径

build.gradle.kts

abstract class GreetingToFileTask : DefaultTask() {

    @get:OutputFile
    abstract val destination: RegularFileProperty

    @TaskAction
    fun greet() {
        val file = destination.get().asFile
        file.parentFile.mkdirs()
        file.writeText("Hello!")
    }
}

val greetingFile = objects.fileProperty()

tasks.register<GreetingToFileTask>("greet") {
    destination = greetingFile
}

tasks.register("sayGreeting") {
    dependsOn("greet")
    val greetingFile = greetingFile
    doLast {
        val file = greetingFile.get().asFile
        println("${file.readText()} (file: ${file.name})")
    }
}

greetingFile = layout.buildDirectory.file("hello.txt")

build.gradle

abstract class GreetingToFileTask extends DefaultTask {

    @OutputFile
    abstract RegularFileProperty getDestination()

    @TaskAction
    def greet() {
        def file = getDestination().get().asFile
        file.parentFile.mkdirs()
        file.write 'Hello!'
    }
}

def greetingFile = objects.fileProperty()

tasks.register('greet', GreetingToFileTask) {
    destination = greetingFile
}

tasks.register('sayGreeting') {
    dependsOn greet
    doLast {
        def file = greetingFile.get().asFile
        println "${file.text} (file: ${file.name})"
    }
}

greetingFile = layout.buildDirectory.file('hello.txt')

$ gradle -q sayGreeting
Hello! (file: hello.txt)

在此示例中，我们将 greet 任务的 destination 属性配置为一个闭包/提供程序，它使用 Project.file(java.lang.Object) 方法进行评估，以便在最后一刻将闭包/提供程序的返回值转换为 File 对象。请注意，我们在任务配置之后指定 greetingFile 属性值。这种惰性评估是接受任何值（在设置文件属性时）然后在读取属性时解析该值的优势所在。

您可以在使用文件中了解有关惰性使用文件的更多信息。

使用扩展使插件可配置

大多数插件都为构建脚本和其他插件提供配置选项，以便自定义插件的工作方式。插件使用扩展对象来实现此目的。

Project 具有关联的 ExtensionContainer 对象，该对象包含已应用于项目的插件的所有设置和属性。您可以通过向此容器添加扩展对象来为插件提供配置。

扩展对象只是一个具有表示配置的 Java Bean 属性的对象。

让我们向项目添加一个 greeting 扩展对象，它允许您配置问候语

build.gradle.kts

interface GreetingPluginExtension {
    val message: Property<String>
}

class GreetingPlugin : Plugin<Project> {
    override fun apply(project: Project) {
        // Add the 'greeting' extension object
        val extension = project.extensions.create<GreetingPluginExtension>("greeting")
        // Add a task that uses configuration from the extension object
        project.task("hello") {
            doLast {
                println(extension.message.get())
            }
        }
    }
}

apply<GreetingPlugin>()

// Configure the extension
the<GreetingPluginExtension>().message = "Hi from Gradle"

build.gradle

interface GreetingPluginExtension {
    Property<String> getMessage()
}

class GreetingPlugin implements Plugin<Project> {
    void apply(Project project) {
        // Add the 'greeting' extension object
        def extension = project.extensions.create('greeting', GreetingPluginExtension)
        // Add a task that uses configuration from the extension object
        project.task('hello') {
            doLast {
                println extension.message.get()
            }
        }
    }
}

apply plugin: GreetingPlugin

// Configure the extension
greeting.message = 'Hi from Gradle'

$ gradle -q hello
Hi from Gradle

在此示例中，GreetingPluginExtension 是一个具有名为 message 的属性的对象。扩展对象以 greeting 名称添加到项目。此对象作为与扩展对象同名的项目属性变为可用。the<GreetingPluginExtension>() 等效于 project.extensions.getByType(GreetingPluginExtension::class.java)。

通常，您需要在单个插件上指定几个相关属性。Gradle 为每个扩展对象添加一个配置块，以便您可以对设置进行分组

build.gradle.kts

interface GreetingPluginExtension {
    val message: Property<String>
    val greeter: Property<String>
}

class GreetingPlugin : Plugin<Project> {
    override fun apply(project: Project) {
        val extension = project.extensions.create<GreetingPluginExtension>("greeting")
        project.task("hello") {
            doLast {
                println("${extension.message.get()} from ${extension.greeter.get()}")
            }
        }
    }
}

apply<GreetingPlugin>()

// Configure the extension using a DSL block
configure<GreetingPluginExtension> {
    message = "Hi"
    greeter = "Gradle"
}

build.gradle

interface GreetingPluginExtension {
    Property<String> getMessage()
    Property<String> getGreeter()
}

class GreetingPlugin implements Plugin<Project> {
    void apply(Project project) {
        def extension = project.extensions.create('greeting', GreetingPluginExtension)
        project.task('hello') {
            doLast {
                println "${extension.message.get()} from ${extension.greeter.get()}"
            }
        }
    }
}

apply plugin: GreetingPlugin

// Configure the extension using a DSL block
greeting {
    message = 'Hi'
    greeter = 'Gradle'
}

$ gradle -q hello
Hi from Gradle

在此示例中，可以在 configure<GreetingPluginExtension> 块中对多个设置进行分组。configure 函数用于配置扩展对象。它提供了一种便捷的方式来设置属性或将配置应用于这些对象。在构建脚本的 configure 函数中使用的类型（GreetingPluginExtension）必须与扩展类型匹配。然后，在执行该块时，该块的接收器就是扩展。

在此示例中，可以在 greeting 闭包中对多个设置进行分组。构建脚本中闭包块的名称（greeting）必须与扩展对象名称匹配。然后，在执行该闭包时，扩展对象上的字段将基于标准 Groovy 闭包委托功能映射到闭包中的变量。

声明 DSL 配置容器

使用扩展对象扩展 Gradle DSL，为插件添加项目属性和 DSL 块。由于扩展对象是一个常规对象，因此可以通过向扩展对象添加属性和方法，在插件块内提供您自己的 DSL。

让我们考虑以下构建脚本以作说明。

build.gradle.kts

plugins {
    id("org.myorg.server-env")
}

environments {
    create("dev") {
        url = "http://localhost:8080"
    }

    create("staging") {
        url = "http://staging.enterprise.com"
    }

    create("production") {
        url = "http://prod.enterprise.com"
    }
}

build.gradle

plugins {
    id 'org.myorg.server-env'
}

environments {
    dev {
        url = 'http://localhost:8080'
    }

    staging {
        url = 'http://staging.enterprise.com'
    }

    production {
        url = 'http://prod.enterprise.com'
    }
}

插件公开的 DSL 公开了一个容器，用于定义一组环境。用户配置的每个环境都有一个任意但声明性的名称，并用它自己的 DSL 配置块表示。上面的示例实例化了一个开发、暂存和生产环境，包括它各自的 URL。

每个环境都必须在代码中具有数据表示，以捕获这些值。环境的名称是不可变的，可以作为构造函数参数传入。目前，数据对象存储的唯一其他参数是 URL。

以下 ServerEnvironment 对象满足这些要求

ServerEnvironment.java

abstract public class ServerEnvironment {
    private final String name;

    @javax.inject.Inject
    public ServerEnvironment(String name) {
        this.name = name;
    }

    public String getName() {
        return name;
    }

    abstract public Property<String> getUrl();
}

Gradle 公开了工厂方法 ObjectFactory.domainObjectContainer(Class, NamedDomainObjectFactory)，用于创建数据对象的容器。该方法采用的参数是表示数据的类。可以通过将类型为 NamedDomainObjectContainer 的创建实例添加到具有特定名称的扩展容器中，将其公开给最终用户。

插件在插件实现中对捕获的值进行后处理很常见，例如配置任务

ServerEnvironmentPlugin.java

public class ServerEnvironmentPlugin implements Plugin<Project> {
    @Override
    public void apply(final Project project) {
        ObjectFactory objects = project.getObjects();

        NamedDomainObjectContainer<ServerEnvironment> serverEnvironmentContainer =
            objects.domainObjectContainer(ServerEnvironment.class, name -> objects.newInstance(ServerEnvironment.class, name));
        project.getExtensions().add("environments", serverEnvironmentContainer);

        serverEnvironmentContainer.all(serverEnvironment -> {
            String env = serverEnvironment.getName();
            String capitalizedServerEnv = env.substring(0, 1).toUpperCase() + env.substring(1);
            String taskName = "deployTo" + capitalizedServerEnv;
            project.getTasks().register(taskName, Deploy.class, task -> task.getUrl().set(serverEnvironment.getUrl()));
        });
    }
}

在上面的示例中，为每个用户配置的环境动态创建部署任务。

您可以在开发自定义 Gradle 类型中找到有关实现项目扩展的更多信息。

建模类似 DSL 的 API

插件公开的 DSL 应该是可读且易于理解的。

例如，让我们考虑插件提供的以下扩展。在其当前形式中，它提供了一个用于配置网站创建的“扁平”属性列表

build-flat.gradle.kts

plugins {
    id("org.myorg.site")
}

site {
    outputDir = layout.buildDirectory.file("mysite")
    websiteUrl = "https://gradle.org.cn"
    vcsUrl = "https://github.com/gradle/gradle-site-plugin"
}

build-flat.gradle

plugins {
    id 'org.myorg.site'
}

site {
    outputDir = layout.buildDirectory.file("mysite")
    websiteUrl = 'https://gradle.org.cn'
    vcsUrl = 'https://github.com/gradle/gradle-site-plugin'
}

随着公开属性数量的增加，您应该引入嵌套的、更具表现力的结构。

以下代码段添加了一个名为 customData 的新配置块作为扩展的一部分。这提供了这些属性的含义的更强指示

build.gradle.kts

plugins {
    id("org.myorg.site")
}

site {
    outputDir = layout.buildDirectory.file("mysite")

    customData {
        websiteUrl = "https://gradle.org.cn"
        vcsUrl = "https://github.com/gradle/gradle-site-plugin"
    }
}

build.gradle

plugins {
    id 'org.myorg.site'
}

site {
    outputDir = layout.buildDirectory.file("mysite")

    customData {
        websiteUrl = 'https://gradle.org.cn'
        vcsUrl = 'https://github.com/gradle/gradle-site-plugin'
    }
}

实现此类扩展的后备对象很简单。首先，引入一个新的数据对象来管理属性 websiteUrl 和 vcsUrl

CustomData.java

abstract public class CustomData {

    abstract public Property<String> getWebsiteUrl();

    abstract public Property<String> getVcsUrl();
}

在扩展中，创建一个 CustomData 类的实例和一个方法，将捕获的值委托给数据实例。

要配置基础数据对象，请定义类型为 Action 的参数。

以下示例演示了在扩展定义中使用 Action

SiteExtension.java

abstract public class SiteExtension {

    abstract public RegularFileProperty getOutputDir();

    @Nested
    abstract public CustomData getCustomData();

    public void customData(Action<? super CustomData> action) {
        action.execute(getCustomData());
    }
}

将扩展属性映射到任务属性

插件通常使用扩展从构建脚本中捕获用户输入，并将其映射到自定义任务的输入/输出属性。构建脚本作者与扩展的 DSL 交互，而插件实现处理底层逻辑

app/build.gradle.kts

// Extension class to capture user input
class MyExtension {
    @Input
    var inputParameter: String? = null
}

// Custom task that uses the input from the extension
class MyCustomTask : org.gradle.api.DefaultTask() {
    @Input
    var inputParameter: String? = null

    @TaskAction
    fun executeTask() {
        println("Input parameter: $inputParameter")
    }
}

// Plugin class that configures the extension and task
class MyPlugin : Plugin<Project> {
    override fun apply(project: Project) {
        // Create and configure the extension
        val extension = project.extensions.create("myExtension", MyExtension::class.java)
        // Create and configure the custom task
        project.tasks.register("myTask", MyCustomTask::class.java) {
            group = "custom"
            inputParameter = extension.inputParameter
        }
    }
}

app/build.gradle

// Extension class to capture user input
class MyExtension {
    @Input
    String inputParameter = null
}

// Custom task that uses the input from the extension
class MyCustomTask extends DefaultTask {
    @Input
    String inputParameter = null

    @TaskAction
    def executeTask() {
        println("Input parameter: $inputParameter")
    }
}

// Plugin class that configures the extension and task
class MyPlugin implements Plugin<Project> {
    void apply(Project project) {
        // Create and configure the extension
        def extension = project.extensions.create("myExtension", MyExtension)
        // Create and configure the custom task
        project.tasks.register("myTask", MyCustomTask) {
            group = "custom"
            inputParameter = extension.inputParameter
        }
    }
}

在此示例中，MyExtension 类定义了一个 inputParameter 属性，可在构建脚本中设置。MyPlugin 类配置此扩展并使用其 inputParameter 值来配置 MyCustomTask 任务。然后，MyCustomTask 任务在其逻辑中使用此输入参数。

您可以在延迟配置中了解有关可在任务实现和扩展中使用的类型的更多信息。

使用约定添加默认配置

插件应在特定上下文中提供明智的默认值和标准，以减少用户需要做出的决策数量。使用 project 对象，您可以定义默认值。这些称为约定。

约定是使用默认值初始化的属性，用户可以在其构建脚本中覆盖这些属性。例如

build.gradle.kts

interface GreetingPluginExtension {
    val message: Property<String>
}

class GreetingPlugin : Plugin<Project> {
    override fun apply(project: Project) {
        // Add the 'greeting' extension object
        val extension = project.extensions.create<GreetingPluginExtension>("greeting")
        extension.message.convention("Hello from GreetingPlugin")
        // Add a task that uses configuration from the extension object
        project.task("hello") {
            doLast {
                println(extension.message.get())
            }
        }
    }
}

apply<GreetingPlugin>()

build.gradle

interface GreetingPluginExtension {
    Property<String> getMessage()
}

class GreetingPlugin implements Plugin<Project> {
    void apply(Project project) {
        // Add the 'greeting' extension object
        def extension = project.extensions.create('greeting', GreetingPluginExtension)
        extension.message.convention('Hello from GreetingPlugin')
        // Add a task that uses configuration from the extension object
        project.task('hello') {
            doLast {
                println extension.message.get()
            }
        }
    }
}

apply plugin: GreetingPlugin

$ gradle -q hello
Hello from GreetingPlugin

在此示例中，GreetingPluginExtension 是表示约定的类。message 属性是约定属性，其默认值为“Hello from GreetingPlugin”。

用户可以在其构建脚本中覆盖此值

build.gradle.kts

GreetingPluginExtension {
    message = "Custom message"
}

build.gradle

GreetingPluginExtension {
    message = 'Custom message'
}

$ gradle -q hello
Custom message

将功能与约定分开

在插件中将功能与约定分开，使用户可以选择要应用的任务和约定。

例如，Java Base 插件提供无主见（即通用）功能，如 SourceSets，而 Java 插件则添加了 Java 开发人员熟悉的任务和约定，如 classes、jar 或 javadoc。

在设计您自己的插件时，请考虑开发两个插件——一个用于功能，另一个用于约定——以向用户提供灵活性。

在下面的示例中，MyPlugin 包含约定，而 MyBasePlugin 定义功能。然后，MyPlugin 应用 MyBasePlugin，这称为插件组合。要从另一个插件应用插件

MyBasePlugin.java

import org.gradle.api.Plugin;
import org.gradle.api.Project;

public class MyBasePlugin implements Plugin<Project> {
    public void apply(Project project) {
        // define capabilities
    }
}

MyPlugin.java

import org.gradle.api.Plugin;
import org.gradle.api.Project;

public class MyPlugin implements Plugin<Project> {
    public void apply(Project project) {
        project.getPlugins().apply(MyBasePlugin.class);

        // define conventions
    }
}

对插件做出反应

Gradle 插件实现中的常见模式是在构建中配置现有插件和任务的运行时行为。

例如，插件可以假设它应用于基于 Java 的项目，并自动重新配置标准源目录

InhouseStrongOpinionConventionJavaPlugin.java

public class InhouseStrongOpinionConventionJavaPlugin implements Plugin<Project> {
    public void apply(Project project) {
        // Careful! Eagerly appyling plugins has downsides, and is not always recommended.
        project.getPlugins().apply(JavaPlugin.class);
        SourceSetContainer sourceSets = project.getExtensions().getByType(SourceSetContainer.class);
        SourceSet main = sourceSets.getByName(SourceSet.MAIN_SOURCE_SET_NAME);
        main.getJava().setSrcDirs(Arrays.asList("src"));
    }
}

这种方法的缺点是它会自动强制项目应用 Java 插件，从而对其施加强烈的意见（即，降低灵活性和通用性）。实际上，应用插件的项目甚至可能不处理 Java 代码。

插件可以响应使用项目应用 Java 插件这一事实，而不是自动应用 Java 插件。只有在这种情况下，才会应用特定配置

InhouseConventionJavaPlugin.java

public class InhouseConventionJavaPlugin implements Plugin<Project> {
    public void apply(Project project) {
        project.getPlugins().withType(JavaPlugin.class, javaPlugin -> {
            SourceSetContainer sourceSets = project.getExtensions().getByType(SourceSetContainer.class);
            SourceSet main = sourceSets.getByName(SourceSet.MAIN_SOURCE_SET_NAME);
            main.getJava().setSrcDirs(Arrays.asList("src"));
        });
    }
}

如果没有任何充分理由假设使用项目具有预期设置，则响应插件比应用插件更可取。

同一概念适用于任务类型

InhouseConventionWarPlugin.java

public class InhouseConventionWarPlugin implements Plugin<Project> {
    public void apply(Project project) {
        project.getTasks().withType(War.class).configureEach(war ->
            war.setWebXml(project.file("src/someWeb.xml")));
    }
}

响应构建功能

插件可以访问构建中构建功能的状态。构建功能 API允许检查用户是否请求了特定的 Gradle 功能，以及它是否在当前构建中处于活动状态。构建功能的一个示例是配置缓存。

有两个主要用例

在报告或统计数据中使用构建功能的状态。
通过禁用不兼容的插件功能，逐步采用实验性 Gradle 功能。

下面是一个同时利用这两个用例的插件示例。

对构建功能做出反应

public abstract class MyPlugin implements Plugin<Project> {

    @Inject
    protected abstract BuildFeatures getBuildFeatures(); (1)

    @Override
    public void apply(Project p) {
        BuildFeatures buildFeatures = getBuildFeatures();

        Boolean configCacheRequested = buildFeatures.getConfigurationCache().getRequested() (2)
            .getOrNull(); // could be null if user did not opt in nor opt out
        String configCacheUsage = describeFeatureUsage(configCacheRequested);
        MyReport myReport = new MyReport();
        myReport.setConfigurationCacheUsage(configCacheUsage);

        boolean isolatedProjectsActive = buildFeatures.getIsolatedProjects().getActive() (3)
            .get(); // the active state is always defined
        if (!isolatedProjectsActive) {
            myOptionalPluginLogicIncompatibleWithIsolatedProjects();
        }
    }

    private String describeFeatureUsage(Boolean requested) {
        return requested == null ? "no preference" : requested ? "opt-in" : "opt-out";
    }

    private void myOptionalPluginLogicIncompatibleWithIsolatedProjects() {
    }
}

1	`BuildFeatures` 服务可以注入到插件、任务和其他受管类型中。
2	访问功能的`requested` 状态以进行报告。
3	使用功能的`active` 状态以禁用不兼容的功能。

构建功能属性

BuildFeature 状态属性用Provider<Boolean> 类型表示。

构建功能的BuildFeature.getRequested() 状态确定用户是否请求启用或禁用该功能。

当requested 提供程序值为

true — 用户选择使用该功能
false — 用户选择不使用该功能
undefined — 用户既未选择使用该功能，也未选择不使用该功能

构建功能的BuildFeature.getActive() 状态始终是已定义的。它表示构建中该功能的有效状态。

当active提供程序值为

true — 该特性可能以特定于该特性的方式影响构建行为
false — 该特性不会影响构建行为

请注意，active状态不依赖于requested状态。即使用户请求了某个特性，它也可能由于构建中使用了其他构建选项而不会处于活动状态。即使用户未指定首选项，Gradle 也可以默认激活某个特性。

提供默认依赖项

插件的实现有时需要使用外部依赖项。

您可能希望使用 Gradle 的依赖项管理机制自动下载工件，并稍后在插件中声明的任务类型的操作中使用它。理想情况下，插件实现不需要向用户询问该依赖项的坐标 - 它可以简单地预定义一个明智的默认版本。

我们来看一个下载包含用于进一步处理的数据的文件的插件示例。插件实现声明了一个自定义配置，允许使用依赖项坐标分配这些外部依赖项

DataProcessingPlugin.java

public class DataProcessingPlugin implements Plugin<Project> {
    public void apply(Project project) {
        Configuration dataFiles = project.getConfigurations().create("dataFiles", c -> {
            c.setVisible(false);
            c.setCanBeConsumed(false);
            c.setCanBeResolved(true);
            c.setDescription("The data artifacts to be processed for this plugin.");
            c.defaultDependencies(d -> d.add(project.getDependencies().create("org.myorg:data:1.4.6")));
        });

        project.getTasks().withType(DataProcessing.class).configureEach(
            dataProcessing -> dataProcessing.getDataFiles().from(dataFiles));
    }
}

DataProcessing.java

abstract public class DataProcessing extends DefaultTask {

    @InputFiles
    abstract public ConfigurableFileCollection getDataFiles();

    @TaskAction
    public void process() {
        System.out.println(getDataFiles().getFiles());
    }
}

这种方法对最终用户很方便，因为无需主动声明依赖项。插件已经提供了有关此实现的所有详细信息。

但如果用户想要重新定义默认依赖项怎么办？

没问题。插件还公开了自定义配置，可用于分配不同的依赖项。实际上，默认依赖项被覆盖

build.gradle.kts

plugins {
    id("org.myorg.data-processing")
}

dependencies {
    dataFiles("org.myorg:more-data:2.6")
}

build.gradle

plugins {
    id 'org.myorg.data-processing'
}

dependencies {
    dataFiles 'org.myorg:more-data:2.6'
}

您会发现，当在执行任务操作时任务需要外部依赖项时，此模式效果很好。您可以更进一步，通过公开扩展属性（例如JaCoCo 插件中的toolVersion）来抽象要用于外部依赖项的版本。

最大程度减少外部库的使用

在 Gradle 项目中使用外部库可以带来极大的便利，但请注意，它们可能会引入复杂的依赖关系图。Gradle 的 buildEnvironment 任务可以帮助你将这些依赖关系可视化，包括插件的依赖关系。请记住，插件共享相同的类加载器，因此不同版本的同一库可能会出现冲突。

为了进行演示，我们假设以下构建脚本

build.gradle.kts

plugins {
    id("org.asciidoctor.jvm.convert") version "4.0.2"
}

build.gradle

plugins {
    id 'org.asciidoctor.jvm.convert' version '4.0.2'
}

任务的输出清楚地指示了 classpath 配置的类路径

$ gradle buildEnvironment

> Task :buildEnvironment

------------------------------------------------------------
Root project 'external-libraries'
------------------------------------------------------------

classpath
\--- org.asciidoctor.jvm.convert:org.asciidoctor.jvm.convert.gradle.plugin:4.0.2
     \--- org.asciidoctor:asciidoctor-gradle-jvm:4.0.2
          +--- org.ysb33r.gradle:grolifant-rawhide:3.0.0
          |    \--- org.tukaani:xz:1.6
          +--- org.ysb33r.gradle:grolifant-herd:3.0.0
          |    +--- org.tukaani:xz:1.6
          |    +--- org.ysb33r.gradle:grolifant40:3.0.0
          |    |    +--- org.tukaani:xz:1.6
          |    |    +--- org.apache.commons:commons-collections4:4.4
          |    |    +--- org.ysb33r.gradle:grolifant-core:3.0.0
          |    |    |    +--- org.tukaani:xz:1.6
          |    |    |    +--- org.apache.commons:commons-collections4:4.4
          |    |    |    \--- org.ysb33r.gradle:grolifant-rawhide:3.0.0 (*)
          |    |    \--- org.ysb33r.gradle:grolifant-rawhide:3.0.0 (*)
          |    +--- org.ysb33r.gradle:grolifant50:3.0.0
          |    |    +--- org.tukaani:xz:1.6
          |    |    +--- org.ysb33r.gradle:grolifant40:3.0.0 (*)
          |    |    +--- org.ysb33r.gradle:grolifant-core:3.0.0 (*)
          |    |    \--- org.ysb33r.gradle:grolifant40-legacy-api:3.0.0
          |    |         +--- org.tukaani:xz:1.6
          |    |         +--- org.apache.commons:commons-collections4:4.4
          |    |         +--- org.ysb33r.gradle:grolifant-core:3.0.0 (*)
          |    |         \--- org.ysb33r.gradle:grolifant40:3.0.0 (*)
          |    +--- org.ysb33r.gradle:grolifant60:3.0.0
          |    |    +--- org.tukaani:xz:1.6
          |    |    +--- org.ysb33r.gradle:grolifant40:3.0.0 (*)
          |    |    +--- org.ysb33r.gradle:grolifant50:3.0.0 (*)
          |    |    +--- org.ysb33r.gradle:grolifant-core:3.0.0 (*)
          |    |    \--- org.ysb33r.gradle:grolifant-rawhide:3.0.0 (*)
          |    +--- org.ysb33r.gradle:grolifant70:3.0.0
          |    |    +--- org.tukaani:xz:1.6
          |    |    +--- org.ysb33r.gradle:grolifant40:3.0.0 (*)
          |    |    +--- org.ysb33r.gradle:grolifant50:3.0.0 (*)
          |    |    +--- org.ysb33r.gradle:grolifant60:3.0.0 (*)
          |    |    \--- org.ysb33r.gradle:grolifant-core:3.0.0 (*)
          |    +--- org.ysb33r.gradle:grolifant80:3.0.0
          |    |    +--- org.tukaani:xz:1.6
          |    |    +--- org.ysb33r.gradle:grolifant40:3.0.0 (*)
          |    |    +--- org.ysb33r.gradle:grolifant50:3.0.0 (*)
          |    |    +--- org.ysb33r.gradle:grolifant60:3.0.0 (*)
          |    |    +--- org.ysb33r.gradle:grolifant70:3.0.0 (*)
          |    |    \--- org.ysb33r.gradle:grolifant-core:3.0.0 (*)
          |    +--- org.ysb33r.gradle:grolifant-core:3.0.0 (*)
          |    \--- org.ysb33r.gradle:grolifant-rawhide:3.0.0 (*)
          +--- org.asciidoctor:asciidoctor-gradle-base:4.0.2
          |    \--- org.ysb33r.gradle:grolifant-herd:3.0.0 (*)
          \--- org.asciidoctor:asciidoctorj-api:2.5.7

(*) - Indicates repeated occurrences of a transitive dependency subtree. Gradle expands transitive dependency subtrees only once per project; repeat occurrences only display the root of the subtree, followed by this annotation.

A web-based, searchable dependency report is available by adding the --scan option.

BUILD SUCCESSFUL in 0s
1 actionable task: 1 executed

Gradle 插件不会在其自己的隔离类加载器中运行，因此你必须考虑是否真正需要一个库，或者一个更简单的解决方案就足够了。

对于作为任务执行的一部分执行的逻辑，请使用 Worker API，它允许你隔离库。

提供多种插件变体

配置其他插件变体的最便捷方法是使用功能变体，这是所有应用 Java 插件之一的 Gradle 项目中可用的一个概念

dependencies {
    implementation 'com.google.guava:guava:30.1-jre'        // Regular dependency
    featureVariant 'com.google.guava:guava-gwt:30.1-jre'    // Feature variant dependency
}

在以下示例中，每个插件变体都独立开发。一个单独的源集被编译并打包到每个变体的单独 jar 中。

以下示例演示如何添加与 Gradle 7.0+ 兼容的变体，而“main”变体与较旧版本兼容

build.gradle.kts

val gradle7 = sourceSets.create("gradle7")

java {
    registerFeature(gradle7.name) {
        usingSourceSet(gradle7)
        capability(project.group.toString(), project.name, project.version.toString()) (1)
    }
}

configurations.configureEach {
    if (isCanBeConsumed && name.startsWith(gradle7.name))  {
        attributes {
            attribute(GradlePluginApiVersion.GRADLE_PLUGIN_API_VERSION_ATTRIBUTE, (2)
                objects.named("7.0"))
        }
    }
}

tasks.named<Copy>(gradle7.processResourcesTaskName) { (3)
    val copyPluginDescriptors = rootSpec.addChild()
    copyPluginDescriptors.into("META-INF/gradle-plugins")
    copyPluginDescriptors.from(tasks.pluginDescriptors)
}

dependencies {
    "gradle7CompileOnly"(gradleApi()) (4)
}

build.gradle

def gradle7 = sourceSets.create('gradle7')

java {
    registerFeature(gradle7.name) {
        usingSourceSet(gradle7)
        capability(project.group.toString(), project.name, project.version.toString()) (1)
    }
}

configurations.configureEach {
    if (canBeConsumed && name.startsWith(gradle7.name))  {
        attributes {
            attribute(GradlePluginApiVersion.GRADLE_PLUGIN_API_VERSION_ATTRIBUTE, (2)
                      objects.named(GradlePluginApiVersion, '7.0'))
        }
    }
}

tasks.named(gradle7.processResourcesTaskName) { (3)
    def copyPluginDescriptors = rootSpec.addChild()
    copyPluginDescriptors.into('META-INF/gradle-plugins')
    copyPluginDescriptors.from(tasks.pluginDescriptors)
}

dependencies {
    gradle7CompileOnly(gradleApi()) (4)
}

只有 Gradle 版本 7 或更高版本才能被变体明确地指定为目标，因为对它的支持只在 Gradle 7 中添加。

首先，我们为 Gradle7 插件变体声明一个单独的源集和一个功能变体。然后，我们进行一些特定的连接，将功能转换为一个适当的 Gradle 插件变体

1	将隐式功能（对应于组件 GAV）分配给变体。
2	将 Gradle API 版本属性分配给 Gradle7 变体的所有可消耗配置。Gradle 使用此信息来确定在插件解析期间选择哪个变体。
3	配置 `processGradle7Resources` 任务以确保插件描述符文件被添加到 Gradle7 变体 Jar 中。
4	为我们的新变体添加对 `gradleApi()` 的依赖，以便在编译时可以看到 API。

请注意，目前没有便捷的方法可以访问与你用于构建插件的 Gradle 版本不同的其他 Gradle 版本的 API。理想情况下，每个变体都应该能够声明对其支持的最小 Gradle 版本的 API 的依赖关系。这将在未来得到改进。

上述代码段假设你的插件的所有变体在相同的位置具有插件类。也就是说，如果你的插件类为 org.example.GreetingPlugin，你需要在 src/gradle7/java/org/example 中创建该类的第二个变体。

使用多变体插件的特定版本变体

给定对多变体插件的依赖关系，Gradle 将在解析任何以下内容时自动选择与当前 Gradle 版本最匹配的变体

在 plugins {} 块中指定的插件；
buildscript 类路径依赖关系；
出现在编译或运行时类路径上的构建源 (buildSrc) 的根项目中的依赖关系；
出现在编译或运行时类路径上，应用了 Java Gradle 插件开发插件或 Kotlin DSL 插件的项目中的依赖关系。

最匹配的变体是针对最高 Gradle API 版本且不超过当前构建的 Gradle 版本的变体。

在所有其他情况下，如果存在不指定受支持的 Gradle API 版本的插件变体，则首选该变体。

在使用插件作为依赖关系的项目中，可以请求支持不同 Gradle 版本的插件依赖关系的变体。这允许依赖于其他插件的多变体插件访问其 API，而这些 API 仅在其特定版本变体中提供。

此代码段使上面定义的插件变体 gradle7 消耗其对其他多变体插件的依赖关系的匹配变体

build.gradle.kts

configurations.configureEach {
    if (isCanBeResolved && name.startsWith(gradle7.name))  {
        attributes {
            attribute(GradlePluginApiVersion.GRADLE_PLUGIN_API_VERSION_ATTRIBUTE,
                objects.named("7.0"))
        }
    }
}

build.gradle

configurations.configureEach {
    if (canBeResolved && name.startsWith(gradle7.name))  {
        attributes {
            attribute(GradlePluginApiVersion.GRADLE_PLUGIN_API_VERSION_ATTRIBUTE,
                objects.named(GradlePluginApiVersion, '7.0'))
        }
    }
}

报告问题

插件可以通过 Gradle 的问题报告 API 报告问题。这些 API 报告有关构建期间发生的问题的丰富结构化信息。不同的用户界面（例如 Gradle 的控制台输出、构建扫描或 IDE）可以使用此信息以最合适的方式向用户传达问题。

以下示例显示了从插件报告的问题

ProblemReportingPlugin.java

public class ProblemReportingPlugin implements Plugin<Project> {

    private final ProblemReporter problemReporter;

    @Inject
    public ProblemReportingPlugin(Problems problems) { (1)
        this.problemReporter = problems.forNamespace("org.myorg"); (2)
    }

    public void apply(Project project) {
        this.problemReporter.reporting(builder -> builder (3)
            .label("Plugin 'x' is deprecated")
            .details("The plugin 'x' is deprecated since version 2.5")
            .solution("Please use plugin 'y'")
            .severity(Severity.WARNING)
        );
    }
}

1	`Problem` 服务被注入到插件中。
2	为插件创建问题报告器。虽然命名空间由插件作者决定，但建议使用插件 ID。
3	报告问题。此问题可恢复，以便继续构建。

有关完整示例，请参阅我们的端到端示例。

构建问题

报告问题时，可以提供各种信息。ProblemSpec 描述了可以提供的所有信息。

报告问题

在报告问题时，我们支持三种不同的模式

报告问题用于报告可恢复的问题，并且构建应继续。
抛出问题用于报告不可恢复的问题，并且构建应失败。
重新抛出问题用于包装已抛出的异常。否则，行为与Throwing相同。

有关更多详细信息，请参阅ProblemReporter文档。

问题聚合

报告问题时，Gradle 会根据问题的类别标签通过 Tooling API 发送类似问题来聚合这些问题。

报告问题时，第一个出现的问题将作为ProblemDescriptor进行报告，其中包含有关该问题的完整信息。
相同问题的任何后续出现都将作为ProblemAggregationDescriptor进行报告。此描述符将出现在构建的末尾，并包含该问题的出现次数。
如果对于任何存储段（即类别和标签配对），收集到的出现次数大于 10.000，则它将立即发送，而不是在构建结束时发送。

此页面有帮助吗？