共享构建服务 - Gradle 中文

有时，多个任务共享某些状态或资源非常有用。例如，任务可能共享预先计算的值的缓存，以便更快地完成工作。或者，任务可能使用 Web 服务或数据库实例来完成工作。

Gradle 允许你声明构建服务来表示此状态。构建服务只是一个保存任务要使用状态的对象。Gradle 负责服务生命周期，并且只会在需要时创建服务实例，并在不再需要时清理该实例。Gradle 还可以选择负责协调对构建服务的访问，以便不会超过指定数量的任务同时使用该服务。

实现构建服务

要实现构建服务，请创建一个实现 BuildService 的抽象类。在此类型上定义你希望任务使用的方法。构建服务实现被视为自定义 Gradle 类型，并且可以使用自定义 Gradle 类型可用的任何功能。

构建服务可以选择采用参数，Gradle 在创建服务实例时将其注入服务实例。要提供参数，请定义一个包含参数的抽象类（或接口）。参数类型必须实现（或扩展）BuildServiceParameters。服务实现可以使用 this.getParameters() 访问参数。参数类型也是自定义 Gradle 类型。

当构建服务不需要任何参数时，可以使用 BuildServiceParameters.None 作为参数类型。

构建服务实现还可以选择实现 AutoCloseable，在这种情况下，Gradle 会在丢弃服务实例时调用构建服务实例的 close() 方法。这发生在使用构建服务的最后一个任务完成与构建结束之间的时间内。

下面是一个采用参数且可关闭的服务示例

示例 1. 实现构建服务

WebServer.java

import org.gradle.api.file.DirectoryProperty;
import org.gradle.api.provider.Property;
import org.gradle.api.services.BuildService;
import org.gradle.api.services.BuildServiceParameters;

import java.net.URI;
import java.net.URISyntaxException;

public abstract class WebServer implements BuildService<WebServer.Params>, AutoCloseable {

    // Some parameters for the web server
    interface Params extends BuildServiceParameters {
        Property<Integer> getPort();

        DirectoryProperty getResources();
    }

    private final URI uri;

    public WebServer() throws URISyntaxException {
        // Use the parameters
        int port = getParameters().getPort().get();
        uri = new URI(String.format("https://localhost:%d/", port));

        // Start the server ...

        System.out.println(String.format("Server is running at %s", uri));
    }

    // A public method for tasks to use
    public URI getUri() {
        return uri;
    }

    @Override
    public void close() {
        // Stop the server ...
    }
}

请注意，不要实现 BuildService.getParameters() 方法，因为 Gradle 会提供此方法的实现。

构建服务实现必须是线程安全的，因为它可能会被多个任务同时使用。

从任务使用构建服务

要从任务使用构建服务，需要

向任务添加一个类型为 Property<MyServiceType> 的属性。
使用 @Internal 或 @ServiceReference（8.0 版起）为属性添加注释。
将共享构建服务提供程序分配给属性（可选，当使用 @ServiceReference(<serviceName>) 时）。
声明任务与服务之间的关联，以便 Gradle 能够正确遵守构建服务生命周期及其使用约束（可选，当使用 @ServiceReference 时）。

请注意，目前不支持使用任何其他注释来使用服务。例如，当前无法将服务标记为任务的输入。

使用 `@Internal` 为共享构建服务属性添加注释

使用 @Internal 为共享构建服务属性添加注释时，还需要执行以下两项操作

在使用 BuildServiceRegistry.registerIfAbsent() 注册服务时，明确分配获取到的构建服务提供程序到属性。
通过 Task.usesService 明确声明任务和服务之间的关联。

以下是一个通过使用带有 @Internal 注释的属性来使用上一个服务的任务示例

示例 2. 使用明确分配的构建服务

Download.java

import org.gradle.api.DefaultTask;
import org.gradle.api.file.RegularFileProperty;
import org.gradle.api.provider.Property;
import org.gradle.api.tasks.Internal;
import org.gradle.api.tasks.OutputFile;
import org.gradle.api.tasks.TaskAction;

import java.net.URI;

public abstract class Download extends DefaultTask {
    // This property provides access to the service instance
    @Internal
    abstract Property<WebServer> getServer();

    @OutputFile
    abstract RegularFileProperty getOutputFile();

    @TaskAction
    public void download() {
        // Use the server to download a file
        WebServer server = getServer().get();
        URI uri = server.getUri().resolve("somefile.zip");
        System.out.println(String.format("Downloading %s", uri));
    }
}

