Reactive Infrastructure

本部分涵盖使用 Spring Vault 的响应式编程支持的基本信息。

This section covers basic information on the reactive programming support using Spring Vault.

What is Reactive Programming?

简单地说，响应式编程是关于非阻塞应用程序的，这些应用程序是异步的、事件驱动的，并且需要少量的线程才能垂直扩展（例如在 JVM 内），而不是水平扩展（例如通过集群）。

In plain terms reactive programming is about non-blocking applications that are asynchronous and event-driven and require a small number of threads to scale vertically (i.e. within the JVM) rather than horizontally (i.e. through clustering).

反应式应用程序的一个关键方面是背压的概念，这是一个机制，以确保生产者不会压垮消费者。例如，当 HTTP 连接太慢时，从数据库延伸到 HTTP 响应的反应式组件管道中的数据仓库也可以减慢速度或完全停止，直到网络容量释放出来。

A key aspect of reactive applications is the concept of backpressure which is a mechanism to ensure producers don’t overwhelm consumers. For example in a pipeline of reactive components extending from the database to the HTTP response when the HTTP connection is too slow the data repository can also slow down or stop completely until network capacity frees up.

Reactive Vault Client

Spring Vault 的反应式客户端支持构建在 composable authentication steps 和 Spring 的函数式 WebClient 之上，通过 Reactor Netty 或 Jetty，它们都具有完全非阻塞的事件驱动的 HTTP 客户端。

Spring Vault’s reactive client support is built on top of vault.authentication.steps and Spring’s functional WebClient via Reactor Netty or Jetty, which feature both a fully non-blocking, event-driven HTTP client.

它公开 VaultTokenSupplier 作为 VaultToken 的供应商以验证 HTTP 请求，并公开 ReactiveVaultOperations 作为主要入口点。VaultEndpoint、ClientOptions 和 SSL 的核心配置在各种客户端实现中重复使用。

It exposes VaultTokenSupplier as supplier of VaultToken to authenticate HTTP requests and ReactiveVaultOperations as the primary entry point. The core configuration of VaultEndpoint, ClientOptions and vault.client-ssl are reused across the various client implementation.

类 ReactiveVaultTemplate，位于包 org.springframework.vault.core 中，是 Spring 反应式 Vault 支持的中心类，提供了一组丰富特性来与 Vault 交互。模板提供了读取、写入和删除 Vault 中数据的便利操作，并在域对象和 Vault 数据之间提供映射。

The class ReactiveVaultTemplate, located in the package org.springframework.vault.core, is the central class of the Spring’s reactive Vault support providing a rich feature set to interact with Vault. The template offers convenience operations to read, write and delete data in Vault and provides a mapping between your domain objects and Vault data.

配置后，ReactiveVaultTemplate 是线程安全的，并且可以在多个实例中重复使用。

Once configured, ReactiveVaultTemplate is thread-safe and can be reused across multiple instances.

Vault 文档和域类之间的映射是通过委派到 WebClient 及其编解码器来完成的。

The mapping between Vault documents and domain classes is done by delegating to WebClient and its codecs.

ReactiveVaultTemplate 类实现了 ReactiveVaultOperations 接口。尽可能地，ReactiveVaultOperations 上的方法以 Vault API 上的方法命名，使得 API 对习惯于使用 API 和 CLI 的现有 Vault 开发者来说很熟悉。例如，你会找到诸如“write”、“delete”和“read”这样的方法。设计目标是尽可能轻松地在 Vault API 和 ReactiveVaultOperations 之间进行转换。两个 API 之间的一个主要区别是 ReactiveVaultOperations 可以传递域对象而不是 JSON 键值对。

The ReactiveVaultTemplate class implements the interface ReactiveVaultOperations. In as much as possible, the methods on ReactiveVaultOperations are named after methods available on the Vault API to make the API familiar to existing Vault developers who are used to the API and CLI. For example, you will find methods such as "write", "delete", and "read". The design goal was to make it as easy as possible to transition between the use of the Vault API and ReactiveVaultOperations. A major difference in between the two APIs is that ReactiveVaultOperations can be passed domain objects instead of JSON Key-Value pairs.

引用 ReactiveVaultTemplate 实例上操作的首选方式是通过其界面 ReactiveVaultOperations。

The preferred way to reference the operations on ReactiveVaultTemplate instance is via its interface ReactiveVaultOperations.

ReactiveVaultTemplate 中明确未公开的功能，你可以使用几个 execute 回调方法之一来访问底层 API。execute 回调将为你提供对 WebClient 对象的引用。请参阅 Execution Callbacks 部分以了解更多信息。

Functionality not explicitly exposed by the ReactiveVaultTemplate you can use one of several execute callback methods to access underlying APIs. The execute callbacks will give you a reference to a WebClient object. Please see the section vault.core.reactive.executioncallback for more information.

现在，让我们来看一个示例，了解如何在 Spring 容器的上下文中使用 Vault。

Now let’s look at a examples of how to work with Vault in the context of the Spring container.

Registering and configuring Spring Vault beans

使用 Spring Vault 不需要 Spring 上下文。但是，在受管上下文中注册的 ReactiveVaultTemplate 和 VaultTokenSupplier 的实例将参与 Spring IoC 容器提供的 {spring-framework-docs}core.html#beans-factory-nature[生命周期事件]。这有助于在应用程序关闭时释放活动 Vault 会话。您还可以受益于在整个应用程序中重复使用相同的 ReactiveVaultTemplate 实例。

Using Spring Vault does not require a Spring Context. However, instances of ReactiveVaultTemplate and VaultTokenSupplier registered inside a managed context will participate in {spring-framework-docs}core.html#beans-factory-nature[lifecycle events] provided by the Spring IoC container. This is useful to dispose active Vault sessions upon application shutdown. You also benefit from reusing the same ReactiveVaultTemplate instance across your application.

Spring Vault 带有一个支持配置类，该类提供了在 Spring 上下文中使用的 bean 定义。应用程序配置类通常从 AbstractVaultConfiguration 扩展，并且需要提供特定于环境的附加详细信息。

Spring Vault comes with a supporting configuration class that provides bean definitions for use inside a Spring context. Application configuration classes typically extend from AbstractVaultConfiguration and are required to provide additional details that are environment specific.

从 AbstractVaultConfiguration 扩展需要实现` VaultEndpoint vaultEndpoint()` 和 ClientAuthentication clientAuthentication() 方法。

Extending from AbstractVaultConfiguration requires to implement ` VaultEndpoint vaultEndpoint()` and ClientAuthentication clientAuthentication() methods.

Example 1. Registering Spring Vault objects using Java based bean metadata
@Configuration
public class AppConfig extends AbstractReactiveVaultConfiguration {

    /**
     * Specify an endpoint for connecting to Vault.
     */
    @Override
    public VaultEndpoint vaultEndpoint() {
        return new VaultEndpoint();                            1
    }

    /**
     * Configure a client authentication.
     * Please consider a more secure authentication method
     * for production use.
     */
    @Override
    public ClientAuthentication clientAuthentication() {
        return new TokenAuthentication("…");                   2
    }
}
1 Create a new VaultEndpoint that points by default to https://localhost:8200.
2 This sample uses TokenAuthentication to get started quickly. See [vault.core.authentication] for details on supported authentication methods.

Session Management

Spring Vault 需要一个令牌来验证 Vault 请求。请参阅 [vault.core.authentication] 中关于验证的详细信息。反应式客户端需要一个非阻塞的令牌供应商，其协定在 VaultTokenSupplier 中定义。令牌可以是静态的，也可以通过 declared authentication flow 获得。Vault 登录不应该发生在每次验证的 Vault 交互中，但会话令牌应该在会话中保持。这个方面是由实现 ReactiveSessionManager（如 ReactiveLifecycleAwareSessionManager）的会话管理器处理的。

Spring Vault requires a token to authenticate Vault requests. See [vault.core.authentication] on details regarding authentication. The reactive client requires a non-blocking token supplier whose contract is defined in VaultTokenSupplier. Tokens can be static or obtained through a vault.authentication.steps. Vault login should not occur on each authenticated Vault interaction but the session token should be kept across a session. This aspect is handled by a session manager implementing ReactiveSessionManager, such as ReactiveLifecycleAwareSessionManager.

Execution callbacks

所有 Spring 模板类的一个共同设计特性是，所有功能都被路由到其中一个模板 execute 回调方法。这有助于确保执行所需的异常和任何资源管理都保持一致。虽然在 JDBC 和 JMS 的情况下比在 Vault 中更需要这样，但它仍然提供了一个访问和记录发生的地方。因此，使用 execute 回调是访问 Vault API 以执行我们尚未 ReactiveVaultTemplate 上的方法公开的非常用操作的首选方法。

One common design feature of all Spring template classes is that all functionality is routed into one of the templates execute callback methods. This helps ensure that exceptions and any resource management that maybe required are performed consistency. While this was of much greater need in the case of JDBC and JMS than with Vault, it still offers a single spot for access and logging to occur. As such, using the execute callback is the preferred way to access the Vault API to perform uncommon operations that we’ve not exposed as methods on ReactiveVaultTemplate.

这里列出了一些 execute 回调方法。

Here is a list of execute callback methods.

  • <T> T doWithVault (Function<WebClient, ? extends T> clientCallback) Composes a reactive sequence the given WebClient, allows to interact with Vault without a session context.

  • <T> T doWithSession (Function<WebClient, ? extends T> clientCallback) Composes a reactive sequence the given WebClient, allows to interact with Vault in an authenticated session.

这里有一个使用回调初始化 Vault 的示例：

Here is an example that uses the callback to initialize Vault:

reactiveVaultOperations.doWithVault(webClient -> {

    return webClient.put()
                    .uri("/sys/init")
                    .syncBody(request)
                    .retrieve()
                    .toEntity(VaultInitializationResponse.class);
});