Spring Data Elasticsearch 3.2到4.0版本迁移指南

概述

本文将详细介绍Spring Data Elasticsearch从3.2.x升级到4.0.x版本的主要变更内容，帮助开发者顺利完成迁移工作。4.0版本带来了多项重大改进，同时也引入了一些破坏性变更，理解这些变化对于平稳升级至关重要。

核心变更解析

1. Jackson映射器的移除

在3.2.x版本中，Spring Data Elasticsearch默认使用Jackson Mapper将实体对象转换为Elasticsearch所需的JSON表示。4.0版本移除了这一依赖，转而完全采用基于元模型的转换器（原名为ElasticsearchEntityMapper）。

迁移建议：

• 如果你之前显式配置了ElasticsearchEntityMapper bean，现在可以安全移除这些配置
• 原Jackson注解（如@JsonFormat等）不再生效，应替换为Spring Data Elasticsearch的@Field注解

示例变更：

// 3.2.x版本
@Document(indexName = "persons")
public class Person {
    @JsonFormat(pattern = "yyyy-MM-dd")
    private Date birthDate;
}

// 4.0.x版本
@Document(indexName = "persons")
public class Person {
    @Field(type = FieldType.Date, format = DateFormat.date)
    private Date birthDate;
}

2. 查询对象中隐式索引名的移除

3.2.x版本中，查询类如IndexQuery或SearchQuery会从@Document注解中自动获取索引名称。4.0版本要求显式指定IndexCoordinates参数，这使得查询对象可以在不同索引间复用。

代码示例对比：

// 3.2.x版本
IndexQuery indexQuery = new IndexQueryBuilder()
    .withId(person.getId().toString())
    .withObject(person)
    .build();

// 4.0.x版本
IndexCoordinates index = elasticsearchOperations.getIndexCoordinatesFor(person.getClass());
IndexQuery indexQuery = new IndexQueryBuilder()
    .withId(person.getId().toString())
    .withObject(person)
    .build();
elasticsearchOperations.index(indexQuery, index);

3. 操作接口的重构

4.0版本对ElasticsearchOperations接口进行了模块化拆分，使其更符合Elasticsearch API结构：

• DocumentOperations：文档相关操作（保存、删除等）
• SearchOperations：搜索功能
• IndexOperations：索引操作（创建、映射等）

迁移提示：

• 原有ElasticsearchOperations中的索引操作方法已被标记为@Deprecated
• 新代码应直接使用相应的专用接口

废弃内容说明

1. 方法和类废弃

大量方法和类已被标记为废弃，建议开发者检查项目中的相关调用并按照Javadoc建议进行替换。

典型示例：

// 废弃方法
@Deprecated
<T> T queryForObject(GetQuery query, Class<T> clazz);

// 替代方法
<T> T get(String id, Class<T> clazz, IndexCoordinates index);

2. Elasticsearch相关废弃

• TransportClient已被标记为废弃（Elasticsearch 7+）
• 映射类型（mapping types）在Elasticsearch 7中已移除，相关参数虽保留但不再使用

完全移除的功能

1. ElasticsearchEntityMapper接口：完全移除，无替代方案
2. SearchQuery接口：合并至Query接口
3. ResultsExtractor及相关方法：由新的搜索结果类型替代
4. 低层级滚动API方法：替换为searchScrollStart等新方法

迁移最佳实践

1. 逐步替换：先处理Jackson注解变更，再调整查询方式
2. 接口适配：将代码迁移到新的操作接口
3. 测试验证：特别注意索引操作和搜索结果处理的变更点
4. 性能监控：新版映射器可能有不同的性能特征

通过理解这些关键变更点，开发者可以更有针对性地进行版本升级，充分利用4.0版本带来的改进特性。