Upgrading from 4.4.x to 5.0.x

本节描述了从 4.4.x 版至 5.0.x 版的重大更改，以及如何通过新引入的功能替换已移除的功能。

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

Deprecations

Custom trace level logging

通过设置属性 logging.level.org.springframework.data.elasticsearch.client.WIRE=trace 进行日志记录现已弃用，Elasticsearch RestClient 提供了可通过将 tracer 包的日志级别设置为“trace”来激活的更佳解决方案。

Logging by setting the property logging.level.org.springframework.data.elasticsearch.client.WIRE=trace is deprecated now, the Elasticsearch RestClient provides a better solution that can be activated by setting the logging level of the tracer package to "trace".

org.springframework.data.elasticsearch.client.erhlc package

请参见 Package changes，此程序包中的所有类都已弃用，因为要使用的默认客户端实现是基于 Elasticsearch 的新 Java 客户端，请参见 New Elasticsearch client

See Package changes, all classes in this package have been deprecated, as the default client implementations to use are the ones based on the new Java Client from Elasticsearch, see New Elasticsearch client

Removal of deprecated code

DateFormat.none 和 DateFormat.custom 自 4.2 版起已被弃用，现已移除。

DateFormat.none and DateFormat.custom had been deprecated since version 4.2 and have been removed.

自 4.2 版起已弃用的 @Document 的属性现已移除。请对它们使用 @Settings 注释。

The properties of @Document that were deprecated since 4.2 have been removed. Use the @Settings annotation for these.

@DynamicMapping 和 @DynamicMappingValue 已被移除。请改用 @Document.dynamic 或 @Field.dynamic。

@DynamicMapping and @DynamicMappingValue have been removed. Use @Document.dynamic or @Field.dynamic instead.

Breaking Changes

Removal of deprecated calls

suggest calls in operations interfaces have been removed

SearchOperations 和 ReactiveSearchOperations 都有已被弃用的使用 Elasticsearch 类作为参数的调用。现已删除它们，因此已消除这些 API 中对 Elasticsearch 类依赖。

Both SearchOperations and ReactiveSearchOperations had deprecated calls that were using Elasticsearch classes as parameters. These now have been removed and so the dependency on Elasticsearch classes in these APIs has been cleaned.

Package changes

所有使用或依赖已弃用 Elasticsearch RestHighLevelClient 的类现已移至包 org.springframework.data.elasticsearch.client.erhlc。通过此更改，我们现在可以清楚地区分使用旧的已弃用 Elasticsearch 库的代码、使用新的 Elasticsearch 客户端的代码和与客户端实现无关的代码。目前提供的响应式实现也已移至这里，因为此实现包含从 Elasticsearch 库中复制和改编的代码。

All the classes that are using or depend on the deprecated Elasticsearch RestHighLevelClient have been moved to the package org.springframework.data.elasticsearch.client.erhlc. By this change we now have a clear separation of code using the old deprecated Elasticsearch libraries, code using the new Elasticsearch client and code that is independent of the client implementation. Also the reactive implementation that was provided up to now has been moved here, as this implementation contains code that was copied and adapted from Elasticsearch libraries.

如果你直接使用 ElasticsearchRestTemplate，而不使用 ElasticsearchOperations 接口，你需要调整自己的导入。

If you are using ElasticsearchRestTemplate directly and not the ElasticsearchOperations interface you’ll need to adjust your imports as well.

使用 NativeSearchQuery 类时，你需要切换到 NativeQuery 类，它可以使用新 Elasticsearch 客户端库提供的 Query 实例。可以在测试代码中找到大量示例。

When working with the NativeSearchQuery class, you’ll need to switch to the NativeQuery class, which can take a Query instance coming from the new Elasticsearch client libraries. You’ll find plenty of examples in the test code.

Conversion to Java 17 records

以下类已转换为 Record，你可能需要将 getter 方法的使用从 getProp() 调整为 prop()：

The following classes have been converted to Record, you might need to adjust the use of getter methods from getProp() to prop():

  • org.springframework.data.elasticsearch.core.AbstractReactiveElasticsearchTemplate.IndexResponseMetaData

  • org.springframework.data.elasticsearch.core.ActiveShardCount

  • org.springframework.data.elasticsearch.support.Version

  • org.springframework.data.elasticsearch.support.ScoreDoc

  • org.springframework.data.elasticsearch.core.query.ScriptData

  • org.springframework.data.elasticsearch.core.query.SeqNoPrimaryTerm

New HttpHeaders class

在 4.4 版之前，客户端配置使用 org.springframework:spring-web 项目中的 HttpHeaders 类。这会引入对该工件的依赖。不使用 spring-web 的用户会遇到错误，因为找不到此类。

Until version 4.4 the client configuration used the HttpHeaders class from the org.springframework:spring-web project. This introduces a dependency on that artifact. Users that do not use spring-web then face an error as this class cannot be found.

在 5.0 版中，我们引入了自己的 HttpHeaders 来配置客户端。

In version 5.0 we introduce our own HttpHeaders to configure the clients.

因此，如果你在客户端配置中使用标头，你需要将 org.springframework.http.HttpHeaders 替换为 org.springframework.data.elasticsearch.support.HttpHeaders。

So if you are using headers in the client configuration, you need to replace org.springframework.http.HttpHeaders with org.springframework.data.elasticsearch.support.HttpHeaders.

提示：你可以将 org.springframework.http.HttpHeaders 传递给 org.springframework.data.elasticsearch.support.HttpHeaders 的 addAll() 方法。

Hint: You can pass a org.springframework.http .HttpHeaders to the addAll() method of org.springframework.data.elasticsearch.support.HttpHeaders.

New Elasticsearch client

Spring Data Elasticsearch 现在使用新的 ElasticsearchClient，已弃用之前的 RestHighLevelClient。

Spring Data Elasticsearch now uses the new ElasticsearchClient and has deprecated the use of the previous RestHighLevelClient.

Imperative style configuration

要配置 Spring Data Elasticsearch 以使用新客户端，必须创建一个源自 org.springframework.data.elasticsearch.client.elc.ElasticsearchConfiguration 的配置 bean：

To 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 configuration

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

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

Still want to use the old client?

旧的已弃用的 RestHighLevelClient 仍然可以使用，但你需要将依赖项显式添加到你的应用程序，因为 Spring Data Elasticsearch 不再自动引入它：

The old deprecated RestHighLevelClient can still be used, but you will need to add the dependency explicitly to your application as Spring Data Elasticsearch does not pull it in automatically anymore:

<!-- include the RHLC, specify version explicitly	-->
<dependency>
	<groupId>org.elasticsearch.client</groupId>
	<artifactId>elasticsearch-rest-high-level-client</artifactId>
	<version>7.17.5</version>
	<exclusions>
		<exclusion>
			<groupId>commons-logging</groupId>
			<artifactId>commons-logging</artifactId>
		</exclusion>
	</exclusions>
</dependency>

请务必显式指定版本 7.17.6，否则 maven 将解析为 8.5.0 而该版本不存在。

Make sure to specify the version 7.17.6 explicitly, otherwise maven will resolve to 8.5.0, and this does not exist.