Elasticsearch Java客户端配置与依赖详解

本文旨在解决在使用Elasticsearch Java客户端时常见的类找不到问题，特别是针对`ClientConfiguration`等新API客户端类。我们将详细介绍Elasticsearch Java客户端的演进、不同客户端的正确Maven依赖配置，并提供实际的代码示例，帮助开发者准确选择和集成所需的客户端。

Elasticsearch Java客户端的演进与依赖管理

在使用Elasticsearch的Java API时，开发者经常会遇到类找不到（ClassNotFoundException）的问题，尤其是在尝试使用特定类如ClientConfiguration时。这通常是由于对Elasticsearch Java客户端生态系统及其依赖的误解所致。Elasticsearch的Java客户端经历了多次迭代和演进，每个版本都有其特定的依赖和用途。

最初，Elasticsearch提供了基于Transport模块的Java客户端，但该客户端已被弃用。随后，Elasticastics推出了RESTful API客户端，主要分为以下两种：

1. Java Low-Level REST Client (低级别REST客户端)：提供与Elasticsearch REST API交互的基础功能，不涉及任何高级抽象或对象映射。
2. Java High-Level REST Client (高级别REST客户端，HLRC)：在低级别客户端之上构建，提供了更高级的抽象，使得与Elasticsearch的交互更加便捷。然而，从Elasticsearch 7.15版本开始，HLRC已被弃用，并计划在8.x版本中移除。
3. Java API Client (新的Java API客户端)：这是Elasticsearch官方推荐的最新Java客户端，旨在取代HLRC。它提供了类型安全的API，并与Elasticsearch的REST API紧密集成，支持最新的功能和更好的开发体验。ClientConfiguration类就是这个新API客户端的一部分。

核心的org.elasticsearch:elasticsearch依赖包主要包含Elasticsearch的核心类型、传输协议和一些内部工具，它不包含任何具体的客户端实现（无论是低级别、高级别还是新的API客户端）。因此，即使正确引入了elasticsearch依赖，也无法找到客户端特定的类。

正确配置Java API客户端 (推荐)

如果您在代码中看到了ClientConfiguration类，或者教程中提及了与此相关的配置，那么您很可能正在尝试使用新的Java API客户端。这是Elasticsearch官方推荐的现代化客户端，提供类型安全和更友好的API。

要使用新的Java API客户端，您需要添加elasticsearch-java依赖。

Maven依赖配置

在您的pom.xml文件中，添加以下依赖：

    co.elastic.clients
    elasticsearch-java
    8.12.2 




    com.fasterxml.jackson.core
    jackson-databind
    2.16.1 

注意事项：

• elasticsearch-java的版本应与您连接的Elasticsearch服务器版本兼容。通常，建议使用与服务器版本相同或相近的客户端版本。
• 新的Java API客户端默认使用Jackson进行JSON处理，因此通常需要额外引入jackson-databind依赖。

客户端初始化示例

使用新的Java API客户端初始化一个连接到Elasticsearch的实例：

import co.elastic.clients.elasticsearch.ElasticsearchClient;
import co.elastic.clients.json.jackson.JacksonJsonpMapper;
import co.elastic.clients.transport.ElasticsearchTransport;
import co.elastic.clients.transport.rest_client.RestClientTransport;
import org.apache.http.HttpHost;
import org.elasticsearch.client.RestClient;

public class ElasticsearchApiClientExample {

    public static void main(String[] args) {
        // 1. 创建低级别REST客户端
        RestClient restClient = RestClient.builder(
                new HttpHost("localhost", 9200, "http"))
                .build();

        // 2. 使用JacksonMapper创建传输层
        ElasticsearchTransport transport = new RestClientTransport(
                restClient, new JacksonJsonpMapper());

        // 3. 创建Elasticsearch客户端
        ElasticsearchClient client = new ElasticsearchClient(transport);

        // 至此，您可以使用client对象与Elasticsearch进行交互
        System.out.println("Elasticsearch Java API Client initialized successfully.");
        // 示例：获取集群信息
        try {
            System.out.println("Cluster name: " + client.cluster().health().clusterName());
        } catch (Exception e) {
            System.err.println("Error getting cluster health: " + e.getMessage());
        }

        // 关闭低级别REST客户端
        try {
            restClient.close();
        } catch (Exception e) {
            System.err.println("Error closing RestClient: " + e.getMessage());
        }
    }
}

配置高级别REST客户端 (已弃用)

如果您的项目是遗留项目，或者您正在参考较旧的教程，并且明确需要使用高级别REST客户端（HLRC），您需要添加elasticsearch-rest-high-level-client依赖。

Maven依赖配置

    org.elasticsearch.client
    elasticsearch-rest-high-level-client
    7.17.7 

注意事项：

• HLRC已弃用，不建议在新项目中使用。
• HLRC的版本应与您连接的Elasticsearch服务器版本兼容。

客户端初始化示例 (HLRC)

import org.apache.http.HttpHost;
import org.elasticsearch.client.RestClient;
import org.elasticsearch.client.RestHighLevelClient;

public class ElasticsearchHighLevelClientExample {

    public static void main(String[] args) {
        RestHighLevelClient client = new RestHighLevelClient(
                RestClient.builder(
                        new HttpHost("localhost", 9200, "http")));

        // 至此，您可以使用client对象与Elasticsearch进行交互
        System.out.println("Elasticsearch High-Level REST Client initialized successfully.");

        // 关闭客户端
        try {
            client.close();
        } catch (Exception e) {
            System.err.println("Error closing High-Level RestClient: " + e.getMessage());
        }
    }
}

配置低级别REST客户端

低级别REST客户端是所有RESTful Java客户端的基础。如果您只需要直接与Elasticsearch的REST API交互，而不希望有任何高级抽象，可以使用它。

Maven依赖配置

    org.elasticsearch.client
    elasticsearch-rest-client
    7.17.7 

注意事项：

• 此客户端通常作为其他高级客户端的底层组件使用。

总结与最佳实践

1. 明确客户端类型：在引入依赖之前，首先确定您希望使用哪种Elasticsearch Java客户端。如果您是新项目开发或更新现有项目，强烈建议使用新的Java API客户端 (co.elastic.clients:elasticsearch-java)。
2. 版本匹配：确保您的客户端依赖版本与Elasticsearch服务器版本兼容。不匹配的版本是导致各种运行时错误和不兼容行为的常见原因。
3. 官方文档：始终参考Elasticsearch官方文档获取最准确和最新的客户端信息、依赖配置和使用指南。Baeldung等第三方教程可能不会及时更新以反映Elasticsearch客户端的最新变化。
4. 避免混淆：核心的org.elasticsearch:elasticsearch依赖不提供客户端API。不要期望通过它找到ClientConfiguration或RestHighLevelClient等类。

通过理解Elasticsearch Java客户端的演进和正确的依赖管理，您可以避免常见的ClassNotFoundException问题，并高效地构建与Elasticsearch交互的Java应用程序。