跳到主要内容

从 3.2.x 升级到 4.0.x

DeepSeek V3 中英对照 Upgrading from 3.2.x to 4.0.x

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

移除已使用的 Jackson 映射器​

4.0.x 版本中的一项变化是，Spring Data Elasticsearch 不再使用 Jackson Mapper 将实体映射为 Elasticsearch 所需的 JSON 表示形式（参见 Elasticsearch 对象映射）。在 3.2.x 版本中，Jackson Mapper 是默认使用的映射器。可以通过显式配置切换到基于元模型的转换器（名为 ElasticsearchEntityMapper）（参见 元模型对象映射）。

在 4.0.x 版本中，基于元模型的转换器是唯一可用的转换器，并且不需要显式配置。如果你曾经通过提供如下 bean 来启用元模型转换器的自定义配置：

@Bean
@Override
public EntityMapper entityMapper() {

  ElasticsearchEntityMapper entityMapper = new ElasticsearchEntityMapper(
    elasticsearchMappingContext(), new DefaultConversionService()
  );
  entityMapper.setConversions(elasticsearchCustomConversions());

  return entityMapper;
}
java

你现在需要移除这个 bean，因为 ElasticsearchEntityMapper 接口已经被移除。

实体配置

一些用户在实体类上使用了自定义的 Jackson 注解，例如为了定义 Elasticsearch 中映射文档的自定义名称或配置日期转换。这些注解不再被考虑。所需的功能现在由 Spring Data Elasticsearch 的 @Field 注解提供。请参阅 映射注解概述 获取详细信息。

从查询对象中移除隐式索引名称​

在 3.2.x 版本中，像 IndexQuery 或 SearchQuery 这样的不同查询类具有一些属性，这些属性指定了它们所操作的一个或多个索引名称。如果这些属性没有设置，系统会检查传入的实体，以从 @Document 注解中获取设置的索引名称。

而在 4.0.x 版本中，索引名称现在必须通过一个类型为 IndexCoordinates 的额外参数来提供。通过这种方式分离索引名称，现在可以使用一个查询对象来针对不同的索引进行操作。

例如，以下代码：

IndexQuery indexQuery = new IndexQueryBuilder()
  .withId(person.getId().toString())
  .withObject(person)
  .build();

String documentId = elasticsearchOperations.index(indexQuery);
java

必须更改为：

IndexCoordinates indexCoordinates = elasticsearchOperations.getIndexCoordinatesFor(person.getClass());

IndexQuery indexQuery = new IndexQueryBuilder()
  .withId(person.getId().toString())
  .withObject(person)
  .build();

String documentId = elasticsearchOperations.index(indexQuery, indexCoordinates);
java

为了更容易地处理实体并使用实体 @Document 注解中包含的索引名称，新增了一些方法，例如 DocumentOperations.save(T entity)；

新的操作接口​

在 3.2 版本中，ElasticsearchOperations 接口定义了 ElasticsearchTemplate 类的所有方法。在版本 4 中，这些功能被拆分到不同的接口中，使这些接口与 Elasticsearch API 保持一致：

  • DocumentOperations 是与文档相关的函数，例如保存或删除

  • SearchOperations 包含在 Elasticsearch 中搜索的函数

  • IndexOperations 定义了操作索引的函数，例如索引创建或映射创建。

ElasticsearchOperations 现在扩展了 DocumentOperations 和 SearchOperations，并且提供了访问 IndexOperations 实例的方法。

备注

在 3.2 版本中，ElasticsearchOperations 接口中的所有函数现在都已移至 IndexOperations 接口，它们仍然可用，但已被标记为弃用，并且具有默认实现，这些实现委托给新的实现：

/**
 * Create an index for given indexName.
 *
 * @param indexName the name of the index
 * @return {@literal true} if the index was created
 * @deprecated since 4.0, use {@link IndexOperations#create()}
 */
@Deprecated
default boolean createIndex(String indexName) {
	return indexOps(IndexCoordinates.of(indexName)).create();
}
java

弃用​

方法和类​

许多函数和类已被弃用。这些函数仍然有效，但 Javadocs 中显示了应该用哪些内容来替换它们。

/*
 * Retrieves an object from an index.
 *
 * @param query the query defining the id of the object to get
 * @param clazz the type of the object to be returned
 * @return the found object
 * @deprecated since 4.0, use {@link #get(String, Class, IndexCoordinates)}
 */
@Deprecated
@Nullable
<T> T queryForObject(GetQuery query, Class<T> clazz);
java

Elasticsearch 弃用​

从版本 7 开始，Elasticsearch 的 TransportClient 已被弃用，它将在 Elasticsearch 版本 8 中被移除。Spring Data Elasticsearch 在版本 4.0 中弃用了使用 TransportClient 的 ElasticsearchTemplate 类。

映射类型在 Elasticsearch 7 中已被移除，它们仍然作为已弃用的值存在于 Spring Data 的 @Document 注解和 IndexCoordinates 类中，但在内部已不再使用。

移除内容​

  • 正如之前所述，ElasticsearchEntityMapper 接口已被移除。

  • SearchQuery 接口已经合并到其基接口 Query 中，因此可以将所有 SearchQuery 的出现替换为 Query。

  • 方法 org.springframework.data.elasticsearch.core.ElasticsearchOperations.query(SearchQuery query, ResultsExtractor<T> resultsExtractor); 以及 org.springframework.data.elasticsearch.core.ResultsExtractor 接口已被移除。这些方法和接口原本用于在基于 Jackson 的映射器无法满足需求时解析 Elasticsearch 的响应结果。自 4.0 版本起，引入了新的 Search Result Types 来返回 Elasticsearch 响应中的信息，因此不再需要暴露这种底层功能。

  • 低级别方法 startScroll、continueScroll 和 clearScroll 已从 ElasticsearchOperations 接口中移除。对于低级别的 Scroll API 访问，现在可以在 ElasticsearchRestTemplate 类中使用 searchScrollStart、searchScrollContinue 和 searchScrollClear 方法。