[特殊字符] Java 集成 Elasticsearch 实战指南

方式一：Spring Boot + Spring Data Elasticsearch（最推荐，开发效率极高）

如果你使用的是 Spring Boot 框架，强烈推荐使用 Spring Data Elasticsearch，它能像操作 JPA 一样操作 ES，极大简化开发。1. 引入 Maven 依赖在你的 pom.xml 中引入核心 starter 依赖：

复制代码

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-elasticsearch</artifactId>
</dependency>

注意：Spring Boot、Spring Data Elasticsearch 和 Elasticsearch 服务端之间有严格的版本对应关系，建议查阅官方文档保持版本兼容（例如 Spring Boot 3.x 对应 ES 8.x，Spring Boot 2.7.x 对应 ES 7.17.x）。

配置 application.yml在配置文件中指定 ES 服务的地址（ES 8.x 默认开启了安全认证，本地测试可以关闭，生产环境需配置用户名密码）：

spring:
elasticsearch: uris: http://localhost:9200 # 如果开启了安全认证，需要配置以下两项 # username: elastic # password: your_password[[source_group_web_4]]**3. 定义实体类（映射索引）**创建一个实体类，使用注解将其映射到 ES 的索引：javaimport org.springframework.data.annotation.Id;import org.springframework.data.elasticsearch.annotations.Document;@Document(indexName = "user") // 指定索引名称，相当于数据库的表名public class User { @Id private String id; // 文档ID private String name; private String phone; private String email; // 省略 getter 和 setter}[[source_group_web_5]]**4. 编写 Repository 接口**继承 `ElasticsearchRepository`，即可获得基础的 CRUD 能力，还可以根据方法名自动生成查询：javaimport org.springframework.data.elasticsearch.repository.ElasticsearchRepository;import java.util.List;public interface UserRepository extends ElasticsearchRepository<User, String> { // 根据名字进行模糊搜索（全文检索） List<User> findByNameContaining(String name);}[[source_group_web_6]]**5. 业务层调用与测试**直接在 Service 或测试类中注入 Repository 使用：java@SpringBootTestclass EsIntegrationTest { @Autowired private UserRepository userRepository; // 写入数据 @Test void saveUser() { User user = new User(); user.setId("1"); user.setName("张三"); user.setPhone("13800138000"); userRepository.save(user); } // 查询数据 @Test void searchUser() { List<User> users = userRepository.findByNameContaining("张"); users.forEach(System.out::println); }}[[source_group_web_7]]---#### 方式二：Elasticsearch 官方原生 Java API Client（适合 ES 8.x+）如果你没有使用 Spring Boot，或者需要更精细地控制 ES 的原生 API，可以使用官方推荐的新一代 Java API Client[[source_group_web_8]]。**1. 引入 Maven 依赖**xml<dependency> <groupId>co.elastic.clients</groupId> <artifactId>elasticsearch-java</artifactId> <version>8.11.0</version> </dependency><dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-databind</artifactId> <version>2.15.0</version></dependency>[[source_group_web_9]]**2. 初始化客户端（配置类）**javaimport 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.client.CredentialsProvider;import org.apache.http.impl.client.BasicCredentialsProvider;import org.elasticsearch.client.RestClient;public class EsClientConfig { public ElasticsearchClient createClient() { // 配置认证信息（ES 8.x 默认开启） final CredentialsProvider credentialsProvider = new BasicCredentialsProvider(); credentialsProvider.setCredentials(AuthScope.ANY, new UsernamePasswordCredentials("elastic", "your_password")); // 构建 RestClient RestClient restClient = RestClient.builder( new HttpHost("localhost", 9200, "http")) .setHttpClientConfigCallback(httpClientBuilder -> httpClientBuilder.setDefaultCredentialsProvider(credentialsProvider)) .build(); // 创建传输层和客户端 ElasticsearchTransport transport = new RestClientTransport( restClient, new JacksonJsonpMapper()); return new ElasticsearchClient(transport); }}[[source_group_web_10]]**3. 使用客户端进行文档操作**javaElasticsearchClient client = new EsClientConfig().createClient();// 索引（新增/修改）文档User user = new User();user.setId("1");user.setName("李四");client.index(i -> i .index("user") .id(user.getId()) .document(user));// 搜索文档var searchResponse = client.search(s -> s .index("user") .query(q -> q .match(t -> t .field("name") .query("李四") ) ), User.class);```[[source_group_web_11]]---#### 💡 避坑与注意事项1. 版本兼容性：这是新手最容易踩的坑。务必保证 Java 客户端版本与 ES 服务端版本一致（尤其是大版本号），否则极易出现 API 不兼容或连接报错[[source_group_web_12]]。2. 废弃的客户端：老版本的 TransportClient 已经在 ES 7.x 后被废弃，RestHighLevelClient 在 ES 8.x 后也逐步被新的 elasticsearch-java 客户端取代。新项目建议直接上手 Spring Data Elasticsearch 或官方新一代 Java API Client[[source_group_web_13]]。3. 本地环境搭建：本地测试推荐使用 Docker 快速启动单节点 ES，命令如：docker run -d --name es -p 9200:9200 -e "discovery.type=single-node" -e "xpack.security.enabled=false" docker.elastic.co/elasticsearch/elasticsearch:8.12.0