NoSQL 与搜索 / 系统课时

Java 客户端初始化

Java 客户端初始化

本课完成一个可复用的 Elasticsearch Java 客户端:引入官方依赖,配置节点地址、Basic 认证、连接与读取超时,并通过连接池复用 HTTP 连接。完成后可直接执行 info 请求验证连接是否可用。

学习目标

  • 正确引入 Elasticsearch Java API Client 及 JSON 映射依赖
  • 配置服务地址、认证、超时和连接池参数
  • 理解客户端生命周期并完成连通性验证

选择客户端与版本

示例使用 Java 17 和 elasticsearch-java:8.19.16。客户端版本应尽量与 Elasticsearch 服务端保持相同主版本和次版本,避免请求类型或新增字段不匹配。Java API Client 负责强类型 API,底层 RestClient 负责 HTTP 通信、连接池和节点选择。

Java 客户端、传输层与连接池关系

下面是可直接使用的 Maven 配置。jackson-databind 用于把 Java 对象与 JSON 相互转换,exec-maven-plugin 用于从命令行运行示例。

xml
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.example</groupId>
    <artifactId>elasticsearch-java-demo</artifactId>
    <version>1.0.0</version>

    <properties>
        <maven.compiler.release>17</maven.compiler.release>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <dependencies>
        <dependency>
            <groupId>co.elastic.clients</groupId>
            <artifactId>elasticsearch-java</artifactId>
            <version>8.19.16</version>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
            <version>2.17.0</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>exec-maven-plugin</artifactId>
                <version>3.5.0</version>
            </plugin>
        </plugins>
    </build>
</project>

保存后刷新 Maven 项目。依赖解析成功且 mvn -q -DskipTests package 没有报错,即表示构建配置生效。

初始化并验证连接

下面的程序从环境变量读取连接信息,统一创建一个客户端。连接超时用于限制 TCP 建连等待时间,读取超时用于限制服务端响应等待时间,连接请求超时用于限制从连接池获取连接的等待时间。

java
package com.example;

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.apache.http.auth.AuthScope;
import org.apache.http.auth.UsernamePasswordCredentials;
import org.apache.http.impl.client.BasicCredentialsProvider;
import org.elasticsearch.client.RestClient;
import org.elasticsearch.client.RestClientBuilder;

import java.net.URI;

public class ElasticsearchClientDemo {

    public static void main(String[] args) throws Exception {
        try (ElasticsearchClient client = createClient()) {
            var info = client.info();
            System.out.println("Connected cluster: " + info.clusterName());
            System.out.println("Elasticsearch version: " + info.version().number());
        }
    }

    private static ElasticsearchClient createClient() {
        URI endpoint = URI.create(requiredEnv("ES_URL"));
        String username = requiredEnv("ES_USERNAME");
        String password = requiredEnv("ES_PASSWORD");
        int port = endpoint.getPort() > 0
                ? endpoint.getPort()
                : ("https".equalsIgnoreCase(endpoint.getScheme()) ? 443 : 80);

        BasicCredentialsProvider credentials = new BasicCredentialsProvider();
        credentials.setCredentials(
                AuthScope.ANY,
                new UsernamePasswordCredentials(username, password)
        );

        RestClientBuilder builder = RestClient.builder(
                new HttpHost(endpoint.getHost(), port, endpoint.getScheme())
        );

        builder.setRequestConfigCallback(request -> request
                .setConnectTimeout(5_000)
                .setSocketTimeout(30_000)
                .setConnectionRequestTimeout(2_000));

        builder.setHttpClientConfigCallback(http -> http
                .setDefaultCredentialsProvider(credentials)
                .setMaxConnTotal(50)
                .setMaxConnPerRoute(20)
                .setKeepAliveStrategy((response, context) -> 60_000L));

        RestClient restClient = builder.build();
        ElasticsearchTransport transport = new RestClientTransport(
                restClient,
                new JacksonJsonpMapper()
        );
        return new ElasticsearchClient(transport);
    }

    private static String requiredEnv(String name) {
        String value = System.getenv(name);
        if (value == null || value.isBlank()) {
            throw new IllegalArgumentException("Missing environment variable: " + name);
        }
        return value;
    }
}

在 Linux 或 macOS 终端中设置实际连接信息后运行。<PASSWORD> 必须替换为真实密码,不要把生产凭据写进源码或提交到仓库。

bash
export ES_URL="http://localhost:9200"
export ES_USERNAME="elastic"
export ES_PASSWORD="<PASSWORD>"
mvn -q compile exec:java -Dexec.mainClass=com.example.ElasticsearchClientDemo

预期输出如下,集群名与补丁版本会随环境变化。

text
Connected cluster: <CLUSTER_NAME>
Elasticsearch version: 8.19.<PATCH>

生命周期与典型失败

客户端和底层连接池都是线程安全的,应用中通常只创建一个实例,并在应用停止时关闭。不要在每次查询前重新创建客户端,否则会反复建立 TCP 连接、增加延迟,并可能耗尽文件描述符。

出现 401 Unauthorized 时先核对用户名、密码和用户权限;出现连接超时时检查地址、端口、防火墙和 Elasticsearch 监听配置;HTTPS 环境出现 PKIX path building failed 时,应把集群 CA 加入 JVM 信任链,而不是关闭证书校验。

本课总结

  • Java API Client 提供强类型接口,底层 REST 客户端负责认证、超时和连接复用
  • 客户端应作为应用级单例长期复用,并在应用关闭时释放资源
  • 使用 info 请求可以快速验证地址、认证和网络链路是否正确

下一课预告

下一课将基于已建立的客户端完成索引创建,以及文档的写入、查询、更新和删除,并验证每一步的实际结果。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

Java 客户端初始化

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通