Upgrading from 4.3.x to 4.4.x

  • 弃用的 org.springframework.data.elasticsearch.core.ReactiveElasticsearchOperations 方法 execute 已被删除。

  • 已弃用的 org.springframework.data.elasticsearch.core.ElasticsearchTemplate 类已删除，因为它依赖于现已弃用的 Elasticsearch TransportClient。

  • ReactiveElasticsearchTemplate 的默认刷新策略已更改为 NONE，以解决繁重索引上的性能问题。

  • 虽然 Elasticsearch 已引入新的 ElasticsearchClient 来取代 RestHighLevelClient，但 Spring Data Elasticsearch 仍继续使用旧客户端作为默认客户端。

  • 提供了使用新客户端的说明，但尚不建议在生产代码中使用。

本部分介绍了从 4.3.x 版到 4.4.x 版的重大变更，以及已删除的功能如何被新引入的功能替换。

This section describes breaking changes from version 4.3.x to 4.4.x and how removed features can be replaced by new introduced features.

Deprecations

org.springframework.data.elasticsearch.core.ReactiveElasticsearchOperations

方法 <T> Publisher<T> execute(ClientCallback<Publisher<T>> callback) 已弃用。由于现在有多个实现使用不同的客户端库，因此 execute 方法仍然在不同的实现中可用，但接口中不再有该方法，因为不同的客户端没有通用的回调接口。

The method <T> Publisher<T> execute(ClientCallback<Publisher<T>> callback) has been deprecated. As there now are multiple implementations using different client libraries the execute method is still available in the different implementations, but there is no more method in the interface, because there is no common callback interface for the different clients.

Breaking Changes

Removal of deprecated classes

org.springframework.data.elasticsearch.core.ElasticsearchTemplate has been removed

从 4.4 版开始，Spring Data Elasticsearch 不再使用 Elasticsearch 的 TransportClient（从 Elasticsearch 7.0 版开始它本身已被弃用）。这意味着已从 Spring Data Elasticsearch 4.0 版开始弃用的 org.springframework.data.elasticsearch.core.ElasticsearchTemplate 类也已删除。这是使用 TransportClient 的 ElasticsearchOperations 接口的实现。必须使用命令式的 ElasticsearchRestTemplate 或反应式的 ReactiveElasticsearchTemplate 来连接 Elasticsearch。

As of version 4.4 Spring Data Elasticsearch does not use the TransportClient from Elasticsearch anymore (which itself is deprecated since Elasticsearch 7.0). This means that the org.springframework.data.elasticsearch.core.ElasticsearchTemplate class which was deprecated since Spring Data Elasticsearch 4.0 has been removed. This was the implementation of the ElasticsearchOperations interface that was using the TransportClient. Connections to Elasticsearch must be made using either the imperative ElasticsearchRestTemplate or the reactive ReactiveElasticsearchTemplate.

Package changes

在 4.3 版中，两个类（ElasticsearchAggregations 和 ElasticsearchAggregation）已被移动到 org.springframework.data.elasticsearch.core.clients.elasticsearch7 包中，以便集成新的 Elasticsearch 客户端。我们已将它们移回 org.springframework.data.elasticsearch.core 包中，因为我们继续在这些类中使用旧 Elasticsearch 客户端。

In 4.3 two classes (ElasticsearchAggregations and ElasticsearchAggregation) had been moved to the org.springframework.data.elasticsearch.core.clients.elasticsearch7 package in preparation for the integration of the new Elasticsearch client. The were moved back to the org.springframework.data.elasticsearch.core package as we keep the classes use the old Elasticsearch client where they were.

Behaviour change

`ReactiveElasticsearchTemplate`在直接创建或通过 Spring Boot 配置创建时，默认刷新策略为 IMMEDIATE。这可能导致大量索引时性能问题，并且与 Elasticsearch 的默认行为不同。现在已更改为默认刷新策略为 NONE。当通过使用 Reactive REST Client中描述的配置来提供 `ReactiveElasticsearchTemplate`时，默认刷新策略已设置为 NONE。

The ReactiveElasticsearchTemplate, when created directly or by Spring Boot configuration had a default refresh policy of IMMEDIATE. This could cause performance issues on heavy indexing and was different than the default behaviour of Elasticsearch. This has been changed to that now the default refresh policy is NONE. When the ReactiveElasticsearchTemplate was provided by using the configuration like described in Reactive REST Client the default refresh policy already was set to NONE.

New Elasticsearch client

Elasticsearch 引入了它的新 ElasticsearchClient 并已弃用之前的 RestHighLevelClient。Spring Data Elasticsearch 4.4 仍然继续将旧客户端作为默认客户端，原因如下：

