Spring Boot 项目里接上 Elasticsearch 之后，真正让人头疼的往往不是"能不能连上"，而是连上之后那一堆查询怎么写、聚合怎么拼、分页怎么翻、结果怎么解析。我见过不少团队在引入 RestHighLevelClient 的初期，把官方文档里的示例代码直接搬进业务层，跑通一个match查询就以为大功告成，结果等到要做条件组合、深度分页、聚合统计的时候，代码迅速膨胀成一坨难以维护的字符串拼接。这篇接着上一篇的节奏，专门聊 RestHighLevelClient 在实际业务里最常打交道的几类操作——查询构建、聚合分析、分页与游标、结果解析与异常处理，把我自己踩过的坑和验证过的写法摊开讲清楚。

如果你正在用 Spring Boot 对接 Elasticsearch，已经能完成基本的索引和文档 CRUD，但一到复杂查询就卡壳，或者写出来的代码自己回头看都费劲，那这篇内容应该能帮上忙。下面所有示例都基于 RestHighLevelClient 这套 Java 客户端，围绕真实业务场景展开，不堆砌 API 清单，而是讲清楚每个操作"为什么这么写"。

1. 查询构建：从 QueryBuilder 组合到业务语义落地

RestHighLevelClient 的查询能力几乎全部压在QueryBuilders这个工具类上，它提供了几十种静态方法，覆盖全文检索、精确匹配、范围、地理、嵌套等各类场景。但工具方法多不代表好用，真正的难点在于：面对一个业务需求，怎么把它翻译成一组 QueryBuilder 的组合，并且保证组合出来的 DSL 既正确又高效。

1.1 为什么不能直接拼 JSON 字符串

刚接触这套客户端的人常有一个疑问：既然 ES 的查询本质就是一段 JSON DSL，那我直接拼字符串丢给低级客户端不就行了？技术上确实可行，但实际项目里这么干很快就会出问题。字符串拼接没有任何类型检查，字段名写错、括号少一个、逗号多一个，编译期完全发现不了，只能等运行时抛异常。而 QueryBuilder 体系是强类型的，termQuery("status", 1)里字段名和值类型在写的时候就约束住了，IDE 还能给出补全提示。

更关键的是可组合性。业务查询往往是"基础条件 + 动态筛选 + 排序 + 分页"的叠加，用 QueryBuilder 可以通过BoolQueryBuilder的must、should、filter、mustNot逐层嵌套，每个子条件独立构建、独立测试，最后组装起来。字符串拼接则只能靠字符串模板和占位符，条件一多就变成意大利面条。我个人的经验是：只要查询条件超过三个且带动态性，就老老实实用 QueryBuilder，别图省事。

1.2 BoolQuery 的四个子句到底怎么选

BoolQueryBuilder是组合查询的核心，它内部有四个子句，很多人分不清must和filter的区别，导致查询性能白白浪费。这里把它们的语义和适用场景列清楚：

核心原则一句话：只影响"是否命中"、不影响"排第几"的条件，一律放 filter。比如"订单状态等于已支付""创建时间在最近七天""商品类目属于数码"，这些条件放 filter 里，ES 会走缓存、跳过算分，查询速度能明显提升。而"标题包含关键词"这种需要按相关度排序的，才放 must。

我见过一个真实案例：某列表页把状态过滤、时间范围、类目筛选全塞进 must，结果每次查询都要对几百万文档算一遍分，响应时间居高不下。改成 filter 之后，同样的查询耗时直接降了一个量级。这个改动成本极低，收益却很大，值得每个项目检查一遍。

1.3 一个可复用的查询构建模板

业务代码里最忌讳把查询逻辑散落在各处，我习惯抽一个构建方法，把公共条件收敛起来。下面这段是简化后的写法，展示组合思路：

