从 4.4.x 升级到 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:
-
一个
RestClientBean,即所配置的、供 Elasticsearch 客户端使用的低级RestClient -
一个
ElasticsearchClientBean,这是使用RestClient的新客户端 -
一个
ElasticsearchOperationsBean,可通过 Bean 名 elasticsearchOperations 和 elasticsearchTemplate 获取,它使用ElasticsearchClient
响应式风格配置
要在响应式环境中使用新客户端,唯一的区别在于配置所派生自的类:
@Configuration
public class NewRestClientConfig extends ReactiveElasticsearchConfiguration {
@Override
public ClientConfiguration clientConfiguration() {
return ClientConfiguration.builder() //
.connectedTo("localhost:9200") //
.build();
}
}
通过此配置,Spring 应用程序上下文中将提供以下 Bean:
-
一个
RestClientBean,即所配置的、供 Elasticsearch 客户端使用的低级RestClient -
一个
ReactiveElasticsearchClientBean,这是使用RestClient的新响应式客户端 -
一个
ReactiveElasticsearchOperationsBean,可通过 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,而该版本并不存在。