1. 为什么在这个阶段还要聊 RestHighLevelClient

如果你正在跟着一个 Spring Boot 整合 Elasticsearch 的系列往下做，做到第五篇还在纠结客户端选型，说明你大概率踩到了同一个坑：项目里已经跑着 Spring Data Elasticsearch 的 Repository，但某个业务场景突然需要写一段带聚合、带脚本、带游标翻页的复杂查询，Repository 那套方法名派生和@Query注解开始不够用了。这时候最省事的做法不是推翻重来，而是把RestHighLevelClient单独拎出来，作为一个底层能力补充进去。

这篇内容就是围绕这件事展开的：在 Spring Boot 工程里，如何用RestHighLevelClient完成那些 Repository 干不了的活。核心关键词是RestHighLevelClient 操作 ES，涉及索引管理、批量写入、复杂查询、聚合分析、游标遍历这几块。适合已经能跑通基础增删改查、想往深水区走一步的开发者，也适合那些手上有个半成品项目、正卡在"复杂查询怎么写"这个环节的人。

先把定位说清楚。RestHighLevelClient是 Elasticsearch 官方 Java 客户端里偏底层的那一层，它把 REST API 做了类型化封装，请求体基本就是你在 Kibana 里手写的那段 JSON，只不过换成了 Builder 链式构造。它的好处是能力全覆盖，官方 REST 接口能干的它都能干；代价是啰嗦，一个简单的 term 查询也要写四五层嵌套。所以我的用法一直是：简单查询交给 Repository，复杂查询、批量操作、索引运维交给RestHighLevelClient，两者共存在同一个工程里，各管一摊。

这一篇重点讲后半部分，也就是真正用RestHighLevelClient去操作 ES 的那些细节。上一篇大概率已经把客户端 Bean 配好了，这一篇直接进入"怎么用"的层面，把请求构造、响应解析、异常处理、性能取舍这些实操环节拆开讲。

2. 客户端注入与工程结构的前置约定

2.1 Bean 的复用方式与线程安全认知

在动手写查询之前，先把客户端的持有方式定下来。RestHighLevelClient内部维护着连接池，本身是线程安全的，所以标准做法是在配置类里声明一个单例 Bean，全工程注入复用，绝对不要在方法里new一个用完就关。我见过有项目在每个 Service 方法里新建客户端，压测时连接数直接飙到四位数，节点侧开始拒绝连接，排查了半天才发现是客户端没复用。

配置类大致长这样，重点是把它交给 Spring 容器管理，生命周期跟着应用走：

@Configuration public class EsClientConfig { @Bean(destroyMethod = "close") public RestHighLevelClient restHighLevelClient() { RestClientBuilder builder = RestClient.builder( new HttpHost("es-node-01", 9200, "http")) .setRequestConfigCallback(rc -> rc .setConnectTimeout(3000) .setSocketTimeout(30000)) .setMaxRetryTimeoutMillis(30000); return new RestHighLevelClient(builder); } }

这里有两个参数值得单独说。connectTimeout设 3 秒，是因为建连失败通常意味着节点不可达，等太久没意义；socketTimeout设 30 秒，是给聚合查询和批量写入留的余量，普通查询几百毫秒就回来了，但一个跨几千万文档的 terms 聚合跑十几秒很正常，超时设太短会误杀。setMaxRetryTimeoutMillis控制的是整体重试窗口，不是单次请求超时，这两个概念经常被混淆，配的时候要分清。

注意：客户端 Bean 上标注destroyMethod = "close"，让容器关闭时释放底层连接。漏掉这一条，应用热部署或者优雅停机时会有连接泄漏，短时间看不出问题，跑几天连接数就上去了。

2.2 依赖版本的对齐问题

RestHighLevelClient对版本相当敏感，客户端主版本必须和服务端主版本一致，7.x 的客户端连 8.x 的集群会直接报兼容性错误。工程里通常是这样引入的：

<dependency> <groupId>org.elasticsearch.client</groupId> <artifactId>elasticsearch-rest-high-level-client</artifactId> <version>7.17.10</version> </dependency>

麻烦在于 Spring Boot 的依赖管理会偷偷把elasticsearch核心包的版本改掉，导致客户端和核心包版本错位，启动时报NoSuchMethodError或者ClassNotFoundException。稳妥的做法是在properties里显式锁定版本，把elasticsearch.version覆盖成和客户端一致的值。这个坑我在两个项目里都踩过，表现是编译没问题、启动就炸，日志里一堆类找不到，第一次遇到能查半天。

3. 索引与文档的基础操作落地

3.1 索引创建：Mapping 设计比代码更重要

用客户端建索引，代码本身没几行，真正决定成败的是 mapping 设计。下面这段是创建一个商品索引的典型写法：

