跳到主要内容
版本:6.1.1

从 4.4.x 升级到 5.0.x

Doubao 中英对照 Upgrading from 4.4.x to 5.0.x

本节介绍从 4.4.x 版本到 5.0.x 版本的破坏性变更,以及如何用新引入的特性替代被移除的特性。

弃用项​

自定义 trace 级别日志​

通过设置属性 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 版本起已弃用,现已移除。

@Document 中自 4.2 起已弃用的属性已被移除。请对这些属性使用 @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 接口,则还需要调整您的 import。

在使用 NativeSearchQuery 类时,您需要改用 NativeQuery 类,后者可以接受来自新 Elasticsearch 客户端库的 Query 实例。您可以在测试代码中找到大量示例。

转换为 Java 17 record​

以下类已转换为 Record,您可能需要将 getter 方法的使用从 getProp() 调整为 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 来配置客户端。

因此,如果您在客户端配置中使用了 headers,需要将 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();
}
}

通过此配置,Spring 应用程序上下文中将提供以下 Bean:

  • 一个 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,而该版本并不存在。