Elasticsearch has introduced it’s new ElasticsearchClient and has deprecated the previous RestHighLevelClient. Spring Data Elasticsearch 4.4 still uses the old client as the default client for the following reasons:

  • The new client forces applications to use the jakarta.json.spi.JsonProvider package whereas Spring Boot will stick to javax.json.spi.JsonProvider until version 3. So switching the default implementaiton in Spring Data Elasticsearch can only come with Spring Data Elasticsearch 5 (Spring Data 3, Spring 6).

  • There are still some bugs in the Elasticsearch client which need to be resolved

  • The implementation using the new client in Spring Data Elasticsearch is not yet complete, due to limited resources working on that - remember Spring Data Elasticsearch is a community driven project that lives from public contributions.

How to use the new client

使用新客户端的实现尚未完成，一些操作会引发 java.lang.UnsupportedOperationException 或可能引发 NPE（例如，当 Elasticsearch 无法解析来自服务器的响应时，有时仍然会发生这种情况），使用新客户端来测试实现，但不要在生产代码中使用！

The implementation using the new client is not complete, some operations will throw a java.lang.UnsupportedOperationException or might throw NPE (for example when the Elasticsearch cannot parse a response from the server, this still happens sometimes) Use the new client to test the implementations but do not use it in productive code yet!

为了尝试和使用新客户端，需要以下步骤：

In order to try and use the new client the following steps are necessary:

Make sure not to configure the existing default client

如果使用 Spring Boot，从自动配置中排除 Spring Data Elasticsearch

If using Spring Boot, exclude Spring Data Elasticsearch from the autoconfiguration

@SpringBootApplication(exclude = ElasticsearchDataAutoConfiguration.class)
public class SpringdataElasticTestApplication {
	// ...
}

从应用程序配置中移除与 Spring Data Elasticsearch 相关的属性。如果 Spring Data Elasticsearch 是使用编程方式配置的 (参见 Elasticsearch Clients)，则从 Spring 应用程序上下文中移除这些 Bean。

Remove Spring Data Elasticsearch related properties from your application configuration. If Spring Data Elasticsearch was configured using a programmatic configuration (see Elasticsearch Clients), remove these beans from the Spring application context.

Add dependencies

Spring Data Elasticsearch 中对新 Elasticsearch 客户端的依赖关系仍然是可选的，因此需要显式添加它们：

The dependencies for the new Elasticsearch client are still optional in Spring Data Elasticsearch so they need to be added explicitly:

<dependencies>
    <dependency>
        <groupId>co.elastic.clients</groupId>
        <artifactId>elasticsearch-java</artifactId>
        <version>7.17.3</version>
        <exclusions>
            <exclusion>
                <groupId>commons-logging</groupId>
                <artifactId>commons-logging</artifactId>
            </exclusion>
        </exclusions>
    </dependency>
    <dependency>
        <groupId>org.elasticsearch.client</groupId>
        <artifactId>elasticsearch-rest-client</artifactId> <!-- is Apache 2-->
        <version>7.17.3</version>
        <exclusions>
            <exclusion>
                <groupId>commons-logging</groupId>
                <artifactId>commons-logging</artifactId>
            </exclusion>
        </exclusions>
    </dependency>
</dependencies>

在使用 Spring Boot 时，需要在 pom.xml 中设置以下属性。

When using Spring Boot, it is necessary to set the following property in the pom.xml.

<properties>
    <jakarta-json.version>2.0.1</jakarta-json.version>
</properties>

New configuration classes

Imperative style

为了配置 Spring Data Elasticsearch 以使用新客户端，需要创建一个从 org.springframework.data.elasticsearch.client.elc.ElasticsearchConfiguration 派生的配置 Bean：

In order configure Spring Data Elasticsearch to use the new client, it is necessary to create a configuration bean that derives from org.springframework.data.elasticsearch.client.elc.ElasticsearchConfiguration:

@Configuration
public class NewRestClientConfig extends ElasticsearchConfiguration {

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

此配置方式与旧客户端相同，但不再需要创建此配置 bean 之外的其他内容。通过此配置，以下 bean 将在 Spring 应用程序上下文中可用：

The configuration is done in the same way as with the old client, but it is not necessary anymore to create more than the configuration bean. With this configuration, the following beans will be available in the Spring application context:

  • a RestClient bean, that is the configured low level RestClient that is used by the Elasticsearch client

  • an ElasticsearchClient bean, this is the new client that uses the RestClient

  • an ElasticsearchOperations bean, available with the bean names elasticsearchOperations and elasticsearchTemplate, this uses the ElasticsearchClient

Reactive style

要在反应式环境中使用新客户端，唯一的区别在于用于导出配置的类：

To use the new client in a reactive environment the only difference is the class from which to derive the configuration:

@Configuration
public class NewRestClientConfig extends ReactiveElasticsearchConfiguration {

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

通过此配置，以下 bean 将在 Spring 应用程序上下文中可用：

With this configuration, the following beans will be available in the Spring application context:

  • a RestClient bean, that is the configured low level RestClient that is used by the Elasticsearch client

  • an ReactiveElasticsearchClient bean, this is the new reactive client that uses the RestClient

  • an ReactiveElasticsearchOperations bean, available with the bean names reactiveElasticsearchOperations and reactiveElasticsearchTemplate, this uses the ReactiveElasticsearchClient