从 4.3.x 升级到 4.4.x

DeepSeek V3 中英对照 Upgrading from 4.3.x to 4.4.x

本节描述了从版本 4.3.x 到 4.4.x 的重大变更，以及如何通过新引入的功能替换已移除的功能。

弃用

org.springframework.data.elasticsearch.core.ReactiveElasticsearchOperations

方法 <T> Publisher<T> execute(ClientCallback<Publisher<T>> callback) 已被弃用。由于现在有多个使用不同客户端库的实现，execute 方法仍然可以在不同的实现中使用，但接口中不再有该方法，因为不同的客户端没有通用的回调接口。

重大变更

移除已弃用的类

org.springframework.data.elasticsearch.core.ElasticsearchTemplate 已被移除

从 4.4 版本开始，Spring Data Elasticsearch 不再使用 Elasticsearch 的 TransportClient（自 Elasticsearch 7.0 起已被弃用）。这意味着自 Spring Data Elasticsearch 4.0 起已被弃用的 org.springframework.data.elasticsearch.core.ElasticsearchTemplate 类已被移除。这是使用 TransportClient 的 ElasticsearchOperations 接口的实现。与 Elasticsearch 的连接必须使用命令式的 ElasticsearchRestTemplate 或响应式的 ReactiveElasticsearchTemplate 来实现。

包变更

在 4.3 版本中，为了准备集成新的 Elasticsearch 客户端，两个类（ElasticsearchAggregations 和 ElasticsearchAggregation）被移到了 org.springframework.data.elasticsearch.core.clients.elasticsearch7 包中。由于我们保留了这些类继续使用旧的 Elasticsearch 客户端，它们又被移回了 org.springframework.data.elasticsearch.core 包中。

行为变更

ReactiveElasticsearchTemplate 在直接创建或通过 Spring Boot 配置创建时，默认的刷新策略是 IMMEDIATE。这可能会导致在大量索引操作时出现性能问题，并且与 Elasticsearch 的默认行为不同。现在已更改为默认刷新策略为 NONE。当通过 Reactive REST Client 中描述的配置提供 ReactiveElasticsearchTemplate 时，默认刷新策略已经设置为 NONE。

新的 Elasticsearch 客户端

Elasticsearch 引入了新的 ElasticsearchClient，并弃用了之前的 RestHighLevelClient。Spring Data Elasticsearch 4.4 仍然使用旧客户端作为默认客户端，原因如下：

• 新客户端强制应用程序使用 jakarta.json.spi.JsonProvider 包，而 Spring Boot 在版本 3 之前将继续使用 javax.json.spi.JsonProvider。因此，在 Spring Data Elasticsearch 中切换默认实现只能伴随 Spring Data Elasticsearch 5（Spring Data 3，Spring 6）一起发布。

• Elasticsearch 客户端中仍存在一些需要修复的 bug。

• 由于资源有限，Spring Data Elasticsearch 中使用新客户端的实现尚未完成——请记住，Spring Data Elasticsearch 是一个社区驱动的项目，依赖于公共贡献。

如何使用新的客户端

警告

使用新客户端的实现尚未完成，某些操作会抛出 java.lang.UnsupportedOperationException 或可能抛出 NPE（例如，当 Elasticsearch 无法解析来自服务器的响应时，这种情况仍然时有发生）
请使用新客户端来测试实现，但暂时不要在正式代码中使用它！

为了尝试使用新的客户端，需要按照以下步骤操作：

确保不要配置现有的默认客户端

如果使用 Spring Boot，请从自动配置中排除 Spring Data Elasticsearch

@SpringBootApplication(exclude = ElasticsearchDataAutoConfiguration.class)
public class SpringdataElasticTestApplication {
	// ...
}

java

从你的应用程序配置中移除与 Spring Data Elasticsearch 相关的属性。如果 Spring Data Elasticsearch 是通过编程配置的（参见 Elasticsearch 客户端），请从 Spring 应用程序上下文中移除这些 bean。

添加依赖

新 Elasticsearch 客户端的依赖在 Spring Data Elasticsearch 中仍然是可选的，因此需要显式添加：

<dependencies>
    <dependency>
        <groupId>co.elastic.clients</groupId>
        <artifactId>elasticsearch-java</artifactId>
        <version>7.17.3</version>
        <exclusions>
            <exclusion>
                <groupId>commons-logging</groupId>
                <artifactId>commons-logging</artifactId>
            </exclusion>
        </exclusions>
    </dependency>
    <dependency>
        <groupId>org.elasticsearch.client</groupId>
        <artifactId>elasticsearch-rest-client</artifactId> <!-- is Apache 2-->
        <version>7.17.3</version>
        <exclusions>
            <exclusion>
                <groupId>commons-logging</groupId>
                <artifactId>commons-logging</artifactId>
            </exclusion>
        </exclusions>
    </dependency>
</dependencies>

xml

在使用 Spring Boot 时，需要在 pom.xml 中设置以下属性。

<properties>
    <jakarta-json.version>2.0.1</jakarta-json.version>
</properties>

xml

新的配置类

命令式风格

为了配置 Spring Data Elasticsearch 以使用新的客户端，需要创建一个从 org.springframework.data.elasticsearch.client.elc.ElasticsearchConfiguration 派生的配置 Bean：

@Configuration
public class NewRestClientConfig extends ElasticsearchConfiguration {

	@Override
	public ClientConfiguration clientConfiguration() {
		return ClientConfiguration.builder() //
			.connectedTo("localhost:9200") //
			.build();
	}
}

java

配置方式与旧客户端相同，但不再需要创建多个配置 Bean。通过此配置，Spring 应用上下文中将提供以下 Bean：

• 一个 RestClient bean，这是由 Elasticsearch 客户端使用的已配置的低级 RestClient

• 一个 ElasticsearchClient bean，这是使用 RestClient 的新客户端

• 一个 ElasticsearchOperations bean，可通过 bean 名称 elasticsearchOperations 和 elasticsearchTemplate 获取，它使用 ElasticsearchClient

响应式风格

在响应式环境中使用新客户端时，唯一的区别在于配置所继承的类：

@Configuration
public class NewRestClientConfig extends ReactiveElasticsearchConfiguration {

	@Override
	public ClientConfiguration clientConfiguration() {
		return ClientConfiguration.builder() //
			.connectedTo("localhost:9200") //
			.build();
	}
}

java

通过这个配置，以下 beans 将在 Spring 应用上下文中可用：

• 一个 RestClient bean，这是由 Elasticsearch 客户端使用的已配置的低级 RestClient

• 一个 ReactiveElasticsearchClient bean，这是使用 RestClient 的新响应式客户端

• 一个 ReactiveElasticsearchOperations bean，可以通过 bean 名称 reactiveElasticsearchOperations 和 reactiveElasticsearchTemplate 使用，它使用了 ReactiveElasticsearchClient