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 通信、连接池和节点选择。

下面是可直接使用的 Maven 配置。jackson-databind 用于把 Java 对象与 JSON 相互转换,exec-maven-plugin 用于从命令行运行示例。
<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 建连等待时间,读取超时用于限制服务端响应等待时间,连接请求超时用于限制从连接池获取连接的等待时间。
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> 必须替换为真实密码,不要把生产凭据写进源码或提交到仓库。
export ES_URL="http://localhost:9200"
export ES_USERNAME="elastic"
export ES_PASSWORD="<PASSWORD>"
mvn -q compile exec:java -Dexec.mainClass=com.example.ElasticsearchClientDemo预期输出如下,集群名与补丁版本会随环境变化。
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请求可以快速验证地址、认证和网络链路是否正确
下一课预告
下一课将基于已建立的客户端完成索引创建,以及文档的写入、查询、更新和删除,并验证每一步的实际结果。