CreateIndexRequest request = new CreateIndexRequest("product_index"); request.settings(Settings.builder() .put("number_of_shards", 3) .put("number_of_replicas", 1) .put("refresh_interval", "1s")); request.mapping( "{\n" + " \"properties\": {\n" + " \"title\": { \"type\": \"text\", \"analyzer\": \"ik_max_word\" },\n" + " \"brand\": { \"type\": \"keyword\" },\n" + " \"price\": { \"type\": \"scaled_float\", \"scaling_factor\": 100 },\n" + " \"stock\": { \"type\": \"integer\" },\n" + " \"createdAt\":{ \"type\": \"date\", \"format\": \"yyyy-MM-dd HH:mm:ss\" }\n" + " }\n" + "}", XContentType.JSON); client.indices().create(request, RequestOptions.DEFAULT);

几个设计决策展开说。title用text加中文分词器，是为了全文检索；brand用keyword，是因为它要参与精确过滤和聚合，用text会导致聚合结果被拆成一个个词。price用scaled_float而不是double，是因为金额场景下浮点精度问题会带来对账麻烦，scaled_float内部按整数存储，scaling_factor设 100 表示保留两位小数，既省空间又避免精度漂移。

分片数设 3 是个经验值，单分片建议控制在 10GB 到 30GB 之间，按你预估的数据量倒推。副本设 1 保证单节点故障时数据不丢，但如果集群只有一个节点，副本会一直处于 unassigned 状态，健康状态显示黄色，这时候要么加节点要么把副本设 0，别对着黄色状态干着急。

提示：mapping 一旦建好，字段类型基本不能改，只能重建索引再 reindex。所以第一次建索引前，把字段类型、分词器、是否需要聚合这些想清楚，比事后补救省事得多。

3.2 单条写入与批量写入的取舍

单条写入用IndexRequest，代码直白：

IndexRequest request = new IndexRequest("product_index") .id("1001") .source(XContentFactory.jsonBuilder() .startObject() .field("title", "无线蓝牙耳机") .field("brand", "某品牌") .field("price", 299.00) .field("stock", 500) .field("createdAt", "2024-03-01 10:00:00") .endObject()); client.index(request, RequestOptions.DEFAULT);

但真实场景里几乎不会一条一条写，导入数据、同步变更都是成批的。BulkRequest的用法是把多个IndexRequest或UpdateRequest塞进去，一次提交：

