★ FEATURED ARTICLE 做后端开发的同学基本都遇到过类似的需求用户在搜索框里输入一个词系统要把相关的文章、商品、文档一次性捞出来。数据量小的时候一句SQL里的LIKE %关键词%还能糊弄过去可一旦数据量上了几十万上百万那个查询慢得让人怀疑人生更别说还要按相关度排序、把命中的关键词标红。这篇文章就是我实际项目中把 SpringBoot 应用的搜索从数据库查询升级为全文检索方案的一段完整记录重点讲高级用法从方案选型、索引设计到组合查询、高亮、聚合再到生产环境常见的那些坑适合已经在用 SpringBoot 但还没系统做过全文检索的同学或者已经接入了 Elasticsearch下称 ES但用得比较糙、想补上高级姿势的朋友。1. 方案选型为什么数据库 LIKE 不够用1.1 LIKE 查询的固有缺陷很多人最开始做搜索第一反应就是在数据库里WHERE title LIKE %关键词%。数据量几千条时确实没问题但有几个天然缺陷会随着数据增长逐渐放大第一无法利用索引。MySQL 的 BTree 索引对前缀匹配友好对%关键词%这种中间匹配只能退化成全表扫描。我接手过一个模拟项目X文章表只有八十万行一次LIKE %并发%扫描加回表要 1.8 秒直接在接口里拖垮了整个请求链路。第二没有相关性排序。LIKE 查询要么匹配要么不匹配至于哪条结果更接近用户意图数据库完全没有概念。实际业务里用户搜SpringBoot 缓存时标题里完整出现这两个词的文档应该排在正文里出现一次但标题无关的文档前面这种需求 LIKE 做不到。第三中文分词无从谈起。用户搜逻辑回归你至少希望它能把逻辑回归逻辑回归都作为可命中项考虑。数据库的 LIKE 只能机械匹配连续字符串稍微换个说法就搜不到。1.2 备选方案横向对比做全文检索业界有几种常见选择我把它们的定位梳理一下方案核心原理优点缺点Lucene搜索引擎底层库提供倒排索引和分词能力性能强、灵活要自己处理索引生命周期、查询封装、集群问题开发成本极高Solr基于 Lucene 的搜索服务老牌稳定、文档较多实时性弱一些动态聚合与集群运维相对重Elasticsearch分布式全文检索引擎开箱即用、REST 接口、生态成熟、聚合分析强内存占用较高需要单独运维集群数据库自带 FULLTEXT数据库侧的全文索引无需引入新组件对中文分词支持弱排序能力有限分布式扩展难最终我选了 ES核心原因是它和 SpringBoot 生态结合得非常舒服。Spring Data Elasticsearch 提供了实体映射、Repository 风格查询、模板方法封装我可以用很熟悉的 Java 语法操作搜索引擎不用整天拼 REST JSON。同时 ES 的聚合分析能力是一等公民这在后续做分类统计、时间趋势分析时帮了大忙。另外提一句如果团队因为合规或技术路线原因不能直接用 ES下游开源分支 OpenSearch 的 API 大体兼容Spring Data 的接入方式几乎不用改这个路线也可以兜底。1.3 选型时容易忽略的决策点选全文检索方案时除了功能对比还要看团队熟悉度。ES 虽然不是最难运维的东西但 JVM 堆内存、分片数、索引生命周期都得有人管。如果团队只有两三个人且没有运维基础我反而建议先用托管服务把精力放在业务索引设计和查询优化上而不是一上来就自己搭三节点集群。2. 集成准备与索引设计2.1 版本兼容第一次踩坑的高发区SpringBoot 集成 ES第一步不是写代码而是确认版本对应关系。Spring Data Elasticsearch 的版本和 ES 大版本是绑定的我见过好几个人拿着 Spring Data Elasticsearch 4.2 去连 ES 8.0启动直接报版本不兼容。下面是我实际验证过的对应关系Spring Boot 版本Spring Data Elasticsearch 版本建议 ES 版本2.6.x4.2.x7.15.x - 7.17.x2.7.x4.4.x7.17.x3.0.x - 3.1.x5.0.x - 5.1.x8.5.x - 8.8.x3.2.x5.2.x8.10.x一旦版本不匹配最典型的症状是客户端初始化失败或者发请求时解析响应报错。排查时先看依赖树确认 Spring Data 版本再对照 ES 版本别一上来就怀疑代码写错。2.2 依赖引入与连接配置我以 Spring Boot 2.7 ES 7.17 为例这是目前最稳的组合之一。Maven 里加一个依赖就够dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-data-elasticsearch/artifactId /dependency然后在application.yml里配置连接信息spring: elasticsearch: uris: http://localhost:9200 connection-timeout: 5s socket-timeout: 30s username: elastic password: changeit注意 Spring Boot 2.7 里面这个配置项是spring.elasticsearch.uris早期版本可能是spring.elasticsearch.rest.uris如果你用的是老版配置格式化升级后要顺手改过来。连接超时设置也有讲究。ES 在数据量大的时候聚合或深分页查询响应可能超过默认的 1 秒如果你在网关层或服务间调用里设置了严格的超时搜索接口会频繁报超时。我一般把 socket 超时放到 30 秒连接超时放 5 秒给慢查询留余地再用后面讲到的慢查询日志去做性能治理。2.3 索引 Mapping字段类型与分词器ES 的核心是索引。索引的 mapping 相当于数据库表结构字段类型定义错了后面的查询和聚合都会跑偏。这一步是全文检索方案设计里最值得花时间的地方我甚至建议在动手写 SpringBoot 代码前先用 Kibana 的 Dev Tools 把 mapping 打磨好。以文章检索为例一个典型的 mapping 长这样{ mappings: { properties: { id: { type: long }, title: { type: text, analyzer: ik_max_word, search_analyzer: ik_smart }, content: { type: text, analyzer: ik_max_word, search_analyzer: ik_smart }, category: { type: keyword }, publishTime: { type: date, format: yyyy-MM-dd HH:mm:ss||epoch_millis } } } }这里有两个关键点。第一文本字段的analyzer和search_analyzer为什么要分开配。analyzer用于建立索引时的分词策略我选ik_max_word它会尽可能把句子切成最细粒度的词比如中华人民共和国会切出中华人民中华人民共和国中华华人共和等这样搜索时更容易被各种查询词命中。search_analyzer用于搜索时对查询词的分词我选ik_smart它做粗粒度切分更贴近用户意图避免查询词被切得太碎导致匹配结果发散。索引细、搜索粗这是很多线上搜索效果调优的基础配置。第二category这种用于精确筛选、排序和聚合的字段必须用keyword类型而不是text。text类型会被分词排序和聚合时是按分词后的结果来的几乎肯定不是你想要的。经典错误就是有人把分类字段配成text结果聚合出来的桶全是一个个单字。2.4 Java 实体映射与索引自动创建Spring Data Elasticsearch 里用Document和Field把 Java 对象和索引对应起来Document(indexName article_index) public class ArticleDoc { Id private Long id; Field(type FieldType.Text, analyzer ik_max_word, searchAnalyzer ik_smart) private String title; Field(type FieldType.Text, analyzer ik_max_word, searchAnalyzer ik_smart) private String content; Field(type FieldType.Keyword) private String category; Field(type FieldType.Date, format DateFormat.custom, pattern yyyy-MM-dd HH:mm:ss) private LocalDateTime publishTime; }注意Field的format写法如果直接用标准DateFormat枚举默认格式可能是yyyy-MM-ddTHH:mm:ss.SSSZ和你数据库里传过来的字符串对不上。我在项目里就用custompattern指定成业务自己的格式省去一堆时间转换问题。关于索引自动创建Spring Data 默认在启动时会根据实体类自动建索引但自动生成的 mapping 往往不够专业尤其是分词器不会自动配置成 IK。所以我比较推荐关闭自动创建在部署流程里用脚本或初始化代码先把 mapping 建好代码里只做读写。具体可以在配置里设置spring: elasticsearch: repositories: enabled: true然后启动类上配合EnableElasticsearchRepositories在初始化阶段用ElasticsearchOperations手动创建索引保证 mapping 完全可控。3. 高级查询实战从简单匹配到组合条件3.1 查询 DSL 的核心概念先别急着写代码ES 的查询 DSL 和 SQL 思维差异很大最反直觉的地方在于匹配和过滤是两种不同性质的语义。must、should这一类是参与相关度评分的结果会按_score排序filter只做条件筛选不参与评分但可以利用缓存性能好很多。我见过不少同学把时间范围、状态这种筛选条件放在must里结果每个请求都在重复计算无关紧要的分数白花性能。正确做法是跟关键词相关度有关的用must跟业务筛选有关的用filter。这也算是我对高级查询的第一个理解不是会写复杂查询就是高级而是知道哪些条件该放在哪里。Spring Data Elasticsearch 4.x 推荐用NativeQuery来构建查询。它跟早期RestHighLevelClient的写法不同但底层思想一致。3.2 组合查询BoolQuery 是你最常用的容器一个实际场景用户在前端输入SpringBoot 全文检索同时勾选了分类技术并且只需要 2023 年之后发布的文章。在 SpringBoot 代码里我可以这样构建import org.elasticsearch.index.query.BoolQueryBuilder; import org.elasticsearch.index.query.QueryBuilders; import org.springframework.data.elasticsearch.client.elc.NativeQuery; import org.springframework.data.elasticsearch.client.elc.NativeQueryBuilder; BoolQueryBuilder boolQuery QueryBuilders.boolQuery() .must(QueryBuilders.matchQuery(title, SpringBoot 全文检索)) .should(QueryBuilders.matchQuery(content, SpringBoot 全文检索)) .filter(QueryBuilders.termQuery(category, 技术)) .filter(QueryBuilders.rangeQuery(publishTime) .gte(2023-01-01 00:00:00) .lte(2024-12-31 23:59:59)); NativeQuery query new NativeQueryBuilder() .withQuery(boolQuery) .withPageable(PageRequest.of(0, 10)) .build(); SearchHitsArticleDoc hits operations.search(query, ArticleDoc.class);这里有一个容易忽略的细节matchQuery的检索词是分词后匹配的它适合全文搜索termQuery是不分词的精确匹配适合枚举字段。如果用matchQuery去查category它会去分词你的查询词查技术两个字可能会先切成技和术结果一个都命不中。类型和查询方法的不匹配是最常见的为什么我搜不到的原因。3.3 模糊查询与通配符fuzzy 和 wildcard 的使用边界用户搜索时手滑拼错一个字母是常事。比如商品名里有iphone用户输入ihponeES 的fuzzy查询能解决这个问题QueryBuilders.fuzzyQuery(title, ihpone) .fuzziness(Fuzziness.AUTO)Fuzziness.AUTO会根据匹配词长度自动决定允许的编辑距离短词不允许错太多长词容忍度大一些这种策略在实测中比固定编辑距离效果好。wildcard则适合做通配符匹配比如*Spring*Boot。但这里要警告一下wildcard的底层在必要时会把索引字段遍历一遍尤其当通配符是前缀时性能会急剧劣化。我线上就见过有人用wildcard实现模糊搜索数据量一上来直接把 ES 查挂。能用match加分词解决的问题就不要碰wildcard。如果确实需要通配符也要避免以*开头。3.4 评分调优boost 的正确用法默认情况下ES 会对所有匹配字段算分然后加权求和。但业务上通常标题命中的权重应该比正文高。ES 提供了boost参数在 Spring Data 里这样用QueryBuilders.boolQuery() .should(QueryBuilders.matchQuery(title, SpringBoot).boost(3.0f)) .should(QueryBuilders.matchQuery(content, SpringBoot).boost(1.0f))boost 的含义是字段权重倍率标题 3.0、正文 1.0意味着标题命中一次的影响力约等于正文命中三次。这个调优非常直接也是我推荐第一个做的搜索质量改进。稳一点的方案是把 boost 值放到配置中心运营同学自己做 A/B 验证不用每次改代码。还有一个隐藏细节should在bool查询里如果没有must或filter就必须至少满足一个should如果存在mustshould就变成了加分项。理解这个你在组合条件时就不会困惑为什么我没勾选 should 对应的条件也能搜到。4. 高亮、分页与聚合高频功能的正确姿势4.1 高亮显示让命中词一目了然搜索结果页把关键词标红是高亮功能的经典需求。ES 本身支持highlightSpring Data Elasticsearch 4.x 里推荐用编程方式构建而不是依赖实体注解因为注解方式在老版本中经常出现返回 null 的坑。代码示例HighlightField highlightField new HighlightField( title, title, ik_smart, 100, new String[]{em}, new String[]{/em} ); NativeQuery query new NativeQueryBuilder() .withQuery(boolQuery) .withHighlight(highlightField) .build(); SearchHitsArticleDoc hits operations.search(query, ArticleDoc.class); SearchHitArticleDoc hit hits.getSearchHit(0); ListString highlightTitle hit.getHighlightField(title);几个注意点。第一HighlightField构造函数里第一个参数是字段引用路径带前缀是 Spring Data 4.x 的写法不加会拿不到值。第二高亮分词器建议用ik_smart如果继续用ik_max_word高亮片段会把长词切到很碎前端标红后看起来一截一截的。第三设置100这个片段长度很重要不设置的话默认片段很短长正文可能只显示半句话观感很差。4.2 深分页问题与 Search After 实践ES 的from size分页有硬性窗口限制默认index.max_result_window是 10000。也就是说from size 10000时查询会直接报错Result window is too large。这不是 bug是设计因为超过这个窗口每次翻页都要在多个分片里取大量数据再排序内存开销极高。解决思路通常有三个第一业务层限制翻页深度。搜索产品的用户行为数据显示绝大多数用户只会看前几页。前端直接限制最大翻到第 100 页是最省事的方案。第二使用 Search After。它本质上是把跳到第 N 页变成从上一页最后一条记录的排序值继续往下取。实现要点是必须有一个全局唯一且值稳定的排序字段比如id或publishTime id组合。在 Spring Data 中Search After 需要比较底层一点的 API核心思路是先搜第一页取最后一条结果的SortValues第二次查询时传入SearchAfter searchAfter new SearchAfter(new Object[]{lastSortValue}); NativeQuery query new NativeQueryBuilder() .withQuery(boolQuery) .withPageable(PageRequest.of(0, 10)) .withSort(Sort.by(Sort.Order.asc(id))) .withSearchAfter(searchAfter) .build();第三Scroll API 适合做批量导出不适合用户交互因为它是基于快照的数据更新后还可能拿到旧数据。4.3 聚合统计搜索之外的隐藏价值ES 的聚合能力经常被 SpringBoot 开发者忽略其实它特别适合做搜索数据分析的组合需求。比如搜索全文检索关键词的文章时同时统计每个分类下的命中数量、按月统计发布趋势。这样一次搜索请求就能拿到结果集和统计信息。Spring Data 4.x 里聚合的写法TermsAggregation categoryAgg new TermsAggregation(categoryAgg, category) .setSize(20); NativeQuery query new NativeQueryBuilder() .withQuery(boolQuery) .withAggregation(categoryAgg) .build(); SearchHitsArticleDoc hits operations.search(query, ArticleDoc.class); AggregationContainer? container hits.getAggregations().get(categoryAgg);解析聚合结果在老版本的 API 里比较绕一个常见坑是字段类型不匹配如果 mapping 里category是text而不是keyword聚合时 ES 会拿分词后的结果分组你看到的就是技和术这种词。所以我在设计 mapping 时就强调所有需要聚合的枚举字段必须定义成keyword。聚合的size参数也要注意默认返回 10 个桶如果分类很多记得调大setSize。但别盲目调到上万桶数量越大内存消耗越高。5. 性能与稳定性生产环境必须掌握的几件事5.1 写入性能别一条条 insert全文检索系统上线后最容易被吐槽的就是数据同步慢。很多人初始化数据时用循环一条条写入 ES几十万条数据要跑几个小时但实际上 ES 的写入强项是 Bulk 批量写入。Spring Data 提供了BulkOperationsBulkOperations bulkOps operations.bulkOps(BulkOptions.builder().build(), ArticleDoc.class); for (ArticleDoc doc : docs) { bulkOps.add((doc)); } bulkOps.execute();批量提交的条数建议控制在 5000 到 10000 条之间或者按单批次体积控制在 5MB 到 15MB。过大的批次反而会增加 ES 端的压力也可能触发内存问题。这个值可以在压测后调优不用照抄。5.2 索引刷新与合并批量导入时的临时调优ES 的索引默认每秒刷新一次这个机制保证了近实时搜索但批量导入数据时每秒刷新会带来大量无意义的段合并开销。我导入历史数据时通常这样处理第一把refresh_interval临时设为-1即暂停自动刷新。第二写入完成后恢复为1s再执行一次_forcemerge合并段。这样批量导入整体耗时能降一半以上。这个操作要慎重线上正在提供搜索服务的索引不要随便停刷新否则你写入的数据用户搜不到。一般用于初始化数据或离线重建索引。5.3 慢查询与连接池定位性能问题的基本手段ES 本身的慢查询日志很有价值。可以在索引模板里配置{ index.search.slowlog.threshold.query.info: 500ms, index.search.slowlog.threshold.fetch.info: 500ms }这样超过 500ms 的查询会被记录在 ES 日志里方便定位到底是哪类 DSL 拖慢了服务。我排查线上问题时第一件事就是看 slowlog基本能锁定到具体的索引和查询模式。SpringBoot 侧也要关注连接池。默认的 HTTP 连接池参数在一些高并发场景下不够用如果服务端频繁报ConnectionPoolTimeoutException多半是连接池不够。可以在配置类里手动构造ElasticsearchClientBean public ElasticsearchClient elasticsearchClient() { RestClientBuilder builder RestClient.builder(new HttpHost(localhost, 9200, http)); builder.setRequestConfigCallback(config - config .setConnectTimeout(5000) .setSocketTimeout(30000)); builder.setHttpClientConfigCallback(client - client .setMaxConnTotal(200) .setMaxConnPerRoute(50)); RestClient restClient builder.build(); return new ElasticsearchClient(new JacksonJsonpMapper(), restClient); }这组参数要根据服务 QPS 调整单机访问时 50 的每路由上限足够高并发集群环境再往上加。6. 常见问题与排查技巧实录6.1 中文分词不生效搜中华人民共和国只能精确匹配这个问题的根源往往不是 IK 插件没装而是索引 mapping 没指定 analyzer。安装 IK 插件只是给 ES 提供了分词能力如果 mapping 里没有显式声明analyzer: ik_max_word默认还是 standard 分词器中文会被切成一个个单字。排查思路很简单先用_analyzeAPI 测试分词效果如果分词结果还是单字就检查 mapping。注意改了 mapping 后不会自动应用到已有索引必须重建索引。线上一般做法是创建带版本号的新索引比如article_index_v2用 alias 切换到新索引导流确认稳定后再删除旧索引。6.2 数据同步延迟数据库改了ES 里查不到这是几乎所有全文检索系统都会遇到的问题。我见过最原始的做法是写完数据库再同步写 ES但业务代码里到处都是双写逻辑一旦 ES 抖动主流程都会被拖住。比较稳的方案路径是这样业务落库后发一个 MQ 消息消费端异步更新 ES如果对实时性要求非常高用基于 binlog 的同步组件订阅数据库变更再投递到 ES。前者实现简单后者对业务无侵入。小团队我建议先从 MQ 异步开始因为 binlog 方案虽然听着高级但要额外维护订阅组件运维成本不低。6.3 版本升级后查询报错Spring Data 和 ES 版本对不上Spring Boot 从 2.x 升到 3.x 后Spring Data Elasticsearch 内部实现换了一套客户端很多旧代码报错是正常的。我遇到过最常见的报错包括NoSuchMethodError、ClassNotFoundException全都是版本不匹配的连锁反应。排查优先看依赖树mvn dependency:tree -Dincludesorg.springframework.data:spring-data-elasticsearch确认版本后再对照 ES 版本必要时用排除依赖锁定到指定版本。这种问题没有捷径版本矩阵一定要先确认。我的建议是如果项目稳定运行不要为了追新随便升 ES 大版本搜索引擎的版本升级往往意味着客户端代码大面积重改。6.4 字段值为空导致搜索不到ES 默认不索引null值也就是说一个字段为空时你搜空值永远搜不到。比如商品表里color字段为 null用户筛选颜色为空的产品ES 返回不出结果。解决方案是在 mapping 里配置null_value{ color: { type: keyword, null_value: UNKNOWN } }这里可以额外说一个经验同步数据前先梳理业务里哪些字段会出现空值统一设计 null 的落库策略别等上线后被运营投诉才补救。6.5 高亮字段拿不到值高亮字段在 Spring Data 4.x 里拿不到值十有八九是HighlightField的路径写法不对。注意看前面示例里第一个参数写了title这个是类型引用路径参考工程代码时很容易漏掉。其次要看查询里是否真的命中了该字段如果只在高亮某个没有被查询条件用到的字段ES 不会给它生成高亮片段。6.6 深分页性能差接口一直抖我曾经把搜索接口从from/size改为 Search After 后第 5000 页附近的请求延迟直接从 2 秒降到 200 毫秒以内。如果你遇到类似的性能问题先检查是不是有人把分页拉得太深。产品层限制页码数、代码层用 Search After 兜底是双保险。另外排序字段如果不稳定Search After 会翻页错乱。比如只按publishTime排序而同一秒内有多条记录时排序值不唯一下一页可能漏数据或者重复。解决办法是排序字段补一个唯一性id比如publishTime desc, id desc。最后再分享一个小技巧全文检索调试时别急着在 SpringBoot 代码里改来改去直接用 Kibana 的 Dev Tools 把 DSL 跑通确认分词、查询、高亮、聚合的结果都符合预期后再平移成 Java 代码。这个习惯帮我省了非常多来回编译重启的时间也让我对 ES 的查询行为有了更直观的感知。搜索性能调优和功能逻辑调试不是一回事前者更依赖观察数据、分析慢日志、验证分词效果的过程只有经常动手看真实数据反馈才能写出真正靠谱的检索服务。
阅读完成 · 觉得有帮助？
