跳到主要内容

Elasticsearch 客户端

DeepSeek V3 中英对照 Elasticsearch Clients

本章将介绍支持的 Elasticsearch 客户端实现的配置和使用方法。

Spring Data Elasticsearch 操作于一个连接到单个 Elasticsearch 节点或集群的 Elasticsearch 客户端（由 Elasticsearch 客户端库提供）。尽管可以直接使用 Elasticsearch 客户端来操作集群，但使用 Spring Data Elasticsearch 的应用程序通常使用更高层次的抽象，如 Elasticsearch Operations 和 Elasticsearch Repositories。

命令式 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();
	}
}
java

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
java

  • ElasticsearchOperations 的一个实现

  • 使用的 co.elastic.clients.elasticsearch.ElasticsearchClient

  • 来自 Elasticsearch 库的低级别 RestClient

  • Elasticsearch Transport 使用的 JsonpMapper

基本上，应该使用 ElasticsearchOperations 来与 Elasticsearch 集群进行交互。在使用仓库（repositories）时，这个实例也会在底层被使用。

响应式 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();
	}
}
java

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

然后可以将以下 bean 注入到其他 Spring 组件中：

@Autowired
ReactiveElasticsearchOperations operations;      1

@Autowired
ReactiveElasticsearchClient elasticsearchClient; 2

@Autowired
RestClient restClient;                           3

@Autowired
JsonpMapper jsonpMapper;                         4
java

以下内容可以被注入：

  • ReactiveElasticsearchOperations 的一个实现

  • 使用的 org.springframework.data.elasticsearch.client.elc.ReactiveElasticsearchClient。这是一个基于 Elasticsearch 客户端实现的反响应式实现。

  • 来自 Elasticsearch 库的低层 RestClient

  • Elasticsearch Transport 使用的 JsonpMapper

基本上，应该使用 ReactiveElasticsearchOperations 来与 Elasticsearch 集群进行交互。在使用存储库时，底层也会使用这个实例。

客户端配置​

客户端行为可以通过 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();
java

  • 定义默认的头部信息，如果需要自定义

  • 使用构建器提供集群地址，设置默认的 HttpHeaders 或启用 SSL。

  • 可选地启用 SSL。此函数存在重载版本，可以接受 SSLContext 或作为替代方案，接受 Elasticsearch 8 启动时输出的证书指纹。

  • 可选地设置代理。

  • 可选地设置路径前缀，主要用于当不同的集群位于某些反向代理之后时。

  • 设置连接超时时间。

  • 设置套接字超时时间。

  • 可选地设置头部信息。

  • 添加基本认证。

  • 可以指定一个 Supplier<HttpHeaders> 函数，该函数在每次发送请求到 Elasticsearch 之前被调用——这里作为一个例子，当前时间被写入一个头部信息中。

  • 一个用于配置创建的客户端的函数（参见 客户端配置回调），可以多次添加。

important

如上例所示，添加一个 Header 供应商允许注入可能随时间变化的头部信息，例如身份验证的 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();
java

配置低级别 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();
java

客户端日志​

要查看实际发送到服务器和从服务器接收的内容，需要按照以下代码片段中所述开启传输级别的 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"/>
xml