如何配置Java的Elasticsearch环境并接入RestHighLevelClient

在Java项目中接入Elasticsearch并使用RestHighLevelClient进行开发，需要先完成环境搭建和客户端配置工作，整个过程涉及依赖管理、客户端初始化、功能验证三个核心环节。不同版本的Elasticsearch需要匹配对应版本的客户端依赖，否则会出现兼容性问题导致连接失败。

环境准备

首先需要确保本地已经安装并启动了Elasticsearch服务，同时记录服务的访问地址和端口，默认情况下Elasticsearch的HTTP访问端口为9200。如果你的Elasticsearch配置了安全认证，还需要提前准备好用户名和密码，后续客户端配置时会用到这些信息。

引入依赖

在Maven项目的pom.xml文件中添加RestHighLevelClient的依赖，注意依赖版本需要和你的Elasticsearch服务版本保持一致，例如Elasticsearch服务版本为7.17.0，客户端版本也选择7.17.0即可，避免版本不兼容问题。

<dependency>
    <groupId>org.elasticsearch.client</groupId>
    <artifactId>elasticsearch-rest-high-level-client</artifactId>
    <version>7.17.0</version>
</dependency>
<dependency>
    <groupId>org.elasticsearch</groupId>
    <artifactId>elasticsearch</artifactId>
    <version>7.17.0</version>
</dependency>

如果是Gradle项目，则在build.gradle文件中添加如下依赖：

dependencies {
    implementation 'org.elasticsearch.client:elasticsearch-rest-high-level-client:7.17.0'
    implementation 'org.elasticsearch:elasticsearch:7.17.0'
}

初始化RestHighLevelClient

依赖引入完成后，就可以编写代码初始化RestHighLevelClient实例了。初始化时需要配置Elasticsearch服务的访问地址，如果有多个节点可以添加多个HttpHost实例。

无安全认证的配置方式

如果Elasticsearch没有开启安全认证，直接使用服务地址和端口初始化即可：

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

public class EsClientUtil {
    private static RestHighLevelClient client;

    public static RestHighLevelClient getClient() {
        if (client == null) {
            // 初始化客户端，配置Elasticsearch服务地址和端口
            client = new RestHighLevelClient(
                RestClient.builder(
                    new HttpHost("127.0.0.1", 9200, "http")
                    // 如果有多个节点，可以继续添加new HttpHost实例
                )
            );
        }
        return client;
    }

    // 关闭客户端的方法
    public static void closeClient() {
        if (client != null) {
            try {
                client.close();
            } catch (Exception e) {
                e.printStackTrace();
            }
        }
    }
}

有安全认证的配置方式

如果Elasticsearch开启了安全认证，需要在初始化时添加认证信息：

import org.apache.http.HttpHost;
import org.apache.http.auth.AuthScope;
import org.apache.http.auth.UsernamePasswordCredentials;
import org.apache.http.client.CredentialsProvider;
import org.apache.http.impl.client.BasicCredentialsProvider;
import org.elasticsearch.client.RestClient;
import org.elasticsearch.client.RestHighLevelClient;

public class EsClientUtil {
    private static RestHighLevelClient client;

    public static RestHighLevelClient getClient() {
        if (client == null) {
            // 配置认证信息
            final CredentialsProvider credentialsProvider = new BasicCredentialsProvider();
            credentialsProvider.setCredentials(AuthScope.ANY,
                new UsernamePasswordCredentials("elastic", "your_password"));

            // 初始化客户端时传入认证配置
            client = new RestHighLevelClient(
                RestClient.builder(new HttpHost("127.0.0.1", 9200, "http"))
                    .setHttpClientConfigCallback(httpClientBuilder -> 
                        httpClientBuilder.setDefaultCredentialsProvider(credentialsProvider))
            );
        }
        return client;
    }

    public static void closeClient() {
        if (client != null) {
            try {
                client.close();
            } catch (Exception e) {
                e.printStackTrace();
            }
        }
    }
}

验证客户端连接

初始化完成后，可以编写一个简单的测试方法验证客户端是否能够正常连接Elasticsearch服务，比如获取集群的健康状态信息。

import org.elasticsearch.action.admin.cluster.health.ClusterHealthRequest;
import org.elasticsearch.action.admin.cluster.health.ClusterHealthResponse;
import org.elasticsearch.client.RequestOptions;
import org.elasticsearch.client.RestHighLevelClient;

public class EsTest {
    public static void main(String[] args) {
        RestHighLevelClient client = EsClientUtil.getClient();
        try {
            // 创建集群健康请求
            ClusterHealthRequest request = new ClusterHealthRequest();
            // 执行请求获取响应
            ClusterHealthResponse response = client.cluster().health(request, RequestOptions.DEFAULT);
            // 输出集群状态
            System.out.println("集群状态：" + response.getStatus().toString());
            System.out.println("集群名称：" + response.getClusterName());
        } catch (Exception e) {
            e.printStackTrace();
        } finally {
            // 关闭客户端
            EsClientUtil.closeClient();
        }
    }
}

如果运行后能够正常输出集群的状态和名称，说明RestHighLevelClient已经成功接入，后续就可以使用该客户端进行索引创建、文档增删改查等操作了。

常见问题排查

• 如果出现NoNodeAvailableException异常，首先检查Elasticsearch服务是否正常运行，访问地址和端口是否正确，防火墙是否放行了对应端口。
• 如果出现版本冲突异常，检查客户端依赖版本和Elasticsearch服务版本是否匹配，尽量保持两者主版本和次版本一致。
• 如果开启了安全认证仍然连接失败，检查用户名和密码是否正确，以及Elasticsearch的认证配置是否生效。

ElasticsearchRestHighLevelClientJava环境配置修改时间：2026-07-20 01:30:29