大概两年前我接手了一个基于SpringBoot的搜索服务改造项目。原来的实现是这样的所有筛选条件拼成SQL靠MySQL的LIKE查询硬扛。数据量在百万级的时候还能忍等到某个业务表冲到三千万行一次带多个条件的模糊查询直接飙到三秒多接口超时告警一天能响几十次。后来把搜索链路替换成了ElasticSearch核心查询构建用的是Spring Data Elasticsearch里的QueryBuilder线上接口的耗时从三秒多降到了几十毫秒。这篇文章就把我在这个改造过程中对QueryBuilder的完整理解、实际踩过的坑和最终沉淀下来的代码组织方式整理出来希望能给正打算在SpringBoot项目里接入ES条件查询的同学一些参考。这套东西我自己使用下来的感受是它并不是一套门槛很高的技术但里面一些细节确实坑了不少人尤其是第一次从SQL思维切到ES思维的时候最容易在bool查询、term与match的区分、以及动态拼接条件这几块上懵。我会从最基础的依赖版本开始一直讲到组合查询怎么写再配合排查实录尽量让这篇内容能做到“看完能直接照着写”。1. 项目整体思路拆解为什么选择QueryBuilder而不是写死JSON先说个很多人刚接触Spring Data Elasticsearch时的困惑既然ES本身提供一整套REST API直接把JSON查询串写在代码里不就行了吗为什么要用QueryBuilder我的答案是如果你只是写一个固定不变的查询直接上JSON字符串确实更直观、更贴近ES原生语法。但现实业务里的搜索条件几乎不会是固定的用户可能选城市、可能筛价格区间、可能只按分类过滤、也可能什么都不选只做一个关键词搜索。这种“动态拼条件”的场景如果靠字符串拼接JSON代码会很快失控而且很容易在拼接过程中漏掉引号、多一个逗号线上查不出数据的时候排查成本极高。QueryBuilder的价值就在于它用Java对象来描述查询逻辑允许你在代码里以编程的方式按需组合条件构建过程本身就是一段可维护的逻辑而不是一堆要被解析的文本。还有一个很重要的原因QueryBuilder最终会由框架转化成ES可以理解的查询DSL。也就是说你不需要自己关心JSON结构长什么样框架帮你序列化出错概率低很多。像我接手那个搜索服务时团队之所以选这种方式核心就是后续扩展方便。比如今天只支持“关键词城市”两个条件明天业务说要加一个“人均消费区间”那只需要在构建QueryBuilder的地方追加一个RangeQueryBuilder不需要改动拼接JSON的逻辑和对应的解析器。另外要说明的是Spring Data Elasticsearch在不同版本里对QueryBuilder的封装是有差异的后面会单独讲版本兼容问题。整体思路确认后项目落地的顺序大致是先准备依赖和连接配置再根据业务字段建好索引映射然后核心地实现查询构建服务最后统一封装返回结果、做分页和排序。下面按这个顺序把关键环节挨个拆开。2. 环境准备与基础配置版本选型是第一个大坑2.1 依赖引入与版本对应关系Spring Data Elasticsearch和Elasticsearch之间的版本兼容是出了名的“一不留神就翻车”。我见过不止一个项目因为依赖版本没对齐启动时直接抛UnsupportedOperationException或者NoSuchMethodError排查半天才发现是客户端版本和服务端版本不匹配。我自己目前用得比较多、也比较推荐的一套组合是SpringBoot 2.7.x Spring Data Elasticsearch 4.4.x Elasticsearch 7.17.x。如果你用的是SpringBoot 2.7可以在pom.xml里这样引入parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version2.7.18/version relativePath/ /parent dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-data-elasticsearch/artifactId /dependency /dependencies这里需要注意一个关键点SpringBoot的BOM已经帮你锁定了spring-boot-starter-data-elasticsearch对应的版本所以正常情况下不需要手动指定spring-data-elasticsearch和elasticsearch这两个jar的版本号。但如果你在私服或者公司内部仓库里单独引了ES的依赖并且版本不是7.17.x那启动时大概率会遇到客户端与服务端版本协商失败的问题。如果不确定自己该用哪套版本组合最稳妥的方法是到Spring Data Elasticsearch官方文档里查“Version Compatibility”表格确保spring-data-elasticsearch的版本和你的ES集群主版本对齐。2.2 连接配置配置项写在application.yml里我习惯用下面这套spring: elasticsearch: uris: - http://localhost:9200 connection-timeout: 3s read-timeout: 10s socket-timeout: 30s注意属性名是spring.elasticsearch.uris而不是spring.elasticsearch.host这是SpringBoot 2.x比较新的写法很多人沿用老版本的习惯写host结果发现配置不生效。连接超时和读取超时这两个参数建议一定要显式配置默认值在某些生产环境里会表现得过于“乐观”如果ES集群压力大、响应慢客户端会长时间挂住不报错接口调用方那边看起来就像是服务假死。配置好连接之后下一步就是定义索引实体。实体定义这一块直接决定了后面QueryBuilder里面字段名怎么使用所以我会把字段映射的规范放在查询之前的准备工作里讲清楚。2.3 索引实体与字段映射注意点我用一个实际的业务场景来举例。假设我们做一个门店搜索索引里存了门店名称、所属城市、分类、人均消费、评分、经纬度、营业状态等字段。对应的实体类大致是这样的Data Document(indexName store_info) public class StoreInfo { Id private String id; Field(type FieldType.Keyword) private String city; Field(type FieldType.Keyword) private String category; Field(type FieldType.Text, analyzer ik_max_word) private String storeName; Field(type FieldType.Text, analyzer ik_max_word) private String description; Field(type FieldType.Double) private Double avgPrice; Field(type FieldType.Double) private Double rating; Field(type FieldType.Boolean) private Boolean isOpen; }字段类型的选择是这里面的核心细节。ES的Text和Keyword是两种查询方式截然不同的类型Keyword类型不分词适合精确匹配、过滤、聚合排序Text类型会经过分析器分词适合全文搜索。像我上面的门店名称和描述因为要做“关键词搜索”的效果所以用Text加ik_max_word中文分词而城市和分类是要精确筛选的就用Keyword。如果这个映射关系没想清楚后面写QueryBuilder的时候就会出现很典型的问题用term查询一个Text字段往往什么都查不到因为Text字段在索引时已经被分词器拆成了多个词项term默认不做分析拿整个输入去匹配词项自然匹配不上。这个问题后面在“常见问题”部分还会再展开。实体类定义好以后可以用ElasticsearchRestTemplate的indexOps()方法创建索引也可以让框架在启动时自动根据实体创建。我建议在开发环境可以自动创建但生产环境最好预先通过ES的API或者专门的初始化任务来建索引因为生产索引的shard数量、副本数、分词器配置往往比实体注解里能表达的东西更复杂。3. 条件查询核心拆解从简单条件到组合条件3.1 几个最常用的QueryBuilder实现类Spring Data Elasticsearch里所有具体的QueryBuilder实现都会实现org.elasticsearch.index.query.QueryBuilder这个顶层接口。我在日常开发中最常用的是下面这几个实现类作用使用场景MatchQueryBuilder分词匹配查询搜索名称、描述、内容等需要分词的字段TermQueryBuilder精确词项查询精确匹配某个ID、分类、状态等不分词字段TermsQueryBuilder多个精确值查询类似SQL里的IN查询RangeQueryBuilder范围查询价格区间、时间范围、数值区间BoolQueryBuilder布尔组合查询把多个条件组合在一起WildcardQueryBuilder通配符查询模糊匹配但性能开销较大需慎用这些类在使用上有一个通用的规律每个QueryBuilder一般都有对应的静态方法可以通过QueryBuilders.xxx()一行代码创建出来。比如QueryBuilders.matchQuery(storeName, 火锅)、QueryBuilders.termQuery(city, 上海)。这种方式写起来简洁团队里其他人读代码的时候也能一眼看出查询意图。3.2 BoolQueryBuilder条件组合的地基真实的搜索场景里几乎没有只靠一个单一条件就能搞定需求的。我自己的经验是90%以上的查询最终都得落到BoolQueryBuilder上。它的核心逻辑是用四个子句来组织条件must文档必须满足所有条件参与相关性评分。filter文档必须满足条件但不参与评分性能更好。should文档满足任意一个条件即可最少满足数由minimumShouldMatch控制。mustNot文档不能满足条件相当于排除。用SQL来类比的话must和filter都相当于ANDshould相当于ORmustNot相当于NOT。但must和filter在ES内部有一个核心差别——filter会使用缓存查询速度更快。所以我的习惯是纯过滤性质的等值条件、范围条件、状态条件全部放到filter里只有影响相关性排序的全文搜索条件才放到must里。举个例子用户搜“火锅”同时筛选城市为“上海”那“火锅”放进must“城市”放进filter因为城市这个条件并不需要影响相关性我们只需要它做过滤。3.3 从第一个简单查询到组合查询的完整演变先说最简单的单条件查询。用Spring Data Elasticsearch的ElasticsearchRestTemplate配合NativeSearchQuery核心代码像这样QueryBuilder queryBuilder QueryBuilders.termQuery(city, 上海); SearchSourceBuilder sourceBuilder new SearchSourceBuilder(); sourceBuilder.query(queryBuilder); NativeSearchQuery searchQuery new NativeSearchQuery(queryBuilder); searchQuery.setPageable(PageRequest.of(0, 10)); SearchHitsStoreInfo searchHits elasticsearchRestTemplate.search(searchQuery, StoreInfo.class); SearchPageStoreInfo page SearchHitSupport.searchPageFor(searchHits, searchQuery.getPageable());这段代码跑通之后就可以在这个基础上不断加条件。比如加上分类筛选和价格区间BoolQueryBuilder boolQueryBuilder QueryBuilders.boolQuery(); boolQueryBuilder.filter(QueryBuilders.termQuery(city, 上海)); boolQueryBuilder.filter(QueryBuilders.termQuery(category, 火锅)); boolQueryBuilder.filter(QueryBuilders.rangeQuery(avgPrice).gte(50).lte(200)); NativeSearchQuery searchQuery new NativeSearchQuery(boolQueryBuilder);这里每一行都是独立的语义代码读起来很清楚。你甚至可以先把所有过滤条件封装到一个方法里方法返回BoolQueryBuilder后续业务加筛选条件就只改这个方法查询入口完全不用动。关于NativeSearchQuery还有个容易忽略的细节这个类本身已经废弃了一些构造方式新版本更推荐直接构建Query对象传入SearchSourceBuilder。但不管API怎么演进核心逻辑都是一样的——你先构建出QueryBuilder然后把它塞进整个Search查询对象里。3.4 全文搜索与精确匹配的取舍在实际业务里我发现最容易让新手纠结的就是什么时候用match什么时候用term。我提供一个非常简单的判断标准只要是给用户输入框使用的搜索词一律用match只要是对字段做程序化过滤比如下拉筛选项、勾选状态、指定ID列表一律用term或terms。原因在于match查询会先对搜索关键词做分词然后再去匹配分词后的词项列表。比如用户输入“好吃的火锅”分词器会把这句话拆成“好吃”“的”“火锅”等词然后逐个去匹配文档里的字段内容而term查询不会做分词它把“好吃的火锅”这个完整字符串当成一个整体去匹配词项。如果字段本身是Keyword类型term是能匹配上的但如果字段是Text类型索引里存的是分词后的结果拿“好吃的火锅”整句去term匹配几乎匹配不到除非某个词项恰好包含了整句内容。下面用代码演示两种典型查法// 全文搜索门店名 QueryBuilders.matchQuery(storeName, keyword); // 精确匹配某个分类 QueryBuilders.termQuery(category, 火锅);区别就一句话分词或不分词。这两个如果不搞清楚后面所有查询都会出问题尤其是当你发现某个条件单独查没问题、组合起来却少数据的时候十有八九就是分词字段和精确匹配混用了。3.5 范围查询和时间范围的处理范围查询在门店搜索里对应的是价格、评分这类数值属性在订单系统里对应的是时间范围。用法很直接// 价格区间 QueryBuilders.rangeQuery(avgPrice).gte(50).lte(200); // 评分不低于4.5 QueryBuilders.rangeQuery(rating).gte(4.5); // 时间范围注意时区问题 QueryBuilders.rangeQuery(createTime) .gte(2024-01-01T00:00:00) .lte(2024-12-31T23:59:59);这里要提醒一个极易踩的坑时间字段在ES里如果按Date类型存储默认格式通常是带时区的ISO标准格式。如果你从前端拿到一个LocalDateTime直接转成字符串传进去时区对不上会导致查询结果偏差好几个小时。我自己的处理方式是统一在服务端把时间转成Instant或者带时区的格式化字符串再传给RangeQueryBuilder。如果你用的是Field(type FieldType.Date)建议在实体上指定日期格式例如format DateFormat.date_hour_minute_second这样查询时字符串格式、索引映射格式、返回结果格式全部对齐。4. 核心环节实操一个可复用的动态条件查询服务4.1 先从业务需求出发拆解条件搜索服务最常见的形态是“传入一个查询对象根据非空字段动态组合查询条件”。比如前端可能传来这样的请求参数关键词可选、城市可选、分类可选、最低评分可选、价格上限可选、是否营业可选。后端要做的事情其实很纯粹哪个字段有值就往BoolQueryBuilder里追加对应的条件哪个字段为空就跳过这个条件。这段逻辑本身不复杂但如果不做代码结构上的整理很容易写成一个几十行不断if拼接的“面条代码”。我建议把每个条件的构建逻辑抽成独立方法主流程只负责组合。下面是我在项目里沉淀下来的一个示例结构。4.2 代码实现查询条件构建器先定义一个查询参数类Data public class StoreSearchQuery { private String keyword; private String city; private String category; private Double minRating; private Double maxPrice; private Boolean isOpen; private Integer pageNum 1; private Integer pageSize 10; }然后构建查询条件Service RequiredArgsConstructor public class StoreSearchService { private final ElasticsearchRestTemplate elasticsearchRestTemplate; public SearchPageStoreInfo search(StoreSearchQuery query) { BoolQueryBuilder boolQueryBuilder QueryBuilders.boolQuery(); // 关键词全文搜索影响评分 if (StringUtils.hasText(query.getKeyword())) { boolQueryBuilder.must(QueryBuilders.matchQuery(storeName, query.getKeyword())); } // 城市精确过滤不参与评分 if (StringUtils.hasText(query.getCity())) { boolQueryBuilder.filter(QueryBuilders.termQuery(city, query.getCity())); } // 分类精确过滤不参与评分 if (StringUtils.hasText(query.getCategory())) { boolQueryBuilder.filter(QueryBuilders.termQuery(category, query.getCategory())); } // 评分下限 if (query.getMinRating() ! null) { boolQueryBuilder.filter(QueryBuilders.rangeQuery(rating).gte(query.getMinRating())); } // 价格上限 if (query.getMaxPrice() ! null) { boolQueryBuilder.filter(QueryBuilders.rangeQuery(avgPrice).lte(query.getMaxPrice())); } // 营业状态 if (query.getIsOpen() ! null) { boolQueryBuilder.filter(QueryBuilders.termQuery(isOpen, query.getIsOpen())); } NativeSearchQuery searchQuery new NativeSearchQuery(boolQueryBuilder); searchQuery.setPageable(PageRequest.of(query.getPageNum() - 1, query.getPageSize())); SearchHitsStoreInfo searchHits elasticsearchRestTemplate.search(searchQuery, StoreInfo.class); return SearchHitSupport.searchPageFor(searchHits, searchQuery.getPageable()); } }这段代码的可读性就在于你一眼就能看出每个业务条件对应哪个ES查询条件而且在“关键词为空”的时候must里不会有任何条件查询就自动退化为纯过滤查询。加分页的时候也记得一点——用户传pageNum1但ES的PageRequest是从0页开始的所以这里要做pageNum - 1的转换这也是一个很常见的初学者问题。4.3 关键字搜索多个字段的写法很多时候用户输入的关键词并不只想匹配一个字段。比如搜索“海底捞”可能门店名里有也可能描述文案里有。这时候常见的做法是把关键词同时匹配多个字段然后在逻辑上取“或”关系。QueryBuilder里有专门的写法QueryBuilder multiMatch QueryBuilders.multiMatchQuery(keyword, storeName, description); boolQueryBuilder.must(multiMatch);上面的代码等同于同时用storeName和description两个字段去匹配同一段关键词只要任意一个字段匹配上文档就被召回。这个写法比分别构建两个match查询再用should组合要简洁得多而且在相关性评分上ES会统一考虑各字段的匹配程度结果更符合直觉。如果业务上还要求某些字段权重更高比如门店名匹配的权重高于描述可以进一步用field^boost的语法指定权重QueryBuilder multiMatch QueryBuilders.multiMatchQuery(keyword, storeName^3, description);意思就是“门店名”字段匹配到的得分权重是“描述”字段的三倍。这个细节在搜索结果排序精度要求较高的场景里非常有用。4.4 分页、排序与高亮的组装搜索服务还有一个基本逃不掉的需求就是分页和排序。这里需要大家记住一个ES的安全底线from size不能超过index.max_result_window默认的10000否则查询会直接报错。如果业务确实会遇到深分页场景就需要改用search_after或者游标方案这属于另一个话题。普通管理后台类的搜索到10000条以前基本够用。排序的写法也很直观。比如按评分降序、按距离升序假设有地理位置数据searchQuery.addSort(SortBuilders.fieldSort(rating).order(SortOrder.DESC)); searchQuery.addSort(SortBuilders.geoDistanceSort(location, 31.2304, 121.4737).order(SortOrder.ASC));上面这行geoDistanceSort适用的情况是索引里存了经纬度坐标用户期望按照“离我最近”的顺序展示结果。这是ES在搜索场景里比起MySQL要便利得多的一项能力——SQL要写复杂的地理计算ES直接在排序阶段把距离算出来了。高亮返回是全文搜索体验里的重头戏。在QueryBuilder之外NativeSearchQuery同样可以设置高亮字段和标签HighlightBuilder highlightBuilder new HighlightBuilder(); HighlightBuilder.Field highlightName new HighlightBuilder.Field(storeName) .preTags(span stylecolor:red) .postTags(/span); highlightBuilder.field(highlightName); searchQuery.setHighlightBuilder(highlightBuilder);搜索结果获取高亮片段的方式SearchHitStoreInfo searchHit ...; ListString highlights searchHit.getHighlightFields().get(storeName);拿到了高亮片段以后前端展示搜索结果时就能直接渲染带红色标记的关键词体验会明显好于“搜索后只展示原文”。4.5 聚合统计的简单应用搜索场景里免不了要展示“按城市分组有多少家店”“每个分类下有哪些门店”。这种需求在ES里对应的是聚合Aggregation。聚合和QueryBuilder是独立的体系但经常配合使用。QueryBuilder先决定搜哪些文档聚合再对这堆文档做统计。举个例子在搜索“火锅”的结果中按城市统计门店数量TermsAggregationBuilder cityAgg AggregationBuilders.terms(cityAgg) .field(city) .size(20); NativeSearchQuery withAggQuery new NativeSearchQuery(boolQueryBuilder); withAggQuery.addAggregation(cityAgg);返回结果里通过Aggregations解析桶数据就能拿到“上海有150家、北京有96家”这种维度的统计结果。这个能力在做筛选栏动态展示和报表分析的时候非常实用相当于把原来要单独发一个SQL分组统计请求的事合并到同一个搜索请求里完成了。5. 复杂场景进阶多条件组合、嵌套查询与脚本字段5.1 should与minimumShouldMatch的搭配should子句代表的是“或”关系但很多人忽略了一个细节在只有should没有must和filter的BoolQuery里should至少匹配一个条件文档才会被召回但如果一个BoolQuery里同时有must和should那should条件默认不强制满足。也就是说should是否必须生效取决于上下文里有没有其他强制条件。这个默认行为很容易造成一种“查询条件写了但没生效”的错觉。比如用户想搜“上海”地区的门店同时也希望能匹配“火锅”或者“烧烤”分类如果你把“上海”放进filter把两个分类放进should结果可能就会变成所有上海门店都返回了分类筛选形同虚设。原因就是should不强制满足。解决办法是显式指定minimumShouldMatchboolQueryBuilder.should(QueryBuilders.termQuery(category, 火锅)); boolQueryBuilder.should(QueryBuilders.termQuery(category, 烧烤)); boolQueryBuilder.minimumShouldMatch(1);这样语义才真正等同于“上海且火锅或烧烤”。我建议项目里只要用到should就明确写出minimumShouldMatch的值不要依赖默认行为避免不同ES版本升级后行为出现偏差时无从排查。5.2 嵌套对象查询门店索引里如果存了多套餐具或服务项目并且每个项目都带有自己的属性那会涉及到nested类型。ES对nested对象做条件查询如果直接拼term会失效必须使用专门的嵌套查询语法。假设实体里有个字段Field(type FieldType.Nested) private ListStoreFacility facilities;要查询“提供免费WiFi且支持24小时营业”的门店QueryBuilder写法是QueryBuilders.nestedQuery(facilities, QueryBuilders.boolQuery() .must(QueryBuilders.termQuery(facilities.name, wifi)) .must(QueryBuilders.termQuery(facilities.available, true)), ScoreMode.None);这里有个关键点nestedQuery内部的条件字段路径必须带上外层嵌套字段的完整路径名比如facilities.name不能只写name。这个坑我也踩过当时查结果一直为空排查了很久才发现是路径写短了。另外ScoreMode的选择也有讲究None表示不参与评分Avg、Max等会影响到最终相关性排序结果除非特意需要一般我用None。5.3 脚本字段做动态计算有些业务需要返回在搜索时动态计算的字段值。比如门店搜索的结果里要算出门店当前评分与区域平均评分的一个差值这类逻辑不适合在Java代码里循环算因为会徒增内存和耗时。ES支持在查询时用Script字段动态生成NativeSearchQuery searchQuery new NativeSearchQuery(boolQueryBuilder); searchQuery.addScriptField(ratingDiff, new Script(ScriptType.INLINE, painless, doc[rating].value - params.avgRating, Collections.singletonMap(avgRating, 4.5)));返回结果里动态字段的获取方式是searchHit.getFields().get(ratingDiff).getValue();Script能力很灵活但也要慎用。它是在ES的每个分片上执行脚本复杂的脚本会对查询性能有比较明显的影响。能用doc取值就尽量不要加载整个_source文档脚本里也尽量别写循环遍历的逻辑。6. 常见问题与排查技巧实录6.1 查询结果为空但直接在Kibana里查有数据这是出现频率最高的问题。原因绝大多数是字段类型不匹配比如索引里某个字段是Text类型但代码里用了termQuery做精确匹配。排查方法很简单先在Kibana或者Dev Tools里执行GET store_info/_mapping看字段的真实类型再回看代码里的QueryBuilder使用方式。如果字段是Text而你确实需要精确匹配正确的办法是对这个字段额外配置一个.keyword子字段然后用termQuery(storeName.keyword, 海底捞)来查询。顺带一提在Spring Data Elasticsearch实体里可以用Field(type FieldType.Text, fielddata true)为Text字段启用fielddata但通常不建议这么干因为fielddata会占用大量堆内存。更推荐的方式是为需要精确匹配的字段单独定义Keyword子字段。6.2 bool查询里must和filter混用导致评分异常有一段时间我们线上搜索结果的相关性排序很奇怪明明完全匹配“海底捞”的门店却排在了只提到“海底捞式服务”的门店后面。排查下来发现问题出在很多人把搜索词同时放进了must和filterfilter负责过滤must负责评分结果同一个条件被计算了两次干扰了评分。解决方式其实很简单——一个查询条件只用一种身份存在。如果只是过滤就放filter如果要影响评分就放must。不要两个都放。这个问题的背后其实是理解上的一个误区同学容易把filter直接等同于SQL里的AND却忽略了它“不计分”的特性。正确的做法是按需求把条件分成两类一类是“结果里必须包含但用户并不在意它如何影响排序”的如城市、营业状态、价格区间另一类是“用户搜索时明确输入的关键内容”如关键词要影响评分。分开管理后排序结果才符合直觉。6.3 深分页报错页码翻到几百页的时候ES突然抛Result window is too large异常。这是from size超过默认max_result_window10000导致的。对于用户端搜索建议通过search_after方案解决如果是后台导出场景建议用Scroll游标方案。不过这两种方案都有各自的限制search_after依赖排序字段保证稳定性Scroll在快照期间数据更新可能不一致。如果你的业务里页码不需要超过100页那用最普通的from size分页就完全足够了不要为了形式上好看去上Scroll复杂度会大很多。6.4 时区差8小时时间字段搜索范围差出8小时是开发环境里特别经典的问题。排查方向主要在两点Es客户端连接串的时区配置以及Java侧传入时间字符串的时区。ES默认时区是UTC如果Java侧传入的字符串不带时区ES会按UTC解析但业务实际时间可能是东八区。最简单的统一办法是在Java侧把时间转成Instant带时区信息再传入索引映射的时间格式里明确指定时区或者全局配置集群时区。只要保证写入、查询、展示三段都使用同一时区基准这个坑就能彻底绕开。6.5 字段名没有显式声明导致搜索不到还有一次我们的查询条件明明正确、字段类型也正确但结果为空最后发现是实体里缺少Field注解框架默认把字段映射成了Keyword类型。所以当发现“类型看起来不对”的时候先别急着怀疑ES回去翻一下实体类上的字段注解确认映射符合预期。尤其是新加的字段最容易被遗漏。7. 那个夜间上线后的教训一次真实的故障复盘最后这段不是额外总结而是我实际经历过的一个教训。那次事故的起因很简单我们要上线一个新搜索功能我在本地测试时一切正常数据没问题查询速度也快。结果上线之后第二天早上业务反馈“搜索不到新增门店”。我登录Kibana一查索引里有数据但查询结果就是少几条。排查了半天发现是新增门店的isOpen状态字段在索引映射里是Text类型而查询里用的termQuery。因为索引创建于最初版本新字段靠动态映射生成ES把布尔值自动映射成了Text。当时代码里没有显式声明字段类型全靠ES猜。它猜的结果和我们查询的方式不匹配数据就永远查不到。那次之后我有了一个非常顽固的操作习惯任何涉及到索引字段的改动第一件事就是确认线上索引的真实映射。实体注解只是开发时的约定真正生效的是索引里已经存在的mapping。如果索引是历史创建的加新字段时必须通过ES的_mapping接口做增量更新而不是指望实体类改一下就能自动同步。还提醒一点生产环境尽量不用“自动创建索引”这个能力。开发环境图省事可以但在生产环境索引的shard数量、分片副本、分词器、字段类型都应该经过设计后由脚本或配置统一管理。否则一旦出现映射和代码不一致的问题线上搜索会变得非常被动。如果让我给一个最快上手路径的建议先搭一个最小可运行的SpringBoot工程把ElasticsearchRestTemplate打通然后照着本文第三、第四部分的内容跑通单条件、多条件、动态组合三个场景。跑通之后再去研究聚合、排序、高亮这些附加能力。QueryBuilder学起来不复杂真正有价值的是你能够在业务里熟练判断哪个条件该放must、哪个该放filter、哪个字段该用term、哪个该用match。这些判断一旦形成肌肉记忆ES条件查询这块基本就没什么能难住你的了。
大概两年前我接手了一个基于SpringBoot的搜索服务改造项目。原来的实现是这样的所有筛选条件拼成SQL靠MySQL的LIKE查询硬扛。数据量在百万级的时候还能忍等到某个业务表冲到三千万行一次带多个条件的模糊查询直接飙到三秒多接口超时告警一天能响几十次。后来把搜索链路替换成了ElasticSearch核心查询构建用的是Spring Data Elasticsearch里的QueryBuilder线上接口的耗时从三秒多降到了几十毫秒。这篇文章就把我在这个改造过程中对QueryBuilder的完整理解、实际踩过的坑和最终沉淀下来的代码组织方式整理出来希望能给正打算在SpringBoot项目里接入ES条件查询的同学一些参考。这套东西我自己使用下来的感受是它并不是一套门槛很高的技术但里面一些细节确实坑了不少人尤其是第一次从SQL思维切到ES思维的时候最容易在bool查询、term与match的区分、以及动态拼接条件这几块上懵。我会从最基础的依赖版本开始一直讲到组合查询怎么写再配合排查实录尽量让这篇内容能做到“看完能直接照着写”。1. 项目整体思路拆解为什么选择QueryBuilder而不是写死JSON先说个很多人刚接触Spring Data Elasticsearch时的困惑既然ES本身提供一整套REST API直接把JSON查询串写在代码里不就行了吗为什么要用QueryBuilder我的答案是如果你只是写一个固定不变的查询直接上JSON字符串确实更直观、更贴近ES原生语法。但现实业务里的搜索条件几乎不会是固定的用户可能选城市、可能筛价格区间、可能只按分类过滤、也可能什么都不选只做一个关键词搜索。这种“动态拼条件”的场景如果靠字符串拼接JSON代码会很快失控而且很容易在拼接过程中漏掉引号、多一个逗号线上查不出数据的时候排查成本极高。QueryBuilder的价值就在于它用Java对象来描述查询逻辑允许你在代码里以编程的方式按需组合条件构建过程本身就是一段可维护的逻辑而不是一堆要被解析的文本。还有一个很重要的原因QueryBuilder最终会由框架转化成ES可以理解的查询DSL。也就是说你不需要自己关心JSON结构长什么样框架帮你序列化出错概率低很多。像我接手那个搜索服务时团队之所以选这种方式核心就是后续扩展方便。比如今天只支持“关键词城市”两个条件明天业务说要加一个“人均消费区间”那只需要在构建QueryBuilder的地方追加一个RangeQueryBuilder不需要改动拼接JSON的逻辑和对应的解析器。另外要说明的是Spring Data Elasticsearch在不同版本里对QueryBuilder的封装是有差异的后面会单独讲版本兼容问题。整体思路确认后项目落地的顺序大致是先准备依赖和连接配置再根据业务字段建好索引映射然后核心地实现查询构建服务最后统一封装返回结果、做分页和排序。下面按这个顺序把关键环节挨个拆开。2. 环境准备与基础配置版本选型是第一个大坑2.1 依赖引入与版本对应关系Spring Data Elasticsearch和Elasticsearch之间的版本兼容是出了名的“一不留神就翻车”。我见过不止一个项目因为依赖版本没对齐启动时直接抛UnsupportedOperationException或者NoSuchMethodError排查半天才发现是客户端版本和服务端版本不匹配。我自己目前用得比较多、也比较推荐的一套组合是SpringBoot 2.7.x Spring Data Elasticsearch 4.4.x Elasticsearch 7.17.x。如果你用的是SpringBoot 2.7可以在pom.xml里这样引入parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version2.7.18/version relativePath/ /parent dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-data-elasticsearch/artifactId /dependency /dependencies这里需要注意一个关键点SpringBoot的BOM已经帮你锁定了spring-boot-starter-data-elasticsearch对应的版本所以正常情况下不需要手动指定spring-data-elasticsearch和elasticsearch这两个jar的版本号。但如果你在私服或者公司内部仓库里单独引了ES的依赖并且版本不是7.17.x那启动时大概率会遇到客户端与服务端版本协商失败的问题。如果不确定自己该用哪套版本组合最稳妥的方法是到Spring Data Elasticsearch官方文档里查“Version Compatibility”表格确保spring-data-elasticsearch的版本和你的ES集群主版本对齐。2.2 连接配置配置项写在application.yml里我习惯用下面这套spring: elasticsearch: uris: - http://localhost:9200 connection-timeout: 3s read-timeout: 10s socket-timeout: 30s注意属性名是spring.elasticsearch.uris而不是spring.elasticsearch.host这是SpringBoot 2.x比较新的写法很多人沿用老版本的习惯写host结果发现配置不生效。连接超时和读取超时这两个参数建议一定要显式配置默认值在某些生产环境里会表现得过于“乐观”如果ES集群压力大、响应慢客户端会长时间挂住不报错接口调用方那边看起来就像是服务假死。配置好连接之后下一步就是定义索引实体。实体定义这一块直接决定了后面QueryBuilder里面字段名怎么使用所以我会把字段映射的规范放在查询之前的准备工作里讲清楚。2.3 索引实体与字段映射注意点我用一个实际的业务场景来举例。假设我们做一个门店搜索索引里存了门店名称、所属城市、分类、人均消费、评分、经纬度、营业状态等字段。对应的实体类大致是这样的Data Document(indexName store_info) public class StoreInfo { Id private String id; Field(type FieldType.Keyword) private String city; Field(type FieldType.Keyword) private String category; Field(type FieldType.Text, analyzer ik_max_word) private String storeName; Field(type FieldType.Text, analyzer ik_max_word) private String description; Field(type FieldType.Double) private Double avgPrice; Field(type FieldType.Double) private Double rating; Field(type FieldType.Boolean) private Boolean isOpen; }字段类型的选择是这里面的核心细节。ES的Text和Keyword是两种查询方式截然不同的类型Keyword类型不分词适合精确匹配、过滤、聚合排序Text类型会经过分析器分词适合全文搜索。像我上面的门店名称和描述因为要做“关键词搜索”的效果所以用Text加ik_max_word中文分词而城市和分类是要精确筛选的就用Keyword。如果这个映射关系没想清楚后面写QueryBuilder的时候就会出现很典型的问题用term查询一个Text字段往往什么都查不到因为Text字段在索引时已经被分词器拆成了多个词项term默认不做分析拿整个输入去匹配词项自然匹配不上。这个问题后面在“常见问题”部分还会再展开。实体类定义好以后可以用ElasticsearchRestTemplate的indexOps()方法创建索引也可以让框架在启动时自动根据实体创建。我建议在开发环境可以自动创建但生产环境最好预先通过ES的API或者专门的初始化任务来建索引因为生产索引的shard数量、副本数、分词器配置往往比实体注解里能表达的东西更复杂。3. 条件查询核心拆解从简单条件到组合条件3.1 几个最常用的QueryBuilder实现类Spring Data Elasticsearch里所有具体的QueryBuilder实现都会实现org.elasticsearch.index.query.QueryBuilder这个顶层接口。我在日常开发中最常用的是下面这几个实现类作用使用场景MatchQueryBuilder分词匹配查询搜索名称、描述、内容等需要分词的字段TermQueryBuilder精确词项查询精确匹配某个ID、分类、状态等不分词字段TermsQueryBuilder多个精确值查询类似SQL里的IN查询RangeQueryBuilder范围查询价格区间、时间范围、数值区间BoolQueryBuilder布尔组合查询把多个条件组合在一起WildcardQueryBuilder通配符查询模糊匹配但性能开销较大需慎用这些类在使用上有一个通用的规律每个QueryBuilder一般都有对应的静态方法可以通过QueryBuilders.xxx()一行代码创建出来。比如QueryBuilders.matchQuery(storeName, 火锅)、QueryBuilders.termQuery(city, 上海)。这种方式写起来简洁团队里其他人读代码的时候也能一眼看出查询意图。3.2 BoolQueryBuilder条件组合的地基真实的搜索场景里几乎没有只靠一个单一条件就能搞定需求的。我自己的经验是90%以上的查询最终都得落到BoolQueryBuilder上。它的核心逻辑是用四个子句来组织条件must文档必须满足所有条件参与相关性评分。filter文档必须满足条件但不参与评分性能更好。should文档满足任意一个条件即可最少满足数由minimumShouldMatch控制。mustNot文档不能满足条件相当于排除。用SQL来类比的话must和filter都相当于ANDshould相当于ORmustNot相当于NOT。但must和filter在ES内部有一个核心差别——filter会使用缓存查询速度更快。所以我的习惯是纯过滤性质的等值条件、范围条件、状态条件全部放到filter里只有影响相关性排序的全文搜索条件才放到must里。举个例子用户搜“火锅”同时筛选城市为“上海”那“火锅”放进must“城市”放进filter因为城市这个条件并不需要影响相关性我们只需要它做过滤。3.3 从第一个简单查询到组合查询的完整演变先说最简单的单条件查询。用Spring Data Elasticsearch的ElasticsearchRestTemplate配合NativeSearchQuery核心代码像这样QueryBuilder queryBuilder QueryBuilders.termQuery(city, 上海); SearchSourceBuilder sourceBuilder new SearchSourceBuilder(); sourceBuilder.query(queryBuilder); NativeSearchQuery searchQuery new NativeSearchQuery(queryBuilder); searchQuery.setPageable(PageRequest.of(0, 10)); SearchHitsStoreInfo searchHits elasticsearchRestTemplate.search(searchQuery, StoreInfo.class); SearchPageStoreInfo page SearchHitSupport.searchPageFor(searchHits, searchQuery.getPageable());这段代码跑通之后就可以在这个基础上不断加条件。比如加上分类筛选和价格区间BoolQueryBuilder boolQueryBuilder QueryBuilders.boolQuery(); boolQueryBuilder.filter(QueryBuilders.termQuery(city, 上海)); boolQueryBuilder.filter(QueryBuilders.termQuery(category, 火锅)); boolQueryBuilder.filter(QueryBuilders.rangeQuery(avgPrice).gte(50).lte(200)); NativeSearchQuery searchQuery new NativeSearchQuery(boolQueryBuilder);这里每一行都是独立的语义代码读起来很清楚。你甚至可以先把所有过滤条件封装到一个方法里方法返回BoolQueryBuilder后续业务加筛选条件就只改这个方法查询入口完全不用动。关于NativeSearchQuery还有个容易忽略的细节这个类本身已经废弃了一些构造方式新版本更推荐直接构建Query对象传入SearchSourceBuilder。但不管API怎么演进核心逻辑都是一样的——你先构建出QueryBuilder然后把它塞进整个Search查询对象里。3.4 全文搜索与精确匹配的取舍在实际业务里我发现最容易让新手纠结的就是什么时候用match什么时候用term。我提供一个非常简单的判断标准只要是给用户输入框使用的搜索词一律用match只要是对字段做程序化过滤比如下拉筛选项、勾选状态、指定ID列表一律用term或terms。原因在于match查询会先对搜索关键词做分词然后再去匹配分词后的词项列表。比如用户输入“好吃的火锅”分词器会把这句话拆成“好吃”“的”“火锅”等词然后逐个去匹配文档里的字段内容而term查询不会做分词它把“好吃的火锅”这个完整字符串当成一个整体去匹配词项。如果字段本身是Keyword类型term是能匹配上的但如果字段是Text类型索引里存的是分词后的结果拿“好吃的火锅”整句去term匹配几乎匹配不到除非某个词项恰好包含了整句内容。下面用代码演示两种典型查法// 全文搜索门店名 QueryBuilders.matchQuery(storeName, keyword); // 精确匹配某个分类 QueryBuilders.termQuery(category, 火锅);区别就一句话分词或不分词。这两个如果不搞清楚后面所有查询都会出问题尤其是当你发现某个条件单独查没问题、组合起来却少数据的时候十有八九就是分词字段和精确匹配混用了。3.5 范围查询和时间范围的处理范围查询在门店搜索里对应的是价格、评分这类数值属性在订单系统里对应的是时间范围。用法很直接// 价格区间 QueryBuilders.rangeQuery(avgPrice).gte(50).lte(200); // 评分不低于4.5 QueryBuilders.rangeQuery(rating).gte(4.5); // 时间范围注意时区问题 QueryBuilders.rangeQuery(createTime) .gte(2024-01-01T00:00:00) .lte(2024-12-31T23:59:59);这里要提醒一个极易踩的坑时间字段在ES里如果按Date类型存储默认格式通常是带时区的ISO标准格式。如果你从前端拿到一个LocalDateTime直接转成字符串传进去时区对不上会导致查询结果偏差好几个小时。我自己的处理方式是统一在服务端把时间转成Instant或者带时区的格式化字符串再传给RangeQueryBuilder。如果你用的是Field(type FieldType.Date)建议在实体上指定日期格式例如format DateFormat.date_hour_minute_second这样查询时字符串格式、索引映射格式、返回结果格式全部对齐。4. 核心环节实操一个可复用的动态条件查询服务4.1 先从业务需求出发拆解条件搜索服务最常见的形态是“传入一个查询对象根据非空字段动态组合查询条件”。比如前端可能传来这样的请求参数关键词可选、城市可选、分类可选、最低评分可选、价格上限可选、是否营业可选。后端要做的事情其实很纯粹哪个字段有值就往BoolQueryBuilder里追加对应的条件哪个字段为空就跳过这个条件。这段逻辑本身不复杂但如果不做代码结构上的整理很容易写成一个几十行不断if拼接的“面条代码”。我建议把每个条件的构建逻辑抽成独立方法主流程只负责组合。下面是我在项目里沉淀下来的一个示例结构。4.2 代码实现查询条件构建器先定义一个查询参数类Data public class StoreSearchQuery { private String keyword; private String city; private String category; private Double minRating; private Double maxPrice; private Boolean isOpen; private Integer pageNum 1; private Integer pageSize 10; }然后构建查询条件Service RequiredArgsConstructor public class StoreSearchService { private final ElasticsearchRestTemplate elasticsearchRestTemplate; public SearchPageStoreInfo search(StoreSearchQuery query) { BoolQueryBuilder boolQueryBuilder QueryBuilders.boolQuery(); // 关键词全文搜索影响评分 if (StringUtils.hasText(query.getKeyword())) { boolQueryBuilder.must(QueryBuilders.matchQuery(storeName, query.getKeyword())); } // 城市精确过滤不参与评分 if (StringUtils.hasText(query.getCity())) { boolQueryBuilder.filter(QueryBuilders.termQuery(city, query.getCity())); } // 分类精确过滤不参与评分 if (StringUtils.hasText(query.getCategory())) { boolQueryBuilder.filter(QueryBuilders.termQuery(category, query.getCategory())); } // 评分下限 if (query.getMinRating() ! null) { boolQueryBuilder.filter(QueryBuilders.rangeQuery(rating).gte(query.getMinRating())); } // 价格上限 if (query.getMaxPrice() ! null) { boolQueryBuilder.filter(QueryBuilders.rangeQuery(avgPrice).lte(query.getMaxPrice())); } // 营业状态 if (query.getIsOpen() ! null) { boolQueryBuilder.filter(QueryBuilders.termQuery(isOpen, query.getIsOpen())); } NativeSearchQuery searchQuery new NativeSearchQuery(boolQueryBuilder); searchQuery.setPageable(PageRequest.of(query.getPageNum() - 1, query.getPageSize())); SearchHitsStoreInfo searchHits elasticsearchRestTemplate.search(searchQuery, StoreInfo.class); return SearchHitSupport.searchPageFor(searchHits, searchQuery.getPageable()); } }这段代码的可读性就在于你一眼就能看出每个业务条件对应哪个ES查询条件而且在“关键词为空”的时候must里不会有任何条件查询就自动退化为纯过滤查询。加分页的时候也记得一点——用户传pageNum1但ES的PageRequest是从0页开始的所以这里要做pageNum - 1的转换这也是一个很常见的初学者问题。4.3 关键字搜索多个字段的写法很多时候用户输入的关键词并不只想匹配一个字段。比如搜索“海底捞”可能门店名里有也可能描述文案里有。这时候常见的做法是把关键词同时匹配多个字段然后在逻辑上取“或”关系。QueryBuilder里有专门的写法QueryBuilder multiMatch QueryBuilders.multiMatchQuery(keyword, storeName, description); boolQueryBuilder.must(multiMatch);上面的代码等同于同时用storeName和description两个字段去匹配同一段关键词只要任意一个字段匹配上文档就被召回。这个写法比分别构建两个match查询再用should组合要简洁得多而且在相关性评分上ES会统一考虑各字段的匹配程度结果更符合直觉。如果业务上还要求某些字段权重更高比如门店名匹配的权重高于描述可以进一步用field^boost的语法指定权重QueryBuilder multiMatch QueryBuilders.multiMatchQuery(keyword, storeName^3, description);意思就是“门店名”字段匹配到的得分权重是“描述”字段的三倍。这个细节在搜索结果排序精度要求较高的场景里非常有用。4.4 分页、排序与高亮的组装搜索服务还有一个基本逃不掉的需求就是分页和排序。这里需要大家记住一个ES的安全底线from size不能超过index.max_result_window默认的10000否则查询会直接报错。如果业务确实会遇到深分页场景就需要改用search_after或者游标方案这属于另一个话题。普通管理后台类的搜索到10000条以前基本够用。排序的写法也很直观。比如按评分降序、按距离升序假设有地理位置数据searchQuery.addSort(SortBuilders.fieldSort(rating).order(SortOrder.DESC)); searchQuery.addSort(SortBuilders.geoDistanceSort(location, 31.2304, 121.4737).order(SortOrder.ASC));上面这行geoDistanceSort适用的情况是索引里存了经纬度坐标用户期望按照“离我最近”的顺序展示结果。这是ES在搜索场景里比起MySQL要便利得多的一项能力——SQL要写复杂的地理计算ES直接在排序阶段把距离算出来了。高亮返回是全文搜索体验里的重头戏。在QueryBuilder之外NativeSearchQuery同样可以设置高亮字段和标签HighlightBuilder highlightBuilder new HighlightBuilder(); HighlightBuilder.Field highlightName new HighlightBuilder.Field(storeName) .preTags(span stylecolor:red) .postTags(/span); highlightBuilder.field(highlightName); searchQuery.setHighlightBuilder(highlightBuilder);搜索结果获取高亮片段的方式SearchHitStoreInfo searchHit ...; ListString highlights searchHit.getHighlightFields().get(storeName);拿到了高亮片段以后前端展示搜索结果时就能直接渲染带红色标记的关键词体验会明显好于“搜索后只展示原文”。4.5 聚合统计的简单应用搜索场景里免不了要展示“按城市分组有多少家店”“每个分类下有哪些门店”。这种需求在ES里对应的是聚合Aggregation。聚合和QueryBuilder是独立的体系但经常配合使用。QueryBuilder先决定搜哪些文档聚合再对这堆文档做统计。举个例子在搜索“火锅”的结果中按城市统计门店数量TermsAggregationBuilder cityAgg AggregationBuilders.terms(cityAgg) .field(city) .size(20); NativeSearchQuery withAggQuery new NativeSearchQuery(boolQueryBuilder); withAggQuery.addAggregation(cityAgg);返回结果里通过Aggregations解析桶数据就能拿到“上海有150家、北京有96家”这种维度的统计结果。这个能力在做筛选栏动态展示和报表分析的时候非常实用相当于把原来要单独发一个SQL分组统计请求的事合并到同一个搜索请求里完成了。5. 复杂场景进阶多条件组合、嵌套查询与脚本字段5.1 should与minimumShouldMatch的搭配should子句代表的是“或”关系但很多人忽略了一个细节在只有should没有must和filter的BoolQuery里should至少匹配一个条件文档才会被召回但如果一个BoolQuery里同时有must和should那should条件默认不强制满足。也就是说should是否必须生效取决于上下文里有没有其他强制条件。这个默认行为很容易造成一种“查询条件写了但没生效”的错觉。比如用户想搜“上海”地区的门店同时也希望能匹配“火锅”或者“烧烤”分类如果你把“上海”放进filter把两个分类放进should结果可能就会变成所有上海门店都返回了分类筛选形同虚设。原因就是should不强制满足。解决办法是显式指定minimumShouldMatchboolQueryBuilder.should(QueryBuilders.termQuery(category, 火锅)); boolQueryBuilder.should(QueryBuilders.termQuery(category, 烧烤)); boolQueryBuilder.minimumShouldMatch(1);这样语义才真正等同于“上海且火锅或烧烤”。我建议项目里只要用到should就明确写出minimumShouldMatch的值不要依赖默认行为避免不同ES版本升级后行为出现偏差时无从排查。5.2 嵌套对象查询门店索引里如果存了多套餐具或服务项目并且每个项目都带有自己的属性那会涉及到nested类型。ES对nested对象做条件查询如果直接拼term会失效必须使用专门的嵌套查询语法。假设实体里有个字段Field(type FieldType.Nested) private ListStoreFacility facilities;要查询“提供免费WiFi且支持24小时营业”的门店QueryBuilder写法是QueryBuilders.nestedQuery(facilities, QueryBuilders.boolQuery() .must(QueryBuilders.termQuery(facilities.name, wifi)) .must(QueryBuilders.termQuery(facilities.available, true)), ScoreMode.None);这里有个关键点nestedQuery内部的条件字段路径必须带上外层嵌套字段的完整路径名比如facilities.name不能只写name。这个坑我也踩过当时查结果一直为空排查了很久才发现是路径写短了。另外ScoreMode的选择也有讲究None表示不参与评分Avg、Max等会影响到最终相关性排序结果除非特意需要一般我用None。5.3 脚本字段做动态计算有些业务需要返回在搜索时动态计算的字段值。比如门店搜索的结果里要算出门店当前评分与区域平均评分的一个差值这类逻辑不适合在Java代码里循环算因为会徒增内存和耗时。ES支持在查询时用Script字段动态生成NativeSearchQuery searchQuery new NativeSearchQuery(boolQueryBuilder); searchQuery.addScriptField(ratingDiff, new Script(ScriptType.INLINE, painless, doc[rating].value - params.avgRating, Collections.singletonMap(avgRating, 4.5)));返回结果里动态字段的获取方式是searchHit.getFields().get(ratingDiff).getValue();Script能力很灵活但也要慎用。它是在ES的每个分片上执行脚本复杂的脚本会对查询性能有比较明显的影响。能用doc取值就尽量不要加载整个_source文档脚本里也尽量别写循环遍历的逻辑。6. 常见问题与排查技巧实录6.1 查询结果为空但直接在Kibana里查有数据这是出现频率最高的问题。原因绝大多数是字段类型不匹配比如索引里某个字段是Text类型但代码里用了termQuery做精确匹配。排查方法很简单先在Kibana或者Dev Tools里执行GET store_info/_mapping看字段的真实类型再回看代码里的QueryBuilder使用方式。如果字段是Text而你确实需要精确匹配正确的办法是对这个字段额外配置一个.keyword子字段然后用termQuery(storeName.keyword, 海底捞)来查询。顺带一提在Spring Data Elasticsearch实体里可以用Field(type FieldType.Text, fielddata true)为Text字段启用fielddata但通常不建议这么干因为fielddata会占用大量堆内存。更推荐的方式是为需要精确匹配的字段单独定义Keyword子字段。6.2 bool查询里must和filter混用导致评分异常有一段时间我们线上搜索结果的相关性排序很奇怪明明完全匹配“海底捞”的门店却排在了只提到“海底捞式服务”的门店后面。排查下来发现问题出在很多人把搜索词同时放进了must和filterfilter负责过滤must负责评分结果同一个条件被计算了两次干扰了评分。解决方式其实很简单——一个查询条件只用一种身份存在。如果只是过滤就放filter如果要影响评分就放must。不要两个都放。这个问题的背后其实是理解上的一个误区同学容易把filter直接等同于SQL里的AND却忽略了它“不计分”的特性。正确的做法是按需求把条件分成两类一类是“结果里必须包含但用户并不在意它如何影响排序”的如城市、营业状态、价格区间另一类是“用户搜索时明确输入的关键内容”如关键词要影响评分。分开管理后排序结果才符合直觉。6.3 深分页报错页码翻到几百页的时候ES突然抛Result window is too large异常。这是from size超过默认max_result_window10000导致的。对于用户端搜索建议通过search_after方案解决如果是后台导出场景建议用Scroll游标方案。不过这两种方案都有各自的限制search_after依赖排序字段保证稳定性Scroll在快照期间数据更新可能不一致。如果你的业务里页码不需要超过100页那用最普通的from size分页就完全足够了不要为了形式上好看去上Scroll复杂度会大很多。6.4 时区差8小时时间字段搜索范围差出8小时是开发环境里特别经典的问题。排查方向主要在两点Es客户端连接串的时区配置以及Java侧传入时间字符串的时区。ES默认时区是UTC如果Java侧传入的字符串不带时区ES会按UTC解析但业务实际时间可能是东八区。最简单的统一办法是在Java侧把时间转成Instant带时区信息再传入索引映射的时间格式里明确指定时区或者全局配置集群时区。只要保证写入、查询、展示三段都使用同一时区基准这个坑就能彻底绕开。6.5 字段名没有显式声明导致搜索不到还有一次我们的查询条件明明正确、字段类型也正确但结果为空最后发现是实体里缺少Field注解框架默认把字段映射成了Keyword类型。所以当发现“类型看起来不对”的时候先别急着怀疑ES回去翻一下实体类上的字段注解确认映射符合预期。尤其是新加的字段最容易被遗漏。7. 那个夜间上线后的教训一次真实的故障复盘最后这段不是额外总结而是我实际经历过的一个教训。那次事故的起因很简单我们要上线一个新搜索功能我在本地测试时一切正常数据没问题查询速度也快。结果上线之后第二天早上业务反馈“搜索不到新增门店”。我登录Kibana一查索引里有数据但查询结果就是少几条。排查了半天发现是新增门店的isOpen状态字段在索引映射里是Text类型而查询里用的termQuery。因为索引创建于最初版本新字段靠动态映射生成ES把布尔值自动映射成了Text。当时代码里没有显式声明字段类型全靠ES猜。它猜的结果和我们查询的方式不匹配数据就永远查不到。那次之后我有了一个非常顽固的操作习惯任何涉及到索引字段的改动第一件事就是确认线上索引的真实映射。实体注解只是开发时的约定真正生效的是索引里已经存在的mapping。如果索引是历史创建的加新字段时必须通过ES的_mapping接口做增量更新而不是指望实体类改一下就能自动同步。还提醒一点生产环境尽量不用“自动创建索引”这个能力。开发环境图省事可以但在生产环境索引的shard数量、分片副本、分词器、字段类型都应该经过设计后由脚本或配置统一管理。否则一旦出现映射和代码不一致的问题线上搜索会变得非常被动。如果让我给一个最快上手路径的建议先搭一个最小可运行的SpringBoot工程把ElasticsearchRestTemplate打通然后照着本文第三、第四部分的内容跑通单条件、多条件、动态组合三个场景。跑通之后再去研究聚合、排序、高亮这些附加能力。QueryBuilder学起来不复杂真正有价值的是你能够在业务里熟练判断哪个条件该放must、哪个该放filter、哪个字段该用term、哪个该用match。这些判断一旦形成肌肉记忆ES条件查询这块基本就没什么能难住你的了。
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