使用 `@ServiceReference` 注释共享构建服务属性

@ServiceReference 注释是一个孵化 API，并且可能会在将来的版本中发生更改。

否则，当您使用 @ServiceReference 注释共享构建服务属性时，无需明确声明任务和服务之间的关联；此外，如果您为注释提供服务名称，并且使用该名称注册了共享构建服务，那么在创建任务时，该服务将自动分配给该属性。

以下是一个通过使用带有 @ServiceReference 注释的属性来使用上一个服务的任务示例

示例 3. 使用自动分配的构建服务

Download.java

import org.gradle.api.DefaultTask;
import org.gradle.api.file.RegularFileProperty;
import org.gradle.api.provider.Property;
import org.gradle.api.services.ServiceReference;
import org.gradle.api.tasks.OutputFile;
import org.gradle.api.tasks.TaskAction;

import java.net.URI;

public abstract class Download extends DefaultTask {
    // This property provides access to the service instance
    @ServiceReference("web")
    abstract Property<WebServer> getServer();

    @OutputFile
    abstract RegularFileProperty getOutputFile();

    @TaskAction
    public void download() {
        // Use the server to download a file
        WebServer server = getServer().get();
        URI uri = server.getUri().resolve("somefile.zip");
        System.out.println(String.format("Downloading %s", uri));
    }
}

注册构建服务并将其连接到任务

要创建构建服务，请使用 BuildServiceRegistry.registerIfAbsent() 方法注册服务实例。注册服务不会创建服务实例。当任务首次使用服务时，会按需进行此操作。如果在构建期间没有任务使用服务，则不会创建服务实例。

目前，构建服务的作用域是构建，而不是项目，并且这些服务可供所有项目的任务共享。您可以通过 Project.getGradle().getSharedServices() 访问共享构建服务的注册表。

以下是一个插件示例，当使用 @Internal 注释任务属性时，该插件会注册之前的服务

示例 4. 当使用 @Internal 注释任务属性时，构建服务注册

DownloadPlugin.java

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

public class DownloadPlugin implements Plugin<Project> {
    public void apply(Project project) {
        // Register the service
        Provider<WebServer> serviceProvider = project.getGradle().getSharedServices().registerIfAbsent("web", WebServer.class, spec -> {
            // Provide some parameters
            spec.getParameters().getPort().set(5005);
        });

        project.getTasks().register("download", Download.class, task -> {
            // Connect the service provider to the task
            task.getServer().set(serviceProvider);
            // Declare the association between the task and the service
            task.usesService(serviceProvider);
            task.getOutputFile().set(project.getLayout().getBuildDirectory().file("result.zip"));
        });
    }
}

该插件注册服务并接收回一个 Provider<WebService>。此提供程序可以连接到任务属性，以将服务传递给任务。请注意，对于使用 @Internal 注释的任务属性，任务属性需要 (1) 使用注册期间获得的提供程序显式分配，并且 (2) 您必须通过 Task.usesService 告知 Gradle 任务使用该服务。

将此与使用 @ServiceReference 注释任务属性时进行比较

示例 5. 当使用 @ServiceReference 注释任务属性时，构建服务注册

DownloadPlugin.java

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

public class DownloadPlugin implements Plugin<Project> {
    public void apply(Project project) {
        // Register the service
        project.getGradle().getSharedServices().registerIfAbsent("web", WebServer.class, spec -> {
            // Provide some parameters
            spec.getParameters().getPort().set(5005);
        });

        project.getTasks().register("download", Download.class, task -> {
            task.getOutputFile().set(project.getLayout().getBuildDirectory().file("result.zip"));
        });
    }
}

如您所见，无需将构建服务提供程序分配给任务，也无需显式声明任务使用该服务。

从配置操作中使用共享构建服务

通常，构建服务旨在供任务使用，因为它们通常表示一些可能创建成本很高的状态，并且您应避免在配置时使用它们。但是，有时在配置时使用服务是有意义的。这是可能的，只需对提供程序调用 get()。

使用构建服务的其他方法

除了从任务中使用构建服务外，您还可以从工作器 API 操作、制品转换或其他构建服务中使用构建服务。为此，请将构建服务 Provider 作为使用操作或服务的参数传递，就像将其他参数传递给操作或服务一样。

