Spring Boot集成Elasticsearch需严格对齐版本、配置连接、映射实体并选择查询方式；常见问题为版本错配、分词失效和连接超时。
Spring Boot 集成 Elasticsearch 的核心是版本对齐、连接配置、实体映射和查询方式选择。只要把这四步理清楚，集成过程并不复杂，但版本错配、分词失效、连接超时这几类问题最常导致启动失败或查不到结果。
确认版本兼容性（最关键一步）
Spring Boot、Spring Data Elasticsearch 和 Elasticsearch 服务端三者必须严格匹配，否则项目根本起不来：
- Spring Boot 3.x → Spring Data Elasticsearch 5.x → Elasticsearch 8.x（推荐新项目用）
- Spring Boot 2.7.x → Spring Data Elasticsearch 4.4.x → Elasticsearch 7.17.x（老项目维护常用）
- 检查方式：运行
curl http://localhost:9200查看 ES 返回的version.number；再核对pom.xml中 Spring Boot 的 parent version - 不建议手动降级或混搭，比如 Spring Boot 3 + ES 7，容易触发
ClassNotFoundException或RestClientException
部署并配置 Elasticsearch 服务
开发环境推荐用 Docker 快速启动单节点，关闭安全认证简化调试：
- 拉取镜像：
docker pull elasticsearch:8.15.2 - 启动容器（含中文分词支持）：
docker run -d --name es8 -p 9200:9200 -e "discovery.type=single-node" -e "xpack.security.enabled=false" -e "ES_JAVA_OPTS=-Xms512m -Xmx512m" -v /path/to/plugins:/usr/share/elasticsearch/plugins elasticsearch:8.15.2 - 安装 IK 分词器（版本必须完全一致）：
bin/elasticsearch-plugin install https://release.infinilabs.com/analysis-ik/stable/elasticsearch-analysis-ik-8.15.2.zip - 验证：
curl "http://localhost:9200/_cat/health?v"返回green即健康
添加依赖与配置连接参数
Maven 引入官方 starter 即可，它会自动装配新版 Java API Client（ES 8 推荐）：
<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-data-elasticsearch</artifactId> </dependency>
在 application.yml 中配置地址和超时：
spring:
elasticsearch:
uris: http://127.0.0.1:9200
connection-timeout: 10s
socket-timeout: 30s
logging:
level:
org.springframework.data.elasticsearch: DEBUG
如需账号密码（生产环境），补充 username 和 password 字段即可。
定义文档实体与实现搜索逻辑
用注解声明索引结构，字段类型要按语义区分：
-
@Document(indexName = "product", createIndex = true)：自动建索引，名称全小写 -
@Id标记主键（对应 ES 的_id） - 文本字段用
@Field(type = FieldType.TEXT, analyzer = "ik_max_word")启用中文分词 - 精确匹配字段（如状态、分类 ID）用
FieldType.KEYWORD，避免被分词
搜索时优先用 ElasticsearchOperations（替代已废弃的 ElasticsearchRestTemplate）写 DSL 查询，例如组合条件+高亮：
Query query = NativeQuery.builder()
.withQuery(q -> q.bool(b -> b
.must(t -> t.match(m -> m.field("title").query("手机")))
.filter(f -> f.range(r -> r.field("price").gte(JsonData.of(1000)))))
.withHighlightBuilder(h -> h.field("title"))
.build();
不复杂但容易忽略
