从 3.2.x 升级到 4.0.x

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

移除使用的 Jackson Mapper

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;
}

现在您需要移除此 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);

必须更改为

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

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

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

为了更方便地使用实体并使用实体的 @Document 注解中包含的索引名称，添加了新的方法，例如 DocumentOperations.save(T entity);

新的操作接口

在 3.2 版本中，存在 ElasticsearchOperations 接口，该接口定义了 ElasticsearchTemplate 类的所有方法。在 4.0 版本中，这些函数已拆分为不同的接口，使这些接口与 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();
}

弃用

方法和类

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

来自 ElasticsearchOperations 的示例
/*
 * 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);

Elasticsearch 弃用

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

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

移除

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

  • SearchQuery 接口已合并到其基础接口 Query 中，因此其出现可以简单地替换为 Query。

  • org.springframework.data.elasticsearch.core.ElasticsearchOperations.query(SearchQuery query, ResultsExtractor<T> resultsExtractor); 方法和 org.springframework.data.elasticsearch.core.ResultsExtractor 接口已被移除。这些方法可用于解析来自 Elasticsearch 的结果，用于 Jackson 基于映射器完成的响应映射不足的情况。从 4.0 版本开始，有新的 搜索结果类型 用于返回来自 Elasticsearch 响应的信息，因此无需公开此低级功能。

  • ElasticsearchOperations 接口中的低级方法 startScroll、continueScroll 和 clearScroll 已被移除。对于低级滚动 API 访问，现在 ElasticsearchRestTemplate 类中提供了 searchScrollStart、searchScrollContinue 和 searchScrollClear 方法。