Spring Data Elasticsearch 4.4 到 5.0 迁移指南

前言

本文主要介绍 Spring Data Elasticsearch 从 4.4.x 版本升级到 5.0.x 版本时的重大变更和迁移方案。作为 Spring 生态中与 Elasticsearch 交互的核心组件，Spring Data Elasticsearch 5.0 带来了多项重要改进，包括新的客户端实现、API 优化等。

废弃功能

1. 自定义日志追踪级别

旧版本中通过设置 logging.level.org.springframework.data.elasticsearch.client.WIRE=trace 来记录请求日志的方式已被废弃。现在推荐使用 Elasticsearch RestClient 提供的日志方案：

logging.level.org.elasticsearch.client=trace

2. 废弃包结构调整

org.springframework.data.elasticsearch.client.erhlc 包下的所有类已被标记为废弃，因为这些类基于 Elasticsearch 旧版 RestHighLevelClient 实现。

3. 移除的废弃代码

• DateFormat.none 和 DateFormat.custom（自 4.2 起废弃）
• @Document 注解中已废弃的属性（改用 @Settings 注解）
• @DynamicMapping 和 @DynamicMappingValue 注解（改用 @Document.dynamic 或 @Field.dynamic）

重大变更

1. 移除废弃的 API 调用

SearchOperations 和 ReactiveSearchOperations 接口中依赖 Elasticsearch 类作为参数的 suggest 相关方法已被移除，这些 API 现在更加独立于 Elasticsearch 具体实现。

2. 包结构调整

所有基于旧版 RestHighLevelClient 的类已移至 org.springframework.data.elasticsearch.client.erhlc 包，实现了以下分离：

• 使用旧版 Elasticsearch 库的代码
• 使用新版 Elasticsearch 客户端的代码
• 与客户端实现无关的代码

重要提示：

• 直接使用 ElasticsearchRestTemplate 需要调整导入
• NativeSearchQuery 已替换为 NativeQuery 类

3. Java 17 Record 转换

以下类已转换为 Java 17 Record 类型，注意方法调用方式变化（从 getProp() 改为 prop()）：

• IndexResponseMetaData
• ActiveShardCount
• Version
• ScoreDoc
• ScriptData
• SeqNoPrimaryTerm

4. 新的 HttpHeaders 类

5.0 版本引入了独立的 HttpHeaders 类（位于 org.springframework.data.elasticsearch.support 包），替代了原先依赖的 Spring Web 中的同名类。

迁移方法：

// 旧方式
import org.springframework.http.HttpHeaders;

// 新方式
import org.springframework.data.elasticsearch.support.HttpHeaders;

新版 Elasticsearch 客户端

Spring Data Elasticsearch 5.0 开始使用新的 ElasticsearchClient，并废弃了 RestHighLevelClient。

1. 命令式配置

配置示例：

@Configuration
public class NewRestClientConfig extends ElasticsearchConfiguration {
    @Override
    public ClientConfiguration clientConfiguration() {
        return ClientConfiguration.builder()
            .connectedTo("localhost:9200")
            .build();
    }
}

自动创建的 Bean：

• RestClient：底层 REST 客户端
• ElasticsearchClient：新版客户端
• ElasticsearchOperations：操作接口（别名为 elasticsearchTemplate）

2. 响应式配置

响应式配置只需继承不同的基类：

@Configuration
public class NewRestClientConfig extends ReactiveElasticsearchConfiguration {
    // 配置相同
}

自动创建的 Bean：

• RestClient：底层 REST 客户端
• ReactiveElasticsearchClient：响应式客户端
• ReactiveElasticsearchOperations：响应式操作接口

3. 继续使用旧版客户端

如需继续使用 RestHighLevelClient，需显式添加依赖（注意版本号）：

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

迁移建议

1. 逐步迁移：先替换客户端配置，再逐步调整业务代码
2. 充分测试：新版客户端在性能和行为上可能有差异
3. 利用IDE：利用IDE的重构功能帮助修改方法调用（Record类相关变更）
4. 日志调整：确保新的日志配置满足调试需求

通过本文的指导，开发者可以顺利完成 Spring Data Elasticsearch 从 4.4 到 5.0 的升级，享受新版带来的改进和性能提升。