public SearchSourceBuilder buildOrderQuery(OrderQueryParam param) { BoolQueryBuilder bool = QueryBuilders.boolQuery(); // 精确过滤条件，全部走 filter if (param.getStatus() != null) { bool.filter(QueryBuilders.termQuery("status", param.getStatus())); } if (param.getStartTime() != null && param.getEndTime() != null) { bool.filter(QueryBuilders.rangeQuery("createTime") .gte(param.getStartTime()) .lte(param.getEndTime())); } if (CollectionUtils.isNotEmpty(param.getCategoryIds())) { bool.filter(QueryBuilders.termsQuery("categoryId", param.getCategoryIds())); } // 全文检索条件走 must，参与算分 if (StringUtils.hasText(param.getKeyword())) { bool.must(QueryBuilders.multiMatchQuery(param.getKeyword(), "title", "remark") .type(MultiMatchQueryBuilder.Type.BEST_FIELDS)); } // 排除已删除 bool.mustNot(QueryBuilders.termQuery("deleted", true)); SearchSourceBuilder source = new SearchSourceBuilder(); source.query(bool); source.sort("createTime", SortOrder.DESC); return source; }

这段代码的价值不在于语法，而在于结构：过滤条件、检索条件、排除条件分区清晰，后续加字段只需在对应区块追加，不会互相干扰。multiMatchQuery用BEST_FIELDS类型，意思是哪个字段匹配得最好就用哪个字段的分，适合标题和备注这种权重不同的场景。

1.4 嵌套字段查询的坑

如果索引里用了nested类型（比如订单里嵌了商品明细数组），普通查询是查不到嵌套字段的，必须用nestedQuery包一层。这里有个高频错误：多个嵌套条件分别写nestedQuery，结果语义变成"存在某个明细满足条件A，且存在某个明细满足条件B"，而业务要的往往是"同一个明细同时满足A和B"。正确做法是把多个条件放进同一个nestedQuery的 bool 里：

bool.filter(QueryBuilders.nestedQuery("items", QueryBuilders.boolQuery() .filter(QueryBuilders.termQuery("items.skuId", skuId)) .filter(QueryBuilders.rangeQuery("items.price").gte(100)), ScoreMode.None));

ScoreMode.None表示嵌套部分不参与算分，配合外层 filter 使用，性能更好。这个细节不注意，查出来的数据会莫名其妙多出一批，排查起来相当费劲。

2. 聚合分析：把统计逻辑从数据库搬到 ES

很多业务场景原本靠数据库group by做统计，数据量一大就扛不住。ES 的聚合能力正好补这个短板，但聚合的 DSL 结构比查询复杂，RestHighLevelClient 的聚合 API 也比较绕，需要单独拎出来讲。

2.1 聚合的基本骨架：AggregationBuilders

聚合通过AggregationBuilders构建，挂在SearchSourceBuilder上。一个聚合由名字、类型、字段三要素组成，名字是自定义的，后面解析结果时靠它取值。下面是一个按状态分组计数的例子：

SearchSourceBuilder source = new SearchSourceBuilder(); source.size(0); // 只要聚合结果，不要文档明细 source.aggregation( AggregationBuilders.terms("status_count").field("status").size(20) );

这里size(0)是个容易被忽略的点。如果只关心聚合结果，把返回文档数设为 0，能省掉大量无用的文档序列化开销。我见过有人忘了设，查一次聚合顺带拉回一万条明细，网络传输和反序列化都白白浪费。

2.2 桶聚合与度量聚合的搭配

聚合分两大类：桶聚合（bucket）负责分组，度量聚合（metric）负责在每组内算值。业务里最常见的组合是"按某维度分组，再算每组的数量、平均值、最大值"。比如按商品类目分组，统计每个类目的销量总和与平均单价：

TermsAggregationBuilder categoryAgg = AggregationBuilders .terms("by_category").field("categoryId").size(50) .subAggregation(AggregationBuilders.sum("total_sales").field("sales")) .subAggregation(AggregationBuilders.avg("avg_price").field("price")); source.aggregation(categoryAgg);

子聚合通过subAggregation挂载，解析时先取桶，再从每个桶里取子聚合的值。这里要注意terms聚合默认只返回文档数最多的前十个桶，size(50)是显式放大，但别设太大，桶数量过多会拖慢查询。如果确实需要全量分组，考虑用composite聚合做分页遍历，而不是把 size 调到几千。

2.3 聚合结果解析的固定套路

聚合结果的解析代码结构高度固定，但字段层级容易搞混。核心是Aggregations对象，先按名字取聚合，再判断类型强转。以刚才的类目聚合为例：

Aggregations aggs = response.getAggregations(); Terms terms = aggs.get("by_category"); for (Terms.Bucket bucket : terms.getBuckets()) { String categoryId = bucket.getKeyAsString(); long docCount = bucket.getDocCount(); Sum totalSales = bucket.getAggregations().get("total_sales"); Avg avgPrice = bucket.getAggregations().get("avg_price"); // totalSales.getValue() 是 double，注意业务精度 }

两个实操提醒：第一，Sum和Avg返回的都是double，涉及金额统计时要么在业务层做精度处理，要么改用scripted_metric精确计算，别直接拿 double 当金额用。第二，terms.get("xxx")如果聚合名写错会返回 null，紧接着就 NPE，建议解析前先判空，或者把聚合名抽成常量统一管理，避免手滑。

2.4 日期直方图：时间序列统计的利器

做趋势图、日报周报这类需求，date_histogram聚合比 terms 更合适。它能按固定时间间隔（天、小时、周）自动分桶，还能配合时区参数避免跨时区错位：

DateHistogramAggregationBuilder dateAgg = AggregationBuilders .dateHistogram("by_day").field("createTime") .calendarInterval(DateHistogramInterval.DAY) .timeZone(ZoneId.of("Asia/Shanghai"));

时区这个参数千万别省。ES 内部时间默认按 UTC 存储，如果不指定时区，按天分桶的边界会落在 UTC 零点，对应到东八区就是早上八点，统计出来的"每天"其实是错位的。这个坑我在两个项目里都遇到过，表现是日报数据总是差那么几个小时，查半天才发现是时区没设。

3. 分页与游标：深度分页为什么不能硬翻

分页看起来是最简单的需求，from加size一设就完事。但只要翻到深一点的位置，问题就来了：查询越来越慢，甚至直接报错。这一节把分页的几种方案和适用边界讲透。

3.1 from/size 的天花板在哪

from + size的分页机制是：每个分片都要取出from + size条文档，协调节点汇总后再截取。也就是说翻到第 1000 页、每页 20 条时，每个分片实际要处理 20000 条，分片越多浪费越大。ES 默认用index.max_result_window限制from + size不超过 10000，超过就抛异常。

这个限制不是随便设的，它反映的是机制本身的代价。所以from/size只适合浅分页，比如前几十页的常规列表。如果你的业务允许用户一直往下翻到很深的页码，就得换方案。

3.2 scroll：适合批量导出的快照游标

scroll的思路是给查询结果做一个快照，后续按游标一批批取，适合数据导出、全量重建索引这类"一次性拉大量数据"的场景。用法上先发起一个带scroll参数的搜索，拿到scrollId，再循环调用scroll接口直到没有数据：

SearchRequest request = new SearchRequest("order_index"); request.scroll(TimeValue.timeValueMinutes(2)); request.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) { // 处理这一批 SearchScrollRequest scrollRequest = new SearchScrollRequest(scrollId); scrollRequest.scroll(TimeValue.timeValueMinutes(2)); response = client.scroll(scrollRequest, RequestOptions.DEFAULT); } // 用完记得清理 ClearScrollRequest clear = new ClearScrollRequest(); clear.addScrollId(scrollId); client.clearScroll(clear, RequestOptions.DEFAULT);

两个必须注意的点：一是scroll的快照会占用资源，用完一定要clearScroll，否则上下文一直挂着直到超时；二是scroll期间的数据变更不会反映到快照里，它不适合实时性要求高的场景，只适合离线批处理。

3.3 search_after：实时深分页的正解

如果业务需要实时深分页（比如无限滚动的信息流），search_after是更合适的选择。它不依赖快照，而是用上一页最后一条记录的排序值作为下一页的起点，每次查询都是实时的。前提是排序字段必须能唯一确定位置，通常用"业务时间 + 唯一ID"组合排序：

source.sort("createTime", SortOrder.DESC); source.sort("id", SortOrder.ASC); // 兜底保证唯一 source.size(20); // 第一页正常查，取最后一条的 sort 值 Object[] lastSort = response.getHits().getHits()[lastIndex].getSortValues(); // 下一页把 sort 值塞回去 source.searchAfter(lastSort);

search_after的代价是不能跳页，只能一页页往后翻，这正好契合无限滚动的交互。如果你的产品有"跳到第 50 页"这种需求，那它就不适用，得回到from/size并接受浅分页限制，或者用其他方式做页码映射。

3.4 三种分页方案的选型对照

选型时先问自己两个问题：要不要跳页？数据要不要实时？答案组合起来基本就锁定方案了。我个人的习惯是列表页默认from/size加一个合理的页码上限，导出功能单独走scroll，信息流类走search_after，各司其职，别指望一个方案通吃。

4. 结果解析与异常处理：让代码经得起线上考验

查询写对了只是第一步，线上跑起来之后，结果解析的健壮性和异常处理才是决定系统稳不稳的关键。这一节聊几个实战中反复出现的问题。

4.1 命中结果解析的字段取值陷阱

SearchHit取字段有几种方式，getSourceAsMap()拿原始 Map，getSourceAsString()拿 JSON 字符串，还有field()取存储字段。用 Map 取值时类型全靠强转，字段一多就容易出ClassCastException。我的做法是统一用 Jackson 把getSourceAsString()反序列化成强类型对象：

ObjectMapper mapper = new ObjectMapper(); for (SearchHit hit : response.getHits().getHits()) { OrderDoc doc = mapper.readValue(hit.getSourceAsString(), OrderDoc.class); // 直接用 doc 的 getter }

这样字段类型在实体类里定义清楚，反序列化失败会明确报错，比在 Map 里到处(String) map.get("xxx")可靠得多。代价是多一次序列化开销，但对绝大多数业务来说完全可以接受。

另外，getSourceAsString()在文档被_source过滤（比如只返回部分字段）时可能缺字段，实体类里对应字段要允许为 null，别在解析后立刻调用它的方法。

4.2 超时与重试的边界

ES 查询超时是线上常见问题，尤其是聚合查询和深分页。RestHighLevelClient 允许在RequestOptions里设置连接超时和读取超时：

RequestOptions options = RequestOptions.DEFAULT.toBuilder() .setConnectTimeout(1000) .setSocketTimeout(5000) .build();

超时设置要区分场景：普通列表查询 socket 超时给 3 到 5 秒足够，聚合统计可以放宽到 10 秒。但超时不是越长越好，设太长会把线程池拖住，反而放大故障。至于重试，读操作可以适度重试一次，写操作要谨慎，避免重复写入。我一般只对查询类请求做一次重试，并且重试前判断异常类型，连接类异常才重试，查询语法错误重试多少次都没用。

4.3 连接池与客户端生命周期管理

RestHighLevelClient 是重量级对象，内部维护连接池，绝对不能在每次请求里 new 一个。正确做法是交给 Spring 容器管理成单例 Bean，应用关闭时调用close()释放资源。配置上，连接数要和实际并发匹配，默认值在低并发下够用，高并发场景需要调大maxConnTotal和maxConnPerRoute，否则请求会排队等连接。

还有一个容易忽略的点：客户端底层依赖的 HTTP 连接如果长时间空闲，可能被中间网络设备断开，表现为偶发的连接异常。可以在客户端配置里开启心跳或者合理设置连接存活时间，让连接池主动淘汰陈旧连接。这类问题排查起来很隐蔽，日志里只看到零星超时，实际是连接失效导致的。

4.4 一个完整的查询执行封装

把前面的点串起来，一个健壮的查询执行方法大致长这样：构建请求、设置超时、执行、判空、解析、异常兜底。下面给出骨架，重点看异常处理和资源管理：

public <T> PageResult<T> search(SearchRequest request, Class<T> clazz) { try { SearchResponse response = client.search(request, buildOptions()); if (response.getHits() == null) { return PageResult.empty(); } List<T> list = new ArrayList<>(); for (SearchHit hit : response.getHits().getHits()) { list.add(objectMapper.readValue(hit.getSourceAsString(), clazz)); } long total = response.getHits().getTotalHits() == null ? 0 : response.getHits().getTotalHits().value; return new PageResult<>(list, total); } catch (ElasticsearchException e) { // 记录 DSL 和异常，便于排查 log.error("ES query failed, dsl={}", request.source(), e); throw new BizException("查询服务暂时不可用"); } catch (IOException e) { log.error("ES io error", e); throw new BizException("查询服务暂时不可用"); } }

这里把ElasticsearchException和IOException分开捕获，前者通常是 DSL 或集群层面的问题，后者是网络层面的问题，日志里区分开有助于快速定位。把 DSL 打进日志这一点很关键，线上出问题时能直接复现查询，比对着代码猜强太多。

5. 写在最后的几点实操体会

RestHighLevelClient 这套 API 用熟了之后其实不算复杂，真正拉开差距的是对细节的把握。我自己在多个项目里反复验证下来，有几条经验值得单独强调。

第一，查询条件的归类要养成肌肉记忆。每次写查询前先想一遍：哪些是过滤、哪些是检索、哪些是排除，分别放进 filter、must、must_not。这个习惯一旦养成，查询性能和可读性都会明显改善，而且代码评审时一眼就能看出问题。

第二，聚合的 size 和分页的 from 都要有明确上限。ES 不是数据库，没有成本低廉的全表扫描，任何"先查出来再说"的写法在大数据量下都会反噬。给每个查询设一个合理的边界，是保护集群也是保护自己。

第三，解析层尽量强类型化。Map 取值写起来快，但维护成本高，字段一多就是灾难。用实体类承接_source，配合 Jackson 做反序列化，出错时错误信息清晰，重构时也有编译器兜底。

第四，异常处理和日志要围绕"可复现"设计。把 DSL、参数、异常类型都记下来，线上出问题时能第一时间还原现场。很多 ES 相关的疑难杂症，最后都是靠日志里那段完整的 DSL 定位的。

这套客户端虽然在新版本里逐渐被新的 Java API Client 取代，但存量项目里 RestHighLevelClient 仍然是主力，把这些操作吃透，迁移到新客户端时思路也是相通的——查询构建的组合思想、聚合的桶与度量结构、分页方案的取舍逻辑，这些底层认知不会因为 API 换皮而失效。