从 4.4.x 升级到 5.0.x

DeepSeek V3 中英对照 Upgrading from 4.4.x to 5.0.x

本节介绍了从版本 4.4.x 到 5.0.x 的重大变更，以及如何通过新引入的功能替换已移除的功能。

弃用

自定义跟踪级别日志

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

org.springframework.data.elasticsearch.client.erhlc 包

请参阅包变更，此包中的所有类已被弃用，因为默认使用的客户端实现是基于 Elasticsearch 新 Java 客户端的版本，详情见新的 Elasticsearch 客户端。

移除已弃用的代码

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

自 4.2 版本起，@Document 中已弃用的属性已被移除。请使用 @Settings 注解来替代这些属性。

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

重大变更

移除已弃用的调用

操作接口中的 suggest 调用已被移除

SearchOperations 和 ReactiveSearchOperations 中曾经有一些已弃用的调用，这些调用使用了 Elasticsearch 类作为参数。现在这些调用已被移除，因此在这些 API 中对 Elasticsearch 类的依赖已经被清理。

包变更

所有使用或依赖于已弃用的 Elasticsearch RestHighLevelClient 的类已被移动到 org.springframework.data.elasticsearch.client.erhlc 包中。通过这一更改，我们现在可以清晰地将代码分为三类：使用旧的已弃用 Elasticsearch 库的代码、使用新的 Elasticsearch 客户端的代码，以及独立于客户端实现的代码。此外，迄今为止提供的响应式实现也已被移动到此包中，因为该实现包含从 Elasticsearch 库复制并改编的代码。

如果你直接使用 ElasticsearchRestTemplate 而不是 ElasticsearchOperations 接口，你还需要调整你的导入语句。

在使用 NativeSearchQuery 类时，你需要切换到 NativeQuery 类，它可以接受来自新的 Elasticsearch 客户端库的 Query 实例。你可以在测试代码中找到很多示例。

转换为 Java 17 记录

以下类已转换为 Record，你可能需要将 getProp() 的 getter 方法使用调整为 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

新的 HttpHeaders 类

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

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

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

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

新的 Elasticsearch 客户端

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

命令式风格配置

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

@Configuration
public class NewRestClientConfig extends ElasticsearchConfiguration {

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

配置方式与旧客户端相同，但不再需要创建除配置 bean 之外的更多 bean。通过此配置，Spring 应用上下文中将提供以下 bean：

• 一个 RestClient bean，这是 Elasticsearch 客户端使用的已配置的低级别 RestClient

• 一个 ElasticsearchClient bean，这是使用 RestClient 的新客户端

• 一个 ElasticsearchOperations bean，可通过 bean 名称 elasticsearchOperations 和 elasticsearchTemplate 使用，它使用 ElasticsearchClient

响应式风格配置

在响应式环境中使用新的客户端，唯一的区别是配置所继承的类：

@Configuration
public class NewRestClientConfig extends ReactiveElasticsearchConfiguration {

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

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

• 一个 RestClient bean，这是由 Elasticsearch 客户端使用的已配置的低级 RestClient

• 一个 ReactiveElasticsearchClient bean，这是使用 RestClient 的新响应式客户端

• 一个 ReactiveElasticsearchOperations bean，可用 bean 名称为 reactiveElasticsearchOperations 和 reactiveElasticsearchTemplate，它使用 ReactiveElasticsearchClient

仍然想使用旧客户端？

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

<!-- 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，而这个版本并不存在。