例如，要将 MyServiceType 服务传递给工作器 API 操作，可以向操作的参数对象添加一个类型为 Property<MyServiceType> 的属性，然后将注册服务时收到的 Provider<MyServiceType> 连接到此属性。

示例 6. 从工作器操作构建服务使用情况

Download.java

import org.gradle.api.DefaultTask;
import org.gradle.api.provider.Property;
import org.gradle.api.services.ServiceReference;
import org.gradle.api.tasks.TaskAction;
import org.gradle.workers.WorkAction;
import org.gradle.workers.WorkParameters;
import org.gradle.workers.WorkQueue;
import org.gradle.workers.WorkerExecutor;

import javax.inject.Inject;
import java.net.URI;

public abstract class Download extends DefaultTask {

    public static abstract class DownloadWorkAction implements WorkAction<DownloadWorkAction.Parameters> {
        interface Parameters extends WorkParameters {
            // This property provides access to the service instance from the work action
            abstract Property<WebServer> getServer();
        }

        @Override
        public void execute() {
            // Use the server to download a file
            WebServer server = getParameters().getServer().get();
            URI uri = server.getUri().resolve("somefile.zip");
            System.out.println(String.format("Downloading %s", uri));
        }
    }

    @Inject
    abstract public WorkerExecutor getWorkerExecutor();

    // This property provides access to the service instance from the task
    @ServiceReference("web")
    abstract Property<WebServer> getServer();

    @TaskAction
    public void download() {
        WorkQueue workQueue = getWorkerExecutor().noIsolation();
        workQueue.submit(DownloadWorkAction.class, parameter -> {
            parameter.getServer().set(getServer());
        });
    }
}

目前，无法将构建服务与使用 ClassLoader 或进程隔离模式的工作器 API 操作结合使用。

并发访问服务

使用 BuildServiceSpec.getMaxParallelUsages() 返回的 Property 对象，可以在注册服务时约束并发执行。当此属性没有值（这是默认值）时，Gradle 不会约束对服务的访问。当此属性的值 > 0 时，Gradle 将允许不超过指定数量的任务并发使用服务。

当使用 @Internal 注释使用任务属性时，为了使约束生效，必须通过 Task.usesService(Provider<? extends BuildService<?>>) 向使用任务注册构建服务。如果使用 @ServiceReference 注释使用属性，则不必这样做。

接收有关任务执行的信息

构建服务可用于在执行任务时接收事件。为此，创建并注册一个实现 OperationCompletionListener 的构建服务

示例 7. 实现 OperationCompletionListener 的构建服务

TaskEventsService.java

import org.gradle.api.services.BuildService;
import org.gradle.api.services.BuildServiceParameters;
import org.gradle.tooling.events.FinishEvent;
import org.gradle.tooling.events.OperationCompletionListener;
import org.gradle.tooling.events.task.TaskFinishEvent;

public abstract class TaskEventsService implements BuildService<BuildServiceParameters.None>,
    OperationCompletionListener { (1)

    @Override
    public void onFinish(FinishEvent finishEvent) {
        if (finishEvent instanceof TaskFinishEvent) { (2)
            // Handle task finish event...
        }
    }
}

1	除了 `BuildService` 接口之外，还实现 `OperationCompletionListener` 接口。
2	检查完成事件是否是 TaskFinishEvent。

然后，在插件中可以使用 BuildEventsListenerRegistry 服务上的方法开始接收事件

示例 8. 在 BuildEventsListenerRegistry 中注册 BuildService

TaskEventsPlugin.java

import org.gradle.api.Plugin;
import org.gradle.api.Project;
import org.gradle.api.provider.Provider;
import org.gradle.build.event.BuildEventsListenerRegistry;

import javax.inject.Inject;

public abstract class TaskEventsPlugin implements Plugin<Project> {
    @Inject
    public abstract BuildEventsListenerRegistry getEventsListenerRegistry(); (1)

    @Override
    public void apply(Project project) {
        Provider<TaskEventsService> serviceProvider =
            project.getGradle().getSharedServices().registerIfAbsent(
                "taskEvents", TaskEventsService.class, spec -> {}); (2)

        getEventsListenerRegistry().onTaskCompletion(serviceProvider); (3)
    }
}

1	使用服务注入获取 `BuildEventsListenerRegistry` 实例。
2	像往常一样注册构建服务。
3	使用服务 `Provider` 将构建服务订阅到构建事件。

此页面有帮助吗？