BulkRequest bulkRequest = new BulkRequest(); for (Product p : productList) { bulkRequest.add(new IndexRequest("product_index") .id(p.getId()) .source(XContentFactory.jsonBuilder() .startObject() .field("title", p.getTitle()) .field("brand", p.getBrand()) .field("price", p.getPrice()) .field("stock", p.getStock()) .endObject())); } BulkResponse response = client.bulk(bulkRequest, RequestOptions.DEFAULT); if (response.hasFailures()) { // 逐条检查失败原因，不要只看 hasFailures 就完事 for (BulkItemResponse item : response.getItems()) { if (item.isFailed()) { log.warn("doc {} failed: {}", item.getId(), item.getFailureMessage()); } } }

批量大小是个需要实测的参数。批次太小，网络往返开销占比高；批次太大，单次请求体可能超过节点限制，而且失败重试的成本也高。我的经验是每批 500 到 1000 条、请求体控制在 5MB 到 15MB 之间比较稳，具体还要看单条文档大小。如果单条文档就有几十 KB，那批次要相应调小。

hasFailures()返回 true 不代表整批失败，可能只是其中几条因为版本冲突或者 mapping 不匹配挂了，所以必须遍历getItems()逐条判断。我见过有代码只判断hasFailures然后整批重试，结果那几条永远失败的文档被反复提交，白白消耗资源。

4. 复杂查询的构造与响应解析

4.1 从 QueryBuilder 到 SearchSourceBuilder 的组装逻辑

RestHighLevelClient的查询构造分两层：QueryBuilder负责描述"查什么"，SearchSourceBuilder负责描述"怎么查、查多少、怎么排、怎么聚合"。这个分层理解清楚了，再复杂的查询都能拆开写。

一个带过滤、排序、分页、高亮的组合查询长这样：

BoolQueryBuilder boolQuery = QueryBuilders.boolQuery() .must(QueryBuilders.matchQuery("title", "蓝牙耳机")) .filter(QueryBuilders.termQuery("brand", "某品牌")) .filter(QueryBuilders.rangeQuery("price").gte(100).lte(500)); SearchSourceBuilder sourceBuilder = new SearchSourceBuilder() .query(boolQuery) .from(0) .size(20) .sort("price", SortOrder.ASC) .trackTotalHits(true) .highlighter(new HighlightBuilder().field("title")); SearchRequest searchRequest = new SearchRequest("product_index") .source(sourceBuilder); SearchResponse response = client.search(searchRequest, RequestOptions.DEFAULT);

这里有个关键取舍：must 和 filter 的区别。must里的条件参与相关性打分，filter里的条件不打分、可缓存。品牌、价格区间这类精确过滤放filter，既不影响排序得分，又能利用查询缓存，性能差别在大数据量下非常明显。很多人图省事全塞must，结果查询慢还找不到原因。

trackTotalHits(true)也值得说一句。ES 默认只精确统计到 10000 条，超过就返回10000这个上限值。如果你的业务需要准确的总数做分页，必须显式打开；如果只是展示"约多少条"，保持默认反而更省资源，因为精确计数要遍历所有匹配分片。

4.2 响应解析：别只盯着 hits

拿到SearchResponse之后，新手通常只取getHits()，但响应体里还有几块信息经常被忽略却很有用：

SearchHits hits = response.getHits(); long total = hits.getTotalHits().value; for (SearchHit hit : hits.getHits()) { Map<String, Object> source = hit.getSourceAsMap(); Map<String, HighlightField> highlight = hit.getHighlightFields(); // 处理业务字段和高亮片段 }

getTotalHits().value是总数，getTotalHits().relation告诉你这个数是精确值还是下限值（EQUAL_TO还是GREATER_THAN_OR_EQUAL_TO），分页逻辑要据此判断。hit.getSourceAsMap()拿原始文档，hit.getHighlightFields()拿高亮片段，高亮字段的文本里会带<em>标签，前端渲染时要注意转义处理，别直接 innerHTML 塞进去。

还有一个容易忽略的点：如果查询里指定了_source过滤（比如只要 title 和 price 两个字段），getSourceAsMap()里就只有这两个字段，其他字段取出来是 null。这个行为本身合理，但如果下游代码默认所有字段都在，就会空指针。所以要么查询时不过滤_source，要么解析时做好判空。

4.3 聚合查询的嵌套结构

聚合是RestHighLevelClient相对 Repository 最大的优势场景。一个"按品牌分组、组内算平均价格、再按平均价格倒序"的聚合：

SearchSourceBuilder sourceBuilder = new SearchSourceBuilder() .size(0) .aggregation(AggregationBuilders .terms("by_brand").field("brand").size(20) .subAggregation(AggregationBuilders.avg("avg_price").field("price"))); SearchResponse response = client.search( new SearchRequest("product_index").source(sourceBuilder), RequestOptions.DEFAULT); Terms byBrand = response.getAggregations().get("by_brand"); for (Terms.Bucket bucket : byBrand.getBuckets()) { String brand = bucket.getKeyAsString(); long docCount = bucket.getDocCount(); Avg avgPrice = bucket.getAggregations().get("avg_price"); double avg = avgPrice.getValue(); }

size(0)表示不要返回文档本身，只要聚合结果，能省掉大量数据传输。terms聚合默认只返回文档数最多的前 10 个桶，要更多就显式设size，但别设太大，桶数量直接影响内存占用。子聚合通过bucket.getAggregations().get("名字")取，名字必须和构建时一致，拼错了拿到的是 null，而且不会报错，这个坑很隐蔽。

聚合结果的类型要和聚合类型对上：terms对应Terms，avg对应Avg，date_histogram对应Histogram。类型强转错了会在运行时抛ClassCastException，编译期发现不了，所以聚合名字和类型最好在代码里集中管理，别散落各处。

5. 游标遍历与大数据量导出

5.1 scroll 与 search_after 的适用边界

需要遍历超过一万条数据时，from + size就不行了，深分页会拖垮集群。这时候有两个选择：scroll和search_after。

scroll相当于给查询结果拍了个快照，后续翻页基于这个快照，适合一次性全量导出的场景，比如把数据同步到另一个系统。缺点是快照期间占资源，而且不能反映实时变更。用法是先发起一个带scroll参数的查询拿到scrollId，然后循环用scrollId取下一批，取完记得clearScroll释放资源：

SearchRequest request = new SearchRequest("product_index") .scroll(TimeValue.timeValueMinutes(2)) .source(new SearchSourceBuilder().query(QueryBuilders.matchAllQuery()).size(1000)); SearchResponse response = client.search(request, RequestOptions.DEFAULT); String scrollId = response.getScrollId(); while (response.getHits().getHits().length > 0) { // 处理这一批 response = client.scroll( new SearchScrollRequest(scrollId).scroll(TimeValue.timeValueMinutes(2)), RequestOptions.DEFAULT); scrollId = response.getScrollId(); } client.clearScroll(new ClearScrollRequest(scrollId), RequestOptions.DEFAULT);

search_after则是基于上一页最后一条的排序值继续往后取，适合实时翻页，比如用户不断点"下一页"。它要求排序字段组合唯一，通常用createdAt加id做复合排序，否则排序值相同的文档可能被跳过或重复。

注意：scroll的scrollId一定要在 finally 块里清理，异常路径漏掉清理会导致快照一直挂着，集群内存慢慢被吃满。这个资源泄漏不会立刻报错，但跑一段时间后查询开始变慢，排查起来很费劲。

5.2 游标遍历中的批次大小调优

批次大小（size）设多少，取决于单条文档大小和下游处理速度。设 1000 条、单条 2KB，一批就是 2MB 左右，网络传输和处理都比较从容。如果单条文档很大，比如带长文本字段，批次要降到 200 到 500。判断标准是：单批响应体别超过 10MB，处理单批的耗时别超过scroll的保活时间，否则下一批请求可能因为快照过期而失败。

6. 异常处理与常见问题排查

6.1 异常分类与应对策略

RestHighLevelClient抛出的异常大致分三类，处理方式完全不同：

区分"可重试"和"不可重试"是异常处理的核心。索引不存在你重试一百次也还是不存在，反而把日志刷爆；网络超时重试一次可能就成功了。我一般会在客户端外层包一个简单的重试逻辑，只对连接类异常生效，状态类异常直接往上抛。

6.2 高频问题速查

下面这张表是我在实际项目里反复遇到的几个问题，按出现频率排序：

6.3 几个只有踩过才知道的细节

第一个，UpdateRequest做局部更新时，如果文档不存在默认会报错，除非显式docAsUpsert(true)或者用upsert。这个默认行为经常让同步逻辑在"新增文档"这一步挂掉，而错误信息又不够直白。

第二个，refresh参数。写入后立刻查询查不到新数据，是因为索引默认 1 秒刷新一次。测试环境为了即时可见可以设RefreshPolicy.IMMEDIATE，但生产环境别这么干，每次写入都强制刷新会让写入性能断崖式下跌。正确做法是接受这个延迟，或者在业务层做补偿。

第三个，RequestOptions可以设置路由和超时。如果查询明确只涉及某个分片路由键，设上routing能把请求打到单个分片，省掉广播开销。这个优化在分片数多的时候效果明显，但前提是你的路由设计合理。

7. 性能取舍与工程化建议

7.1 查询层面的几个开关

SearchSourceBuilder上有几个开关，用好了能显著降低开销。fetchSource可以只取需要的字段，避免传输大字段；profile打开能看到每个子查询的耗时分布，调优时非常有用，但生产环境别开，它本身有性能损耗；terminateAfter可以限制最多匹配多少文档就停，适合"只要有没有、不关心有多少"的存在性判断。

分页大小也要克制。一次取 20 条和一次取 1000 条，网络和内存开销差几十倍。如果前端是滚动加载，size设 20 到 50 足够；如果是导出，走scroll而不是把size调大。

7.2 客户端与 Repository 的共存边界

回到开头说的分工。我的实践是：领域实体的简单 CRUD 走 Repository，享受方法名派生和自动映射的便利；跨索引查询、复杂聚合、批量运维走RestHighLevelClient，享受完全控制权。两者共用同一个客户端连接池，不会互相干扰。

需要提醒的是，别在同一个业务方法里混用两套 API 去操作同一批数据，事务边界和刷新时机容易对不上，出现"刚写完查不到"的诡异现象。要么统一走一套，要么在方法边界上做好同步。

7.3 配置外置与多环境适配

节点地址、超时、批次大小这些参数不要硬编码在代码里。用@ConfigurationProperties绑定到配置文件，不同环境用不同的 profile 覆盖。测试环境节点少、数据量小，超时可以设短一点快速暴露问题；生产环境节点多、查询重，超时要留足余量。这个分离做得好，后面调参不用改代码重新打包。

es: hosts: es-node-01:9200,es-node-02:9200 connect-timeout: 3000 socket-timeout: 30000 bulk-size: 800 scroll-keepalive: 2m

我在实际项目里发现，把bulk-size和scroll-keepalive这类参数外置之后，遇到数据量突增时只需要改配置重启，不用走一遍发版流程，响应速度快很多。而且这些参数的最优值本来就随数据特征变化，硬编码等于把调优空间锁死了。

最后分享一个排查思路：当查询性能突然下降时，先看慢查询日志里有没有from + size的深分页，再看聚合的桶数量是不是失控，最后才怀疑硬件。绝大多数"ES 变慢了"的问题，根子都在查询写法上，而不是集群本身。