从 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)；

新的 Operations 接口

在 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();
}

弃用

方法和类

许多函数和类已被弃用。这些函数仍然可以使用，但 Javadoc 显示了应该用什么替代它们。

来自 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 起，Elasticsearch TransportClient 已被弃用，它将在 Elasticsearch 版本 8 中移除。Spring Data Elasticsearch 在 4.0 版本中弃用了使用 TransportClient 的 ElasticsearchTemplate 类。

映射类型已从 Elasticsearch 7 中移除，它们在 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 接口已被移除。这些曾用于在基于 Jackson 的映射器响应映射不足的情况下解析 Elasticsearch 的结果。自 4.0 版本起，有了新的搜索结果类型来返回 Elasticsearch 响应中的信息，因此不再需要暴露此低级功能。
低级方法 startScroll、continueScroll 和 clearScroll 已从 ElasticsearchOperations 接口中移除。对于低级滚动（scroll）API 访问，现在在 ElasticsearchRestTemplate 类上有 searchScrollStart、searchScrollContinue 和 searchScrollClear 方法。