简介面向需要将Spring Boot应用接入Elasticsearch 7.2.0的Java开发人员这份PDF文档围绕版本兼容痛点系统讲解从Spring Boot 2.1.X默认依赖与ES版本错配到改采Spring-data-elasticsearch与RestHighLevelClient的完整实现思路。文章对比了传输层transport与REST两种连接方式说明官方推荐及后续废弃策略并给出依赖坐标、application.yml配置及客户端连接类等关键代码其中也包含连接超时与请求超时等参数设置细节。文档中的配置类示例清晰展示了RestHighLevelClient的初始化过程能帮助减少调试连接问题的时间。这份资料可帮助开发者避开版本对应关系不一致的常见坑为日志检索、全文搜索、站内搜索等场景快速搭建可用的Elasticsearch客户端环境也适合在学习搜索引擎集成或项目升级时作为速查参考。压缩包仅含1个PDF文档体积约58KB内容聚焦无冗余便于移动端阅读目前已有6768人学习下载。1. 整合 Elasticsearch 7.2.0 为什么是 springboot 项目里最容易被版本坑一环搜索引擎这块Elasticsearch 在 7.2.0 这个版本上其实是个分水岭6.x 时代常用的 TransportClient 在 7.0 被标记废弃8.0 直接移除同时 Spring Data Elasticsearch 的版本对应关系又极其挑剔SpringBoot 2.1.x 对应 ES 7.x 早期版本SpringBoot 2.2.x 对应 7.6中间错一个版本启动时要么连不上、要么序列化直接抛异常。很多人从网上拷贝一段依赖就开干结果卡在版本兼容上长达一天这是整个 springboot 整合 Elasticsearch 7.2.0 的过程里最消耗人耐心的一关。这篇文章定位很明确用 SpringBoot 把 Elasticsearch 7.2.0 跑通、跑稳并覆盖写接口、查接口、分页、高亮、聚合、批量写入和索引重建。读者如果是第一次做 ES 整合跟着章节顺序搭环境即可如果已经跑通但查询性能不理想或者老遇到列名映射问题直接跳到第 5 章和第 6 章那里的参数和场景对照表能省下不少排查时间。2. 整合前先做对选择题版本对应、依赖坐标和两条路线2.1 SpringBoot 与 ES 7.2.0 的版本硬对应关系Spring Data Elasticsearch 的版本号不会和 Elasticsearch 完全对齐它通过内部一套映射关系来适配。常见的版本对应如下表这也是排查报错时第一份需要对照的清单SpringBoot 版本Spring Data Elasticsearch 版本兼容的 ES 版本2.1.x3.2.xES 7.2.0 可用2.2.x3.3.xES 7.6 首选2.3.x4.0.xES 7.62.4.x4.1.xES 7.9要做 ES 7.2.0最稳的组合是 SpringBoot 2.1.x 或手动锁定 spring-data-elasticsearch 3.2.x 坐标。如果项目已经被迫使用 SpringBoot 2.2 或更高版本你依然可以把 ES 版本固定在 7.2.0前提是不要使用 Spring Data 自动装配的 TransportClient完全转向 RestHighLevelClient。我一般会先跑一个最小启动类确认 Spring Data ES 版本确实被解析到了预期版本再往下推进业务代码。这个做法很笨却能过滤掉大量后续的“找到一个坑修一个坑”的无谓消耗。2.2 两条整合路线RestHighLevelClient 与 Spring Data Elasticsearch 的取舍SpringBoot 整合 ES 7.2.0 常见有两条路线。一条是 Spring Data Elasticsearch 的 Repository 风格适合纯粹的增删改查与简单条件查询。它的优点是无需手写查询 DSL甚至不需要自己 new RestHighLevelClient框架自动帮你注入 ElasticsearchRestTemplate。缺点也很明显——一旦需要复杂 bool 嵌套、聚合桶、高亮解析Spring Data 的抽象会变得很绕生成的查询也未必符合预期性能问题一旦出现排查难度反而上升。另一条路线是原生 RestHighLevelClient。它是 ES 官方 Java 客户端语义与 REST API 一一对应查询 JSON 怎么写代码就怎么写逻辑完全透明。代价是一切都要自己搭连接配置、索引初始化、查询响应解析、分页逻辑没有自动实体映射。综合来看推荐做法是CRUD 用 Spring Data 提速复杂检索用 RestHighLevelClient 兜底。两种方式共存于同一个项目没有任何冲突这也是我目前在多数 springboot 项目里采用的标准结构。2.3 在 pom.xml 里正确引入依赖坐标以 SpringBoot 2.1.5.RELEASE 为例子以下是同时支持两条路线的依赖配置parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version2.1.5.RELEASE/version /parent dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-data-elasticsearch/artifactId /dependency dependency groupIdorg.elasticsearch.client/groupId artifactIdelasticsearch-rest-high-level-client/artifactId version7.2.0/version /dependency dependency groupIdorg.elasticsearch/groupId artifactIdelasticsearch/artifactId version7.2.0/version /dependency dependency groupIdcom.alibaba/groupId artifactIdfastjson/artifactId version1.2.83/version /dependency /dependenciesspring-boot-starter-data-elasticsearch 这个 starter 会自动引入一个 Spring Data ES 版本它很可能不是你想要的 3.2.x。此时最直接的做法是在 properties 节点中强制锁定版本号properties spring-data-elasticsearch.version3.2.0.RELEASE/spring-data-elasticsearch.version /properties另外elasticsearch-rest-high-level-client 与 elasticsearch 两个坐标的版本必须保持一致否则运行时会报 Jackson 序列化层面的 NoClassDefFoundError。fastjson 不是必须的但在做批量写入时能把实体序列化成 JSON 字符串代码量会少很多推荐引入。3. 用 Spring Data Elasticsearch 快速跑通第一个索引和 CRUD3.1 在 application.yml 里配置连接参数Spring Data Elasticsearch 在 SpringBoot 2.1.x 使用的是 spring.data.elasticsearch 前缀而不是有些老博客里提到的 spring.elasticsearch。这个前缀写错应用能启动但 ES 连接永远是 localhost:9300然后报连接超时。spring: data: elasticsearch: cluster-name: docker-cluster cluster-nodes: 192.168.1.10:9300 repositories: enabled: true注意这里配置的是 9300 端口这是 TransportClient 的端口。Spring Data ES 3.2.x 在 SpringBoot 2.1.x 下确实默认走 TransportClient所以如果你没有在依赖中接入 RestHighLevelClient 的话会面临 ES 7.2.0 已经不推荐 TransportClient 的问题。为了避免把时间浪费在废弃客户端上我一般不会只配这个 yml还会配合手动注入 RestHighLevelClient 来使用 RestClient 风格的连接并配置 9200 端口Configuration public class EsRestClientConfig { Value(${elasticsearch.host:127.0.0.1}) private String host; Value(${elasticsearch.port:9200}) private Integer port; Bean(destroyMethod close) public RestHighLevelClient restHighLevelClient() { return new RestHighLevelClient( RestClient.builder(new HttpHost(host, port, http)) ); } }两个配置并存不会冲突Spring Data 负责实体映射和 RepositoryRestHighLevelClient 负责手动查询。注意新版高版本客户端在建立连接时如果 ES 端没有开 http也就是默认的 9200 端口没有监听那么所有调用都会报 Connection refused。3.2 定义实体类与索引映射ES 7.x 中 type 概念已经弱化Spring Data ES 3.2.x 默认索引类型为 _doc。实体类写法如下Document(indexName product, shards 3, replicas 1) public class Product { Id private String id; Field(type FieldType.Text, analyzer ik_max_word) private String name; Field(type FieldType.Keyword) private String brand; Field(type FieldType.Double) private Double price; Field(type FieldType.Date) private Date createTime; // getter setter 省略 }Document 指定索引名。shards 与 replicas 在索引首次创建时生效之后修改需要走索引重建。Field 里的 analyzer 指定了中文分词器这里用 ik_max_word 是常见做法前提是 ES 端已安装 IK 分词插件否则索引创建时会直接报错。price 用 Double 是因为 ES 7.2.0 对数值类型默认不支持 float 与 double 做精确匹配除非在 mapping 中单独声明为 keyword。首次启动项目时Spring Data 会依据实体自动创建索引。这个行为由 spring.data.elasticsearch.repositories.enabled 控制但索引结构一旦创建后面修改字段类型不会自动更新这属于 ES 的常见限制需要走重建索引流程这块偏后边第 6 章我再细说。3.3 使用 Repository 实现增删改查定义接口继承 ElasticsearchRepository泛型第一个参数是实体类第二个是主键类型public interface ProductRepository extends ElasticsearchRepositoryProduct, String { ListProduct findByName(String name); ListProduct findByNameAndBrand(String name, String brand); PageProduct findByPriceBetween(Double min, Double max, Pageable pageable); Query({\bool\: {\must\: [{\match\: {\name\: \?0\}}]}}) PageProduct searchByName(String name, Pageable pageable); }ElasticsearchRepository 内置了 save、findById、findAll、deleteById 等基础方法无需额外实现。方法命名规则与 Spring Data JPA 非常相似支持 And、Or、Between、Like 等关键字框架会自动生成查询 DSL。上述代码里的 findByPriceBetween 返回 Page配合 PageRequest.of(0, 10) 就能实现带分页的区间查询。Query 注解适合手动编写 JSON 查询语句?0 表示第一个参数占位符。在开发阶段我个人比较推荐对 core 查询用 Query 明确定义 DSL因为一旦实体字段多方法名自动生成的查询语义会变得难以确认而手写 JSON 字段与 ES 返回结构一致参数好不好排查一眼就能看出来。Service public class ProductService { Resource private ProductRepository productRepository; public Product save(Product product) { return productRepository.save(product); } public void delete(String id) { productRepository.deleteById(id); } public PageProduct search(String name, int page, int size) { return productRepository.findByName(name, PageRequest.of(page, size)); } }这种写法的缺点是隔离性不好如果查询条件一变比如动态拼接多个 should、mustRepository 的方法签名会变得难以维护。所以接下来第 4 章是你在实际项目中真正要被考验的部分——复杂查询。4. 用 RestHighLevelClient 构建复杂检索bool 组合、高亮与分页4.1 为什么复杂场景必须回到 RestHighLevelClientSpring Data 的方法名推导遇到超过两个条件就已显得生硬如果条件里还有 should、filter、range 的混排方法名越长越难读生成的 DSL 也难以预料。RestHighLevelClient 完全规避了这个问题查询怎么写代码就是什么结构。它还支持异步调用与 scroll 滚动查询适合大数据量导出。初始化方式已在第 2 章写了配置类这里直接把 client 注入到 Service 使用Service public class ProductSearchService { Resource private RestHighLevelClient client; public ListProduct searchByCondition(SearchCondition condition) throws IOException { SearchRequest searchRequest new SearchRequest(product); SearchSourceBuilder sourceBuilder new SearchSourceBuilder(); BoolQueryBuilder boolQuery QueryBuilders.boolQuery(); boolQuery.must(QueryBuilders.matchQuery(name, condition.getName())); boolQuery.filter(QueryBuilders.termQuery(brand, condition.getBrand())); boolQuery.filter(QueryBuilders.rangeQuery(price).gte(condition.getMinPrice())); sourceBuilder.query(boolQuery); sourceBuilder.from(condition.getPage() * condition.getSize()); sourceBuilder.size(condition.getSize()); searchRequest.source(sourceBuilder); SearchResponse response client.search(searchRequest, RequestOptions.DEFAULT); return parseResponse(response); } }BoolQueryBuilder 是 7.2.0 中组合查询的核心入口。must 对应 AND 语义must 里的 match 查询会做分词匹配。这里品牌用的是 termQuery因为品牌在实体里声明为了 keyword不分词用 term 才能精确匹配。filter 与 must 的区别在于 filter 不计算相关度分数查询速度更快且可以被 ES 缓存。所以范围过滤、状态过滤等不影响排序的硬性条件建议一律放入 filter 中。4.2 同时返回关键词高亮片段搜索引擎场景有一个高频需求搜索命中的关键词需要在前端标红展示。ES 高亮原理是在查询时指定字段名ES 返回该字段中命中的片段。RestHighLevelClient 的写法如下public MapString, Object searchWithHighlight(SearchCondition condition) throws IOException { SearchRequest searchRequest new SearchRequest(product); SearchSourceBuilder sourceBuilder new SearchSourceBuilder(); BoolQueryBuilder boolQuery QueryBuilders.boolQuery(); boolQuery.must(QueryBuilders.matchQuery(name, condition.getKeyword())); sourceBuilder.query(boolQuery); HighlightBuilder highlightBuilder new HighlightBuilder(); HighlightBuilder.Field highlightName new HighlightBuilder.Field(name); highlightName.preTags(span stylecolor:red); highlightName.postTags(/span); highlightBuilder.field(highlightName); sourceBuilder.highlighter(highlightBuilder); searchRequest.source(sourceBuilder); SearchResponse response client.search(searchRequest, RequestOptions.DEFAULT); MapString, Object result new HashMap(); ListMapString, Object list new ArrayList(); for (SearchHit hit : response.getHits().getHits()) { MapString, Object source hit.getSourceAsMap(); source.put(highlightName, hit.getHighlightFields() .get(name) .fragments()[0] .string()); list.add(source); } result.put(list, list); result.put(total, response.getHits().getTotalHits().value); return result; }高亮字段有三个常见翻车点需要提一下字段类型必须是 Textkeyword 类型无法高亮查询时如果有多个条件但高亮只对包含关键词的字段生效不要对 filter 字段声明高亮preTags 与 postTags 如果不设置默认返回标签很多前端框架需要自定义样式所以建议在服务端直接拼接好带色 HTML 或约定标签交由前端处理。fragments()[0] 需要判空因为当高亮字段没有命中时fragments 数组是空的直接取下标会抛 ArrayIndexOutOfBoundsException。4.3 7.2.0 的分页细节from.size 与最大窗口限制ES 分页有两种常用方式。一是 from size 浅分页适合页面跳转页码越深性能越差。二是 search_after 深分页适合 app 下拉加载与后台导出场景。7.2.0 的默认限制是 from size 不能超过 10000这个参数是 index 级别的 max_result_window 控制的。public ListProduct searchByScrollAfter(String lastSortValue, int size) throws IOException { SearchRequest searchRequest new SearchRequest(product); SearchSourceBuilder sourceBuilder new SearchSourceBuilder(); sourceBuilder.query(QueryBuilders.matchAllQuery()); sourceBuilder.size(size); sourceBuilder.sort(price, SortOrder.ASC); if (StringUtils.isNotBlank(lastSortValue)) { sourceBuilder.searchAfter(new Object[]{new BigDecimal(lastSortValue)}); } searchRequest.source(sourceBuilder); SearchResponse response client.search(searchRequest, RequestOptions.DEFAULT); ListProduct list new ArrayList(); for (SearchHit hit : response.getHits().getHits()) { list.add(JSONObject.parseObject(hit.getSourceAsString(), Product.class)); } return list; }search_after 依赖排序字段生成一个全局唯一的游标值。翻页时把上一页最后一条记录里用于排序的值传回来替代 from 参数。这里排序字段用 price它可能出现相同值为了确保唯一建议在排序里追加一个 _id 字段作为最终排序条件。使用 search_after 时不能再指定 from这是 ES 的硬性要求。对于后台导出这种需要全量遍历的场景scroll API 才会更合适但 scroll 要求保持上下文ES 会维护一个快照长时间挂起会占用大量内存7.2.0 中不推荐超过 5 分钟。5. 整合 ES 7.2.0 的避坑清单5 个高频踩坑记录与修复5.1 启动报错Received fatal alert: protocol_version现象SpringBoot 项目启动正常但第一次调用 ES 接口时报错堆栈信息包含 Received fatal alert: protocol_version。原因这是 JDK 版本与 ES 7.2.0 传输层协议不兼容导致的坑。ES 7.2.0 的 TransportClient 底层 Netty 与 JDK 11 的 TLS 协议协商存在版本不匹配如果你恰好用 JDK 11 或更高版本跑项目这个问题极其典型。解决优先切换到 RestHighLevelClient它走 HTTP 协议不受 TransportClient 的 TLS 实现影响。如果项目里暂时离不开 Spring Data 的自动 Repository也可以把 JDK 降到 8 并明确使用 3.2.x 的 spring-data-elasticsearch。生产环境我推荐前者一劳永逸地避开这条废弃链路。5.2 max_result_window 超限Result window is too large现象分页查询访问了第 10000 条之后的数据ES 直接抛异常提示 Result window is too largefrom size must be less than or equal to 10000。原因ES 索引默认 max_result_window 为 10000超出这个范围的 fromsize 组合会被拦截。这个限制是索引级配置不是全局的需要针对具体索引修改。解决在 Kibana 或通过 REST API 修改索引设置PUT /product/_settings { index: { max_result_window: 100000 } }修改索引的 settings 不影响索引现有数据是热更新操作。但如果未来数据量继续增长把窗口调大治标不治本。更合理的方案是前后台分页用 search_after 或 scroll 替代 fromsize。我一般在业务量超过千万级才会把 max_result_window 调大并且只调到 5 万以内避免深度分页把内存耗光导致全文检索性能集体下降。5.3 集群无主节点导致索引创建卡死现象应用启动时创建索引卡住es 日志显示 red 状态或者日志反复出现 waiting for master node。原因ES 7.2.0 对集群健康度比旧版更敏感。单节点启动时如果 discovery.type 不是 single-node节点会期待加入现有集群没有发现其他节点时不会自封为 master导致整个集群处于无主状态。解决单机开发环境启动时在 elasticsearch.yml 中设置discovery.type: single-node如果是多节点测试环境确认所有节点配置了相同的 cluster.name 并且网络可互通。另外注意 Spring Data 配置里 cluster-name 必须与 elasticsearch.yml 中的 cluster.name 完全一致否则节点发现了也不会加入这个参数玄学味道比较重排错时优先检查两边字符串是否完全相等。5.4 IK 分词插件缺失导致索引创建失败现象实体类字段配置了 analyzer ik_max_word应用启动创建索引时报 MapperParsingException提示 Analyzer [ik_max_word] not found。原因ES 服务端没有安装 IK 分词插件但客户端实体仍然声明了该分词器。解决进入 ES 的 plugins 目录安装 IK 分词器需要选用与 ES 7.2.0 匹配的版本然后重启 ES./bin/elasticsearch-plugin install https://github.com/medcl/elasticsearch-analysis-ik/releases/download/v7.2.0/elasticsearch-analysis-ik-7.2.0.zip安装前先确认 ES 是否已经启用了 security 或证书校验如果有需要额外调整 rest client 的 SSL 配置。插件的版本必须与 ES 主版本完全一致7.2.0 的插件不能装到 7.3.0 上这与部分读者已有的 mysql、redis 类插件经验不同ES 插件对版本绑定非常严。5.5 实体字段与 ES 返回字段类型不一致导致反序列化报错现象查询接口报错异常堆栈是 ClassCastException 或者 JSON parse error提示 Long can not cast to Integer、BigDecimal 无法解析等。原因ES 数字类型与 Java 实体类型之间的映射不对。比如 ES 里字段映射成 long实体类却声明为 Integer反序列化时 fastjson 或 Jackson 的严格模式就会拒绝。另一个常见场景是 date 字段在 ES 中返回的时间戳格式与 Java Date 不兼容。解决先通过 Kibana 查看索引 mapping确认字段的实际类型再回来修改实体类。ES 7.2.0 的 Date 字段默认格式通常形如 yyyy-MM-dd HH:mm:ss 或 epoch_millisJava 侧要么用 Long 接收时间戳要么通过 JsonFormat 显式指定格式。数值字段统一定义为 BigDecimal 或 Long 能绕开多数精度问题不推荐用 float 存金额类字段浮点精度在 ES 聚合中会造成统计偏差这是实战中容易让人忽视的。另外 double 无法精确匹配等于特定值如果需要精确过滤就必须映射为 keyword。6. 进阶技巧批量写入、索引重建与聚合统计6.1 用 Bulk 批量写入 10 万级数据单条 save 在数据量上来后效率很低常见做法是用 BulkRequest 一次性提交成批数据。批量写入必须控制每批条数和数据大小7.2.0 建议每批 5000 到 10000 条或者单批数据量不超过 15MB。超过这个大小ES 的 HTTP 层会返回 413 或直接超时。public boolean bulkInsert(ListProduct products) throws IOException { BulkRequest bulkRequest new BulkRequest(); for (Product product : products) { bulkRequest.add(new IndexRequest(product) .id(product.getId()) .source(JSONObject.toJSONString(product), XContentType.JSON)); } BulkResponse response client.bulk(bulkRequest, RequestOptions.DEFAULT); if (response.hasFailures()) { log.error(批量插入失败: {}, response.buildFailureMessage()); return false; } return true; }BulkRequest 是顺序写入的如果中途有失败项hasFailures 会返回 trueES 会把失败原因拼接在 buildFailureMessage 中。注意单条失败不会中止整个批次的请求所以批量写入必需要处理部分失败的情况。整批处理失败时回滚 ES 本身不提供事务能力只能通过重试单个文档或对比日志与源数据这就是 ES 建立在最终一致性之上的现实天然无强事务只能靠业务侧补偿。批量写入前建议先关闭 refresh 间隔这个参数是写入速率的隐藏瓶颈。ES 默认每秒刷新一次索引数据量大的时候把 refresh_interval 临时设成 -1等待写入完成后调回 1s索引速度会有明显提升PUT /product/_settings { index: { refresh_interval: -1 } }6.2 索引重建流程字段类型改错的最佳后悔药ES 不支持直接修改字段类型这是新手最容易碰壁的地方。如果你在实体里把 price 声明成了 text 并且已经创建索引想要改成 double必须走重建索引。正确步骤是先基于新结构创建临时索引再通过 reindex 将数据复制过去最后切换别名。PUT /product_v2 { mappings: { properties: { name: { type: text, analyzer: ik_max_word }, brand: { type: keyword }, price: { type: double }, createTime: { type: date } } } } POST /_reindex { source: { index: product }, dest: { index: product_v2 } }reindex 是 ES 自带的数据搬迁接口它不会修改原索引。操作完成后应用层需要将搜索结果指向 product_v2推荐用索引别名 xuan。给索引起别名并让应用连接别名之后后续版本切换与回滚都只需要改别名业务代码不动POST /_aliases { actions: [ { add: { index: product_v2, alias: product_alias } }, { remove: { index: product, alias: product_alias } } ] }这样一来即使新索引有问题也可以快速把别名切回旧索引算得上是对付结构变更的一剂后悔药。需要注意 reindex 在数据量大时是异步行为在 Kibana 中可以查看 task API 的进度reindex 期间不要删除原索引避免失败后没有回退路径。6.3 一个基于 terms 聚合的统计用例聚合查询是搜索引擎比关系型数据库出色很多的能力7.2.0 的 rest client 支持各种聚合器。以按品牌统计商品数为例public MapString, Long aggregateByBrand() throws IOException { SearchRequest searchRequest new SearchRequest(product); SearchSourceBuilder sourceBuilder new SearchSourceBuilder(); sourceBuilder.size(0); sourceBuilder.aggregation(AggregationBuilders .terms(brand_count) .field(brand) .size(20)); searchRequest.source(sourceBuilder); SearchResponse response client.search(searchRequest, RequestOptions.DEFAULT); Terms brandCount response.getAggregations().get(brand_count); MapString, Long result new HashMap(); for (Terms.Bucket bucket : brandCount.getBuckets()) { result.put(bucket.getKeyAsString(), bucket.getDocCount()); } return result; }sourceBuilder.size(0) 表示不返回文档明细只返回聚合结果这一步能省下大量传输开销。terms 聚合的字段必须是 keyword 类型否则聚合报错或结果不符合预期。聚合桶数量通过 size 控制这里 20 代表只返回品牌计数最多的前 20 个桶而不是全部。聚合计算是基于 Lucene 的倒排索引性能远高于同等条件下关系型数据库的 group by这也是后端用 ES 做报表统计的核心原因。在我经手的项目里SpringBoot 打包后一般直接部署在容器中ES 服务单独部署在专用机器上。两者之间隔了一层网络应用层必须对 ES 调用做超时与降级不要无限等待我习惯给 RestHighLevelClient 的 RequestOptions 设置连接超时与 socket 超时ES 集群抖动时应用不至于整体卡死。设置方法如下RequestOptions.Builder options RequestOptions.DEFAULT.toBuilder(); options.setHttpAsyncResponseConsumerFactory( new HttpAsyncResponseConsumerFactory .HeapBufferedResponseConsumerFactory(30 * 1024 * 1024));这套组合下来SpringBoot 与 ES 7.2.0 的整合已经能覆盖日常开发中从简单 CRUD 到复杂检索、批量索引、聚合统计的大部分场景。做这类整合时保持一个习惯所有索引结构变动优先改映射字段而不是在代码里做兼容所有查询参数先在 Kibana 验证 DSL 再写进 java这个习惯帮我避开了无数坑希望帮到你。本文还有配套的精品资源点击获取 SpringBoot整合Elasticsearch 7.2.0实战：版本兼容、复杂检索与避坑指南
简介面向需要将Spring Boot应用接入Elasticsearch 7.2.0的Java开发人员这份PDF文档围绕版本兼容痛点系统讲解从Spring Boot 2.1.X默认依赖与ES版本错配到改采Spring-data-elasticsearch与RestHighLevelClient的完整实现思路。文章对比了传输层transport与REST两种连接方式说明官方推荐及后续废弃策略并给出依赖坐标、application.yml配置及客户端连接类等关键代码其中也包含连接超时与请求超时等参数设置细节。文档中的配置类示例清晰展示了RestHighLevelClient的初始化过程能帮助减少调试连接问题的时间。这份资料可帮助开发者避开版本对应关系不一致的常见坑为日志检索、全文搜索、站内搜索等场景快速搭建可用的Elasticsearch客户端环境也适合在学习搜索引擎集成或项目升级时作为速查参考。压缩包仅含1个PDF文档体积约58KB内容聚焦无冗余便于移动端阅读目前已有6768人学习下载。1. 整合 Elasticsearch 7.2.0 为什么是 springboot 项目里最容易被版本坑一环搜索引擎这块Elasticsearch 在 7.2.0 这个版本上其实是个分水岭6.x 时代常用的 TransportClient 在 7.0 被标记废弃8.0 直接移除同时 Spring Data Elasticsearch 的版本对应关系又极其挑剔SpringBoot 2.1.x 对应 ES 7.x 早期版本SpringBoot 2.2.x 对应 7.6中间错一个版本启动时要么连不上、要么序列化直接抛异常。很多人从网上拷贝一段依赖就开干结果卡在版本兼容上长达一天这是整个 springboot 整合 Elasticsearch 7.2.0 的过程里最消耗人耐心的一关。这篇文章定位很明确用 SpringBoot 把 Elasticsearch 7.2.0 跑通、跑稳并覆盖写接口、查接口、分页、高亮、聚合、批量写入和索引重建。读者如果是第一次做 ES 整合跟着章节顺序搭环境即可如果已经跑通但查询性能不理想或者老遇到列名映射问题直接跳到第 5 章和第 6 章那里的参数和场景对照表能省下不少排查时间。2. 整合前先做对选择题版本对应、依赖坐标和两条路线2.1 SpringBoot 与 ES 7.2.0 的版本硬对应关系Spring Data Elasticsearch 的版本号不会和 Elasticsearch 完全对齐它通过内部一套映射关系来适配。常见的版本对应如下表这也是排查报错时第一份需要对照的清单SpringBoot 版本Spring Data Elasticsearch 版本兼容的 ES 版本2.1.x3.2.xES 7.2.0 可用2.2.x3.3.xES 7.6 首选2.3.x4.0.xES 7.62.4.x4.1.xES 7.9要做 ES 7.2.0最稳的组合是 SpringBoot 2.1.x 或手动锁定 spring-data-elasticsearch 3.2.x 坐标。如果项目已经被迫使用 SpringBoot 2.2 或更高版本你依然可以把 ES 版本固定在 7.2.0前提是不要使用 Spring Data 自动装配的 TransportClient完全转向 RestHighLevelClient。我一般会先跑一个最小启动类确认 Spring Data ES 版本确实被解析到了预期版本再往下推进业务代码。这个做法很笨却能过滤掉大量后续的“找到一个坑修一个坑”的无谓消耗。2.2 两条整合路线RestHighLevelClient 与 Spring Data Elasticsearch 的取舍SpringBoot 整合 ES 7.2.0 常见有两条路线。一条是 Spring Data Elasticsearch 的 Repository 风格适合纯粹的增删改查与简单条件查询。它的优点是无需手写查询 DSL甚至不需要自己 new RestHighLevelClient框架自动帮你注入 ElasticsearchRestTemplate。缺点也很明显——一旦需要复杂 bool 嵌套、聚合桶、高亮解析Spring Data 的抽象会变得很绕生成的查询也未必符合预期性能问题一旦出现排查难度反而上升。另一条路线是原生 RestHighLevelClient。它是 ES 官方 Java 客户端语义与 REST API 一一对应查询 JSON 怎么写代码就怎么写逻辑完全透明。代价是一切都要自己搭连接配置、索引初始化、查询响应解析、分页逻辑没有自动实体映射。综合来看推荐做法是CRUD 用 Spring Data 提速复杂检索用 RestHighLevelClient 兜底。两种方式共存于同一个项目没有任何冲突这也是我目前在多数 springboot 项目里采用的标准结构。2.3 在 pom.xml 里正确引入依赖坐标以 SpringBoot 2.1.5.RELEASE 为例子以下是同时支持两条路线的依赖配置parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version2.1.5.RELEASE/version /parent dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-data-elasticsearch/artifactId /dependency dependency groupIdorg.elasticsearch.client/groupId artifactIdelasticsearch-rest-high-level-client/artifactId version7.2.0/version /dependency dependency groupIdorg.elasticsearch/groupId artifactIdelasticsearch/artifactId version7.2.0/version /dependency dependency groupIdcom.alibaba/groupId artifactIdfastjson/artifactId version1.2.83/version /dependency /dependenciesspring-boot-starter-data-elasticsearch 这个 starter 会自动引入一个 Spring Data ES 版本它很可能不是你想要的 3.2.x。此时最直接的做法是在 properties 节点中强制锁定版本号properties spring-data-elasticsearch.version3.2.0.RELEASE/spring-data-elasticsearch.version /properties另外elasticsearch-rest-high-level-client 与 elasticsearch 两个坐标的版本必须保持一致否则运行时会报 Jackson 序列化层面的 NoClassDefFoundError。fastjson 不是必须的但在做批量写入时能把实体序列化成 JSON 字符串代码量会少很多推荐引入。3. 用 Spring Data Elasticsearch 快速跑通第一个索引和 CRUD3.1 在 application.yml 里配置连接参数Spring Data Elasticsearch 在 SpringBoot 2.1.x 使用的是 spring.data.elasticsearch 前缀而不是有些老博客里提到的 spring.elasticsearch。这个前缀写错应用能启动但 ES 连接永远是 localhost:9300然后报连接超时。spring: data: elasticsearch: cluster-name: docker-cluster cluster-nodes: 192.168.1.10:9300 repositories: enabled: true注意这里配置的是 9300 端口这是 TransportClient 的端口。Spring Data ES 3.2.x 在 SpringBoot 2.1.x 下确实默认走 TransportClient所以如果你没有在依赖中接入 RestHighLevelClient 的话会面临 ES 7.2.0 已经不推荐 TransportClient 的问题。为了避免把时间浪费在废弃客户端上我一般不会只配这个 yml还会配合手动注入 RestHighLevelClient 来使用 RestClient 风格的连接并配置 9200 端口Configuration public class EsRestClientConfig { Value(${elasticsearch.host:127.0.0.1}) private String host; Value(${elasticsearch.port:9200}) private Integer port; Bean(destroyMethod close) public RestHighLevelClient restHighLevelClient() { return new RestHighLevelClient( RestClient.builder(new HttpHost(host, port, http)) ); } }两个配置并存不会冲突Spring Data 负责实体映射和 RepositoryRestHighLevelClient 负责手动查询。注意新版高版本客户端在建立连接时如果 ES 端没有开 http也就是默认的 9200 端口没有监听那么所有调用都会报 Connection refused。3.2 定义实体类与索引映射ES 7.x 中 type 概念已经弱化Spring Data ES 3.2.x 默认索引类型为 _doc。实体类写法如下Document(indexName product, shards 3, replicas 1) public class Product { Id private String id; Field(type FieldType.Text, analyzer ik_max_word) private String name; Field(type FieldType.Keyword) private String brand; Field(type FieldType.Double) private Double price; Field(type FieldType.Date) private Date createTime; // getter setter 省略 }Document 指定索引名。shards 与 replicas 在索引首次创建时生效之后修改需要走索引重建。Field 里的 analyzer 指定了中文分词器这里用 ik_max_word 是常见做法前提是 ES 端已安装 IK 分词插件否则索引创建时会直接报错。price 用 Double 是因为 ES 7.2.0 对数值类型默认不支持 float 与 double 做精确匹配除非在 mapping 中单独声明为 keyword。首次启动项目时Spring Data 会依据实体自动创建索引。这个行为由 spring.data.elasticsearch.repositories.enabled 控制但索引结构一旦创建后面修改字段类型不会自动更新这属于 ES 的常见限制需要走重建索引流程这块偏后边第 6 章我再细说。3.3 使用 Repository 实现增删改查定义接口继承 ElasticsearchRepository泛型第一个参数是实体类第二个是主键类型public interface ProductRepository extends ElasticsearchRepositoryProduct, String { ListProduct findByName(String name); ListProduct findByNameAndBrand(String name, String brand); PageProduct findByPriceBetween(Double min, Double max, Pageable pageable); Query({\bool\: {\must\: [{\match\: {\name\: \?0\}}]}}) PageProduct searchByName(String name, Pageable pageable); }ElasticsearchRepository 内置了 save、findById、findAll、deleteById 等基础方法无需额外实现。方法命名规则与 Spring Data JPA 非常相似支持 And、Or、Between、Like 等关键字框架会自动生成查询 DSL。上述代码里的 findByPriceBetween 返回 Page配合 PageRequest.of(0, 10) 就能实现带分页的区间查询。Query 注解适合手动编写 JSON 查询语句?0 表示第一个参数占位符。在开发阶段我个人比较推荐对 core 查询用 Query 明确定义 DSL因为一旦实体字段多方法名自动生成的查询语义会变得难以确认而手写 JSON 字段与 ES 返回结构一致参数好不好排查一眼就能看出来。Service public class ProductService { Resource private ProductRepository productRepository; public Product save(Product product) { return productRepository.save(product); } public void delete(String id) { productRepository.deleteById(id); } public PageProduct search(String name, int page, int size) { return productRepository.findByName(name, PageRequest.of(page, size)); } }这种写法的缺点是隔离性不好如果查询条件一变比如动态拼接多个 should、mustRepository 的方法签名会变得难以维护。所以接下来第 4 章是你在实际项目中真正要被考验的部分——复杂查询。4. 用 RestHighLevelClient 构建复杂检索bool 组合、高亮与分页4.1 为什么复杂场景必须回到 RestHighLevelClientSpring Data 的方法名推导遇到超过两个条件就已显得生硬如果条件里还有 should、filter、range 的混排方法名越长越难读生成的 DSL 也难以预料。RestHighLevelClient 完全规避了这个问题查询怎么写代码就是什么结构。它还支持异步调用与 scroll 滚动查询适合大数据量导出。初始化方式已在第 2 章写了配置类这里直接把 client 注入到 Service 使用Service public class ProductSearchService { Resource private RestHighLevelClient client; public ListProduct searchByCondition(SearchCondition condition) throws IOException { SearchRequest searchRequest new SearchRequest(product); SearchSourceBuilder sourceBuilder new SearchSourceBuilder(); BoolQueryBuilder boolQuery QueryBuilders.boolQuery(); boolQuery.must(QueryBuilders.matchQuery(name, condition.getName())); boolQuery.filter(QueryBuilders.termQuery(brand, condition.getBrand())); boolQuery.filter(QueryBuilders.rangeQuery(price).gte(condition.getMinPrice())); sourceBuilder.query(boolQuery); sourceBuilder.from(condition.getPage() * condition.getSize()); sourceBuilder.size(condition.getSize()); searchRequest.source(sourceBuilder); SearchResponse response client.search(searchRequest, RequestOptions.DEFAULT); return parseResponse(response); } }BoolQueryBuilder 是 7.2.0 中组合查询的核心入口。must 对应 AND 语义must 里的 match 查询会做分词匹配。这里品牌用的是 termQuery因为品牌在实体里声明为了 keyword不分词用 term 才能精确匹配。filter 与 must 的区别在于 filter 不计算相关度分数查询速度更快且可以被 ES 缓存。所以范围过滤、状态过滤等不影响排序的硬性条件建议一律放入 filter 中。4.2 同时返回关键词高亮片段搜索引擎场景有一个高频需求搜索命中的关键词需要在前端标红展示。ES 高亮原理是在查询时指定字段名ES 返回该字段中命中的片段。RestHighLevelClient 的写法如下public MapString, Object searchWithHighlight(SearchCondition condition) throws IOException { SearchRequest searchRequest new SearchRequest(product); SearchSourceBuilder sourceBuilder new SearchSourceBuilder(); BoolQueryBuilder boolQuery QueryBuilders.boolQuery(); boolQuery.must(QueryBuilders.matchQuery(name, condition.getKeyword())); sourceBuilder.query(boolQuery); HighlightBuilder highlightBuilder new HighlightBuilder(); HighlightBuilder.Field highlightName new HighlightBuilder.Field(name); highlightName.preTags(span stylecolor:red); highlightName.postTags(/span); highlightBuilder.field(highlightName); sourceBuilder.highlighter(highlightBuilder); searchRequest.source(sourceBuilder); SearchResponse response client.search(searchRequest, RequestOptions.DEFAULT); MapString, Object result new HashMap(); ListMapString, Object list new ArrayList(); for (SearchHit hit : response.getHits().getHits()) { MapString, Object source hit.getSourceAsMap(); source.put(highlightName, hit.getHighlightFields() .get(name) .fragments()[0] .string()); list.add(source); } result.put(list, list); result.put(total, response.getHits().getTotalHits().value); return result; }高亮字段有三个常见翻车点需要提一下字段类型必须是 Textkeyword 类型无法高亮查询时如果有多个条件但高亮只对包含关键词的字段生效不要对 filter 字段声明高亮preTags 与 postTags 如果不设置默认返回标签很多前端框架需要自定义样式所以建议在服务端直接拼接好带色 HTML 或约定标签交由前端处理。fragments()[0] 需要判空因为当高亮字段没有命中时fragments 数组是空的直接取下标会抛 ArrayIndexOutOfBoundsException。4.3 7.2.0 的分页细节from.size 与最大窗口限制ES 分页有两种常用方式。一是 from size 浅分页适合页面跳转页码越深性能越差。二是 search_after 深分页适合 app 下拉加载与后台导出场景。7.2.0 的默认限制是 from size 不能超过 10000这个参数是 index 级别的 max_result_window 控制的。public ListProduct searchByScrollAfter(String lastSortValue, int size) throws IOException { SearchRequest searchRequest new SearchRequest(product); SearchSourceBuilder sourceBuilder new SearchSourceBuilder(); sourceBuilder.query(QueryBuilders.matchAllQuery()); sourceBuilder.size(size); sourceBuilder.sort(price, SortOrder.ASC); if (StringUtils.isNotBlank(lastSortValue)) { sourceBuilder.searchAfter(new Object[]{new BigDecimal(lastSortValue)}); } searchRequest.source(sourceBuilder); SearchResponse response client.search(searchRequest, RequestOptions.DEFAULT); ListProduct list new ArrayList(); for (SearchHit hit : response.getHits().getHits()) { list.add(JSONObject.parseObject(hit.getSourceAsString(), Product.class)); } return list; }search_after 依赖排序字段生成一个全局唯一的游标值。翻页时把上一页最后一条记录里用于排序的值传回来替代 from 参数。这里排序字段用 price它可能出现相同值为了确保唯一建议在排序里追加一个 _id 字段作为最终排序条件。使用 search_after 时不能再指定 from这是 ES 的硬性要求。对于后台导出这种需要全量遍历的场景scroll API 才会更合适但 scroll 要求保持上下文ES 会维护一个快照长时间挂起会占用大量内存7.2.0 中不推荐超过 5 分钟。5. 整合 ES 7.2.0 的避坑清单5 个高频踩坑记录与修复5.1 启动报错Received fatal alert: protocol_version现象SpringBoot 项目启动正常但第一次调用 ES 接口时报错堆栈信息包含 Received fatal alert: protocol_version。原因这是 JDK 版本与 ES 7.2.0 传输层协议不兼容导致的坑。ES 7.2.0 的 TransportClient 底层 Netty 与 JDK 11 的 TLS 协议协商存在版本不匹配如果你恰好用 JDK 11 或更高版本跑项目这个问题极其典型。解决优先切换到 RestHighLevelClient它走 HTTP 协议不受 TransportClient 的 TLS 实现影响。如果项目里暂时离不开 Spring Data 的自动 Repository也可以把 JDK 降到 8 并明确使用 3.2.x 的 spring-data-elasticsearch。生产环境我推荐前者一劳永逸地避开这条废弃链路。5.2 max_result_window 超限Result window is too large现象分页查询访问了第 10000 条之后的数据ES 直接抛异常提示 Result window is too largefrom size must be less than or equal to 10000。原因ES 索引默认 max_result_window 为 10000超出这个范围的 fromsize 组合会被拦截。这个限制是索引级配置不是全局的需要针对具体索引修改。解决在 Kibana 或通过 REST API 修改索引设置PUT /product/_settings { index: { max_result_window: 100000 } }修改索引的 settings 不影响索引现有数据是热更新操作。但如果未来数据量继续增长把窗口调大治标不治本。更合理的方案是前后台分页用 search_after 或 scroll 替代 fromsize。我一般在业务量超过千万级才会把 max_result_window 调大并且只调到 5 万以内避免深度分页把内存耗光导致全文检索性能集体下降。5.3 集群无主节点导致索引创建卡死现象应用启动时创建索引卡住es 日志显示 red 状态或者日志反复出现 waiting for master node。原因ES 7.2.0 对集群健康度比旧版更敏感。单节点启动时如果 discovery.type 不是 single-node节点会期待加入现有集群没有发现其他节点时不会自封为 master导致整个集群处于无主状态。解决单机开发环境启动时在 elasticsearch.yml 中设置discovery.type: single-node如果是多节点测试环境确认所有节点配置了相同的 cluster.name 并且网络可互通。另外注意 Spring Data 配置里 cluster-name 必须与 elasticsearch.yml 中的 cluster.name 完全一致否则节点发现了也不会加入这个参数玄学味道比较重排错时优先检查两边字符串是否完全相等。5.4 IK 分词插件缺失导致索引创建失败现象实体类字段配置了 analyzer ik_max_word应用启动创建索引时报 MapperParsingException提示 Analyzer [ik_max_word] not found。原因ES 服务端没有安装 IK 分词插件但客户端实体仍然声明了该分词器。解决进入 ES 的 plugins 目录安装 IK 分词器需要选用与 ES 7.2.0 匹配的版本然后重启 ES./bin/elasticsearch-plugin install https://github.com/medcl/elasticsearch-analysis-ik/releases/download/v7.2.0/elasticsearch-analysis-ik-7.2.0.zip安装前先确认 ES 是否已经启用了 security 或证书校验如果有需要额外调整 rest client 的 SSL 配置。插件的版本必须与 ES 主版本完全一致7.2.0 的插件不能装到 7.3.0 上这与部分读者已有的 mysql、redis 类插件经验不同ES 插件对版本绑定非常严。5.5 实体字段与 ES 返回字段类型不一致导致反序列化报错现象查询接口报错异常堆栈是 ClassCastException 或者 JSON parse error提示 Long can not cast to Integer、BigDecimal 无法解析等。原因ES 数字类型与 Java 实体类型之间的映射不对。比如 ES 里字段映射成 long实体类却声明为 Integer反序列化时 fastjson 或 Jackson 的严格模式就会拒绝。另一个常见场景是 date 字段在 ES 中返回的时间戳格式与 Java Date 不兼容。解决先通过 Kibana 查看索引 mapping确认字段的实际类型再回来修改实体类。ES 7.2.0 的 Date 字段默认格式通常形如 yyyy-MM-dd HH:mm:ss 或 epoch_millisJava 侧要么用 Long 接收时间戳要么通过 JsonFormat 显式指定格式。数值字段统一定义为 BigDecimal 或 Long 能绕开多数精度问题不推荐用 float 存金额类字段浮点精度在 ES 聚合中会造成统计偏差这是实战中容易让人忽视的。另外 double 无法精确匹配等于特定值如果需要精确过滤就必须映射为 keyword。6. 进阶技巧批量写入、索引重建与聚合统计6.1 用 Bulk 批量写入 10 万级数据单条 save 在数据量上来后效率很低常见做法是用 BulkRequest 一次性提交成批数据。批量写入必须控制每批条数和数据大小7.2.0 建议每批 5000 到 10000 条或者单批数据量不超过 15MB。超过这个大小ES 的 HTTP 层会返回 413 或直接超时。public boolean bulkInsert(ListProduct products) throws IOException { BulkRequest bulkRequest new BulkRequest(); for (Product product : products) { bulkRequest.add(new IndexRequest(product) .id(product.getId()) .source(JSONObject.toJSONString(product), XContentType.JSON)); } BulkResponse response client.bulk(bulkRequest, RequestOptions.DEFAULT); if (response.hasFailures()) { log.error(批量插入失败: {}, response.buildFailureMessage()); return false; } return true; }BulkRequest 是顺序写入的如果中途有失败项hasFailures 会返回 trueES 会把失败原因拼接在 buildFailureMessage 中。注意单条失败不会中止整个批次的请求所以批量写入必需要处理部分失败的情况。整批处理失败时回滚 ES 本身不提供事务能力只能通过重试单个文档或对比日志与源数据这就是 ES 建立在最终一致性之上的现实天然无强事务只能靠业务侧补偿。批量写入前建议先关闭 refresh 间隔这个参数是写入速率的隐藏瓶颈。ES 默认每秒刷新一次索引数据量大的时候把 refresh_interval 临时设成 -1等待写入完成后调回 1s索引速度会有明显提升PUT /product/_settings { index: { refresh_interval: -1 } }6.2 索引重建流程字段类型改错的最佳后悔药ES 不支持直接修改字段类型这是新手最容易碰壁的地方。如果你在实体里把 price 声明成了 text 并且已经创建索引想要改成 double必须走重建索引。正确步骤是先基于新结构创建临时索引再通过 reindex 将数据复制过去最后切换别名。PUT /product_v2 { mappings: { properties: { name: { type: text, analyzer: ik_max_word }, brand: { type: keyword }, price: { type: double }, createTime: { type: date } } } } POST /_reindex { source: { index: product }, dest: { index: product_v2 } }reindex 是 ES 自带的数据搬迁接口它不会修改原索引。操作完成后应用层需要将搜索结果指向 product_v2推荐用索引别名 xuan。给索引起别名并让应用连接别名之后后续版本切换与回滚都只需要改别名业务代码不动POST /_aliases { actions: [ { add: { index: product_v2, alias: product_alias } }, { remove: { index: product, alias: product_alias } } ] }这样一来即使新索引有问题也可以快速把别名切回旧索引算得上是对付结构变更的一剂后悔药。需要注意 reindex 在数据量大时是异步行为在 Kibana 中可以查看 task API 的进度reindex 期间不要删除原索引避免失败后没有回退路径。6.3 一个基于 terms 聚合的统计用例聚合查询是搜索引擎比关系型数据库出色很多的能力7.2.0 的 rest client 支持各种聚合器。以按品牌统计商品数为例public MapString, Long aggregateByBrand() throws IOException { SearchRequest searchRequest new SearchRequest(product); SearchSourceBuilder sourceBuilder new SearchSourceBuilder(); sourceBuilder.size(0); sourceBuilder.aggregation(AggregationBuilders .terms(brand_count) .field(brand) .size(20)); searchRequest.source(sourceBuilder); SearchResponse response client.search(searchRequest, RequestOptions.DEFAULT); Terms brandCount response.getAggregations().get(brand_count); MapString, Long result new HashMap(); for (Terms.Bucket bucket : brandCount.getBuckets()) { result.put(bucket.getKeyAsString(), bucket.getDocCount()); } return result; }sourceBuilder.size(0) 表示不返回文档明细只返回聚合结果这一步能省下大量传输开销。terms 聚合的字段必须是 keyword 类型否则聚合报错或结果不符合预期。聚合桶数量通过 size 控制这里 20 代表只返回品牌计数最多的前 20 个桶而不是全部。聚合计算是基于 Lucene 的倒排索引性能远高于同等条件下关系型数据库的 group by这也是后端用 ES 做报表统计的核心原因。在我经手的项目里SpringBoot 打包后一般直接部署在容器中ES 服务单独部署在专用机器上。两者之间隔了一层网络应用层必须对 ES 调用做超时与降级不要无限等待我习惯给 RestHighLevelClient 的 RequestOptions 设置连接超时与 socket 超时ES 集群抖动时应用不至于整体卡死。设置方法如下RequestOptions.Builder options RequestOptions.DEFAULT.toBuilder(); options.setHttpAsyncResponseConsumerFactory( new HttpAsyncResponseConsumerFactory .HeapBufferedResponseConsumerFactory(30 * 1024 * 1024));这套组合下来SpringBoot 与 ES 7.2.0 的整合已经能覆盖日常开发中从简单 CRUD 到复杂检索、批量索引、聚合统计的大部分场景。做这类整合时保持一个习惯所有索引结构变动优先改映射字段而不是在代码里做兼容所有查询参数先在 Kibana 验证 DSL 再写进 java这个习惯帮我避开了无数坑希望帮到你。本文还有配套的精品资源点击获取