Elasticsearch 客户端

本章阐述了支持的 Elasticsearch 客户端实现的配置和用法。

Spring Data Elasticsearch 基于连接到单个 Elasticsearch 节点或集群的 Elasticsearch 客户端（由 Elasticsearch 客户端库提供）运行。虽然可以直接使用 Elasticsearch 客户端与集群交互，但使用 Spring Data Elasticsearch 的应用程序通常使用更高级别的抽象，即 Elasticsearch 操作和 Elasticsearch Repository。

命令式 Rest 客户端

要使用命令式（非响应式）客户端，必须按如下方式配置一个配置 Bean

import org.springframework.data.elasticsearch.client.elc.ElasticsearchConfiguration;

@Configuration
public class MyClientConfig extends ElasticsearchConfiguration {

	@Override
	public ClientConfiguration clientConfiguration() {
		return ClientConfiguration.builder()           (1)
			.connectedTo("localhost:9200")
			.build();
	}
}

1	有关构建器方法的详细说明，请参阅客户端配置

ElasticsearchConfiguration] 类允许通过覆盖例如 jsonpMapper() 或 transportOptions() 方法进行进一步配置。

以下 Bean 可以注入到其他 Spring 组件中

import org.springframework.beans.factory.annotation.Autowired;@Autowired
ElasticsearchOperations operations;      (1)

@Autowired
ElasticsearchClient elasticsearchClient; (2)

@Autowired
RestClient restClient;                   (3)

@Autowired
JsonpMapper jsonpMapper;                 (4)

1	`ElasticsearchOperations` 的实现
2	所使用的 `co.elastic.clients.elasticsearch.ElasticsearchClient`。
3	来自 Elasticsearch 库的低级别 `RestClient`
4	Elasticsearch `Transport` 使用的 `JsonpMapper`

基本上，应该只使用 ElasticsearchOperations 与 Elasticsearch 集群交互。使用 Repository 时，底层也使用这个实例。

响应式 Rest 客户端

在使用响应式栈时，配置必须派生自不同的类

import org.springframework.data.elasticsearch.client.elc.ReactiveElasticsearchConfiguration;

@Configuration
public class MyClientConfig extends ReactiveElasticsearchConfiguration {

	@Override
	public ClientConfiguration clientConfiguration() {
		return ClientConfiguration.builder()           (1)
			.connectedTo("localhost:9200")
			.build();
	}
}

1	有关构建器方法的详细说明，请参阅客户端配置

ReactiveElasticsearchConfiguration 类允许通过覆盖例如 jsonpMapper() 或 transportOptions() 方法进行进一步配置。

以下 Bean 可以注入到其他 Spring 组件中

@Autowired
ReactiveElasticsearchOperations operations;      (1)

@Autowired
ReactiveElasticsearchClient elasticsearchClient; (2)

@Autowired
RestClient restClient;                           (3)

@Autowired
JsonpMapper jsonpMapper;                         (4)

以下可以注入

1	`ReactiveElasticsearchOperations` 的实现
2	所使用的 `org.springframework.data.elasticsearch.client.elc.ReactiveElasticsearchClient`。这是一个基于 Elasticsearch 客户端实现的响应式实现。
3	来自 Elasticsearch 库的低级别 `RestClient`
4	Elasticsearch `Transport` 使用的 `JsonpMapper`

基本上，应该只使用 ReactiveElasticsearchOperations 与 Elasticsearch 集群交互。使用 Repository 时，底层也使用这个实例。

客户端配置

客户端行为可以通过 ClientConfiguration 进行更改，它允许设置 SSL、连接和套接字超时、请求头以及其他参数。

示例 1. 客户端配置

import org.springframework.data.elasticsearch.client.ClientConfiguration;
import org.springframework.data.elasticsearch.support.HttpHeaders;

import static org.springframework.data.elasticsearch.client.elc.ElasticsearchClients.*;

HttpHeaders httpHeaders = new HttpHeaders();
httpHeaders.add("some-header", "on every request")                      (1)

ClientConfiguration clientConfiguration = ClientConfiguration.builder()
  .connectedTo("localhost:9200", "localhost:9291")                      (2)
  .usingSsl()                                                           (3)
  .withProxy("localhost:8888")                                          (4)
  .withPathPrefix("ela")                                                (5)
  .withConnectTimeout(Duration.ofSeconds(5))                            (6)
  .withSocketTimeout(Duration.ofSeconds(3))                             (7)
  .withDefaultHeaders(defaultHeaders)                                   (8)
  .withBasicAuth(username, password)                                    (9)
  .withHeaders(() -> {                                                  (10)
    HttpHeaders headers = new HttpHeaders();
    headers.add("currentTime", LocalDateTime.now().format(DateTimeFormatter.ISO_LOCAL_DATE_TIME));
    return headers;
  })
  .withClientConfigurer(                                                (11)
    ElasticsearchHttpClientConfigurationCallback.from(clientBuilder -> {
  	  // ...
      return clientBuilder;
  	}))
  . // ... other options
  .build();

1	定义默认请求头，如果需要自定义
2	使用构建器提供集群地址，设置默认 `HttpHeaders` 或启用 SSL。
3	可选地启用 SSL。此函数存在可以接受 `SSLContext` 的重载，或者作为替代，接受 Elasticsearch 8 启动时输出的证书指纹。
4	可选地设置代理。
5	可选地设置路径前缀，主要用于不同集群位于反向代理后方的情况。
6	设置连接超时。
7	设置套接字超时。
8	可选地设置请求头。
9	添加基本认证。
10	可以指定一个 `Supplier<HttpHeaders>` 函数，该函数在每次请求发送到 Elasticsearch 之前被调用 - 这里，举例来说，当前时间被写入到请求头中。
11	配置创建的客户端的函数（参见客户端配置回调），可以添加多次。

如上例所示添加请求头供应商允许注入可能随时间变化的请求头，例如身份验证 JWT 令牌。如果这用于响应式设置中，则供应商函数不得阻塞！

客户端配置回调

ClientConfiguration 类提供了最常见的参数来配置客户端。如果这些不够，用户可以使用 withClientConfigurer(ClientConfigurationCallback<?>) 方法添加回调函数。

提供了以下回调

低级别 Elasticsearch `RestClient` 的配置

此回调提供了一个 org.elasticsearch.client.RestClientBuilder，可用于配置 Elasticsearch RestClient

ClientConfiguration.builder()
    .connectedTo("localhost:9200", "localhost:9291")
    .withClientConfigurer(ElasticsearchClients.ElasticsearchRestClientConfigurationCallback.from(restClientBuilder -> {
        // configure the Elasticsearch RestClient
        return restClientBuilder;
    }))
    .build();

低级别 Elasticsearch `RestClient` 使用的 HttpAsyncClient 的配置

此回调提供了一个 org.apache.http.impl.nio.client.HttpAsyncClientBuilder，用于配置 RestClient 使用的 HttpClient。

ClientConfiguration.builder()
    .connectedTo("localhost:9200", "localhost:9291")
    .withClientConfigurer(ElasticsearchClients.ElasticsearchHttpClientConfigurationCallback.from(httpAsyncClientBuilder -> {
        // configure the HttpAsyncClient
        return httpAsyncClientBuilder;
    }))
    .build();

客户端日志记录

要查看实际发送到服务器以及从服务器接收到的内容，需要在传输层启用 Request / Response 日志记录，如下所示。这可以在 Elasticsearch 客户端中通过将 tracer 包的级别设置为 "trace" 来启用（参见 www.elastic.co/guide/en/elasticsearch/client/java-api-client/current/java-rest-low-usage-logging.html）

启用传输层日志记录

<logger name="tracer" level="trace"/>