尧图网页设计 
1. 本地环境搭建与版本选型先解决“装不装得上”再谈集成很多朋友上来就写代码写到一半发现版本不对、客户端报错回头又去折腾环境白白浪费一下午。我建议第一步先把ES本身搞清楚你本机到底装没装装的是什么版本SpringBoot那边要用哪个客户端版本。这些问题不先定下来后面全是坑。1.1 Windows下如何确认ES是否安装热搜词里有一条是“windows怎么看自己有没有安装es”问的人很多。其实方法很简单按顺序做一遍就行。第一先看服务。这里我以Windows系统为例按Win R打开运行窗口输入services.msc回车在服务列表里找Elasticsearch开头的服务。如果有并且状态是“正在运行”说明已经装了而且装的是Windows服务版本。第二直接敲端口。ES默认监听9200端口你可以在浏览器访问http://localhost:9200或者在命令行执行curl http://localhost:9200如果返回一串JSON里面带cluster_name、version这些字段那说明ES正在运行。比如类似这样的返回{ name : DESKTOP-ABC123, cluster_name : elasticsearch, cluster_uuid : xxxx, version : { number : 7.17.15, build_flavor : default, build_type : zip, build_hash : xxxx, build_date : 2023-04-05T19:55:28.446154Z, build_snapshot : false, lucene_version : 8.11.1 }, tagline : You Know, for Search }看到version.number你的ES版本就明确了这个信息对接下来的选型至关重要。第三如果端口没通再查一下进程。打开任务管理器在“详细信息”里找名字带java或elasticsearch的进程。因为ES本身就是Java写的进程里可能显示为java.exe。如果有但端口不通多半是配置或启动失败问题去看ES安装目录下logs/elasticsearch.log即可。1.2 版本搭配的原则SpringBoot和ES的版本兼容这是整个集成工程里最容易翻车的地方。SpringBoot的spring-boot-starter-data-elasticsearch会锁定一个ES客户端的版本而ES客户端和ES服务端的版本必须兼容否则请求发出去直接报UnsupportedPluginVersionException或各种协议错误。我自己一直沿用一个保守原则ES服务端版本 SpringBoot Data Elasticsearch 内置版本的次版本尽量选择小版本贴近的搭配。SpringBoot的版本和ES客户端之间的对应关系大致可以参照下表以常见组合为例SpringBoot版本官方默认的ES客户端版本推荐的ES服务端版本2.3.x7.6.x7.6 ~ 7.102.5.x7.12.x7.12 ~ 7.172.6.x7.15.x7.15 ~ 7.172.7.x7.17.x7.17推荐3.0.x8.08.x这里要特别提醒一个关键点ES官方的Java High Level REST ClientRestHighLevelClient在7.15版本已经被标记为废弃到8.0彻底移除。如果你用的SpringBoot版本内置到7.15以上的客户端建议直接用ElasticsearchClient新客户端或底层RestClient自己封装。从SpringBoot 3.0开始官方推荐的是ElasticsearchClientAPI风格跟旧版完全不一样网上很多旧教程代码直接粘过来是跑不起来的。提示如果你只是想快速做个Demo最稳的组合是 SpringBoot 2.7.x ES 7.17.x原因很简单SpringBoot 2.7的自动装配默认用的是 RestHighLevelClientES 7.17是7系最后一个版本兼容性面最广网上的资料也最多。除非项目明确要求上SpringBoot 3否则别一上来就追新。2. 依赖引入与自动装配选择官方starter还是原生客户端版本定好了接下来就进入代码层面的集成。这里有两个路线我分别说清楚免得大家纠结。2.1 官方Starter和原生RestClient怎么选SpringBoot官方提供了一个倒排索引开发包叫spring-boot-starter-data-elasticsearch。这个包给我们封装了ElasticsearchRestTemplate、ElasticsearchRepository这类现成的操作组件用起来很像JPA可以少写很多代码。另一种做法是只引入ES官方的客户端依赖自己在Spring容器里创建RestHighLevelClient或ElasticsearchClient的Bean然后写通用的连接工具类。这样做的好处是代码更透明不受SpringBoot数据封装层的限制可以完全控制底层API。我的经验是分场景选如果项目以ES为主需要大量复杂的查询、聚合、索引管理建议直接走原生客户端路线操作自由、踩坑少、可控性强。如果只是给已有系统加一个简单的全文检索功能实体结构清晰、增删改查为主用SpringBoot官方starter效率更高代码量少一大截。两种方式不冲突甚至可以同时存在。我见过不少项目是两个都引然后按场景选择用哪个这在工程上是可行的。2.2 Maven依赖的三种引入姿势第一种只引入官方starterdependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-data-elasticsearch/artifactId /dependency如果使用SpringBoot 2.7这个依赖会自动传递elasticsearch-rest-high-level-client。但由于SpringBoot2.7的管理版本是7.15或者7.17如果你需要更精确的版本可以显式指定dependency groupIdorg.elasticsearch.client/groupId artifactIdelasticsearch-rest-high-level-client/artifactId version7.17.15/version /dependency第二种只引入ES原生客户端不引入starterdependency groupIdorg.elasticsearch.client/groupId artifactIdelasticsearch-rest-high-level-client/artifactId version7.17.15/version /dependency第三种SpringBoot 3.x ES 8.x 的新方式dependency groupIdco.elastic.clients/groupId artifactIdelasticsearch-java/artifactId version8.11.0/version /dependency dependency groupIdcom.fasterxml.jackson.core/groupId artifactIdjackson-databind/artifactId /dependency这个新客户端需要Jackson参与JSON序列化依赖里要带上。连接时使用的是RestClientTransport这种更底层的传输方式。如果你是从高版本客户端倒退回低版本ES会遇到传输层协议不匹配所以版本搭配一定要按第一节的表格走。2.3 核心配置项与连接参数解读在SpringBoot的application.yml里需要配置ES地址。用官方starter时长这样spring: elasticsearch: uris: http://localhost:9200 username: elastic password: changeme connection-timeout: 3s read-timeout: 30s需要说明的是spring.elasticsearch.username和password是给7.x之后的版本用的如果ES开启了安全认证比如x-pack不加会连不上。自己本地随便装的单机ES一般没有开认证username和password可以不写。如果你走原生客户端路线可以通过Java配置类创建BeanConfiguration public class ElasticsearchConfig { Bean(destroyMethod close) public RestHighLevelClient restHighLevelClient() { RestClientBuilder builder RestClient.builder( new HttpHost(localhost, 9200, http) ); builder.setRequestConfigCallback( requestConfigBuilder - requestConfigBuilder .setConnectTimeout(3000) .setSocketTimeout(30000) ); return new RestHighLevelClient(builder); } }这里把destroyMethod设为close是必须的否则Spring容器关闭时不会释放HTTP连接池在微服务场景下会反复报Connection pool shut down。2.4 自动装配的黑盒逻辑理解starter到底替你做了什么用官方starter后很多人以为只要写个Autowired ElasticsearchRestTemplate就能用。但自动装配是有条件的比如SpringBoot 2.7中的逻辑是当classpath里存在RestHighLevelClient这个类时才自动装配ES连接找不到Bean时会直接报错。所以你会经常遇到一种情况明明加了starter依赖项目能启动但注入ElasticsearchClient时提示没有Bean。原因很简单starter给你装配的主要是ElasticsearchRestTemplate、ElasticsearchDataAutoConfiguration这些组件一些低版本的ES客户端类并不会自动注册。如果你用的是新客户端ElasticsearchClient需要手动定义BeanConfiguration public class EsClientConfig { Bean public ElasticsearchClient elasticsearchClient(RestClient restClient) { RestClientTransport transport new RestClientTransport(restClient, new JacksonJsonpMapper()); return new ElasticsearchClient(transport); } }这层知识如果不主动搞明白排错时会很迷茫。我的建议是每次引入新依赖都打开spring-configuration-metadata.json或者源码的自动装配文件看一眼不要黑盒使用。3. 基础读写API的实操落地索引、文档、查询与删除前面把环境、依赖、配置都梳理通了接下来进入实际编码环节。这一节我只讲高频的、直接在业务里用得上的能力不铺开讲ES所有API。3.1 索引设计与Mapping实践索引就相当于MySQL里的数据库表文档相当于行记录。真正执行增删改查之前得先把索引建好Mapping字段映射设好。在建索引时我建议直接使用代码来建不要每次都跑Kibana里手工去建。对SpringBoot工程来说可以在配置类里做启动时自动建索引Component public class EsIndexInitializer implements ApplicationRunner { Resource private RestHighLevelClient client; Override public void run(ApplicationArguments args) throws IOException { String indexName mall_product; if (!existsIndex(indexName)) { CreateIndexRequest request new CreateIndexRequest(indexName); request.settings(Settings.builder() .put(index.number_of_shards, 3) .put(index.number_of_replicas, 1) ); request.mapping( { properties: { productName: {type: text, analyzer: ik_max_word}, categoryId: {type: keyword}, price: {type: double}, publishTime: {type: date, format: yyyy-MM-dd HH:mm:ss} } } , XContentType.JSON); client.indices().create(request, RequestOptions.DEFAULT); } } private boolean existsIndex(String indexName) throws IOException { GetIndexRequest request new GetIndexRequest(indexName); return client.indices().exists(request, RequestOptions.DEFAULT); } }这里有两个经验点第一analyzer字段不是ES自带的默认只有standard、keyword、simple等标准分词器。上面示例中的ik_max_word需要提前安装IK分词插件否则建Mapping时直接报错。如果不需要中文分词用standard就行。第二number_of_shards创建后不可修改只能重建索引。前期不确定数据量的话先设置3个分片比较合适后期涨了可以用shrink或重建来解决。3.2 文档写入单条与批量写入文档最直接的方式是用IndexRequestIndexRequest request new IndexRequest(mall_product) .id(1001) .source(productJson, XContentType.JSON); IndexResponse response client.index(request, RequestOptions.DEFAULT);如果写入时文档数组非常大单条循环写入性能太差建议用Bulk批量BulkRequest bulkRequest new BulkRequest(); for (Product product : products) { bulkRequest.add(new IndexRequest(mall_product) .id(product.getId().toString()) .source(JSON.toJSONString(product), XContentType.JSON)); } BulkResponse response client.bulk(bulkRequest, RequestOptions.DEFAULT);批量写入的BulkRequest默认是全部命中的当中间有一条失败时默认不会中断后续请求所以记得检查response.hasFailures()和response.buildFailureMessage()。实际业务中批量失败后如果要精确重试失败项可以遍历BulkItemResponse根据isFailed()判断单独捞出失败的那几条再重试。3.3 查询SearchSourceBuilder是核心查询入口查询的核心对象是SearchRequestSearchSourceBuilder日常的term、match、range、bool查询基本都是往这个Builder上叠加。一个常见组合示例——商品名称模糊搜索加价格区间过滤SearchRequest searchRequest new SearchRequest(mall_product); SearchSourceBuilder sourceBuilder new SearchSourceBuilder(); BoolQueryBuilder boolQuery QueryBuilders.boolQuery(); boolQuery.must(QueryBuilders.matchQuery(productName, 手机)); boolQuery.filter(QueryBuilders.rangeQuery(price).gte(1000).lte(5000)); sourceBuilder.query(boolQuery); sourceBuilder.from(0); sourceBuilder.size(20); sourceBuilder.sort(publishTime, SortOrder.DESC); searchRequest.source(sourceBuilder); SearchResponse searchResponse client.search(searchRequest, RequestOptions.DEFAULT);然后解析返回结果。解析SearchHits的时候可以这样处理SearchHits hits searchResponse.getHits(); ListProduct productList new ArrayList(); for (SearchHit hit : hits) { productList.add(JSON.parseObject(hit.getSourceAsString(), Product.class)); }这里尤其注意ES里所有的文档都是JSON字符串必须自己处理Java对象到JSON的转换。我统一用的是 fastjson 或 Jackson无特殊偏好只要全工程保持一致就行。3.4 关于删除条数的一个隐蔽坑delete_by_query 和 精确删除 API热搜词里出现“es删除条数”这个点确实值得专门讲一下。ES里删除文档有两条路第一条路是精确删除单个文档用DeleteRequest返回DeleteResponse里面有getResult()和getShardInfo()可以看出删除是否成功。第二条路是按条件删除用DeleteByQueryRequestDeleteByQueryRequest request new DeleteByQueryRequest(mall_product); request.setQuery(QueryBuilders.termQuery(categoryId, 1001)); BulkByScrollResponse response client.deleteByQuery(request, RequestOptions.DEFAULT);这时候要注意BulkByScrollResponse.getDeleted()统计的是删除动作匹配的文档数但这个数字在ES内部是按分片并行统计的。如果你对索引做了replica副本并且使用某些版本的ESgetDeleted()可能出现“计数不等于实际删除行数”的现象。因为delete by query在执行时会先匹配再删除如果同一分片在ES内部有路由顺序问题极少数版本存在会存在重复匹配或者漏统计的情况。更隐蔽的坑是很多人用SearchRequest先查出待删除文档的数量再用deleteByQuery删除最后对不上一开始查出的数量。这里占大多数原因的是删除前有新的写入发生导致文档量变化或者数据里有相同的_id被不同索引版本覆盖。所以做数据清理时不要依赖返回的计数来判断是否清干净直接按_id一个get请求确认更直观。提示如果需要全量清空索引最快的方式是删除索引再重建比delete_by_query快非常多。API是DeleteIndexRequest但注意先备份数据删索引是物理级操作不可逆。4. 进阶操作routing路由、异步写入与性能调优这一块是ES集成里最能拉开水平的地方。如果只是跑通CRUD那跟操作MySQL没有本质区别。真正在实际生产环境里发现问题、解决问题的能力往往都体现在这节内容里。4.1 routing路由机制为什么它决定查询性能ES的每个文档在写入时会根据_id做一个哈希计算然后决定文档落在哪个分片shard上。公式大致是shard hash(_id) % number_of_primary_shards正常情况下一个查询会广播到所有分片去执行再把结果合并。当数据量大、分片多的时候这种广播开销不可忽视。routing的作用就是人为指定一个路由键让同一个路由值的数据都落到同一个分片上。比如用户A的所有订单都设置routing10001那么查询用户A的订单时只需要查询一个分片查询性能会大幅提升。写入代码里加routing很简单IndexRequest request new IndexRequest(order_index) .id(20240101001) .routing(10001) .source(orderJson, XContentType.JSON);查询时也要带上同样的routingSearchRequest searchRequest new SearchRequest(order_index); searchRequest.routing(10001);有个小细节必须清楚一旦某类文档写入时带routing查询时最好也带同样的routing否则会查不到数据因为文档所在的shard是固定的不带routing的查询是全分片广播理论上能查到但如果你用的是新客户端对某些请求类型有routing限制会查不到或报错。我的建议是从写入到查询routing的使用规则要在代码规范里写死避免后期人员变动导致规则混乱。routing带来的副作用是数据可能分布不均匀。比如热门用户的数据量极大会导致某些分片过热。这个问题在高并发场景下需要提前规划比如用user_id % 分片数这类hash算法做更均匀的路由而不是直接使用原始用户ID。4.2 异步写入高并发场景下的正确姿势热搜词“es异步写入java”其实包含两层含义一层是ES自身的异步API另一层是业务层的异步化写入方案。我这里把两者都讲一下。ES的AsyncAction风格API不常用生产环境用得更多的反而是业务侧异步 批量提交的思路。为了避免每次请求都同步等待ES返回常规做法是业务数据先入内存队列或线程池队列攒到一定数量或时间后批量写入ES。我分享一个自己常用的BulkProcessor方案。ES官方提供的BulkProcessor本身就是一个异步批处理工具配置好之后会自动攒批、自动刷盘不需要我们自己搞队列Configuration public class BulkProcessorConfig { Resource private RestHighLevelClient client; Bean(destroyMethod flush) public BulkProcessor bulkProcessor() { BulkProcessorListener listener new BulkProcessorListener() { Override public void beforeBulk(long executionId, BulkRequest request) { // 可在这里打印日志观察攒批情况 } Override public void afterBulk(long executionId, BulkRequest request, BulkResponse response) { if (response.hasFailures()) { log.error(批量写入ES出现失败: {}, response.buildFailureMessage()); } } Override public void afterBulk(long executionId, BulkRequest request, Throwable failure) { log.error(批量写入ES出现异常, failure); } }; return BulkProcessor.builder( (request, bulkListener) - client.bulkAsync(request, RequestOptions.DEFAULT, bulkListener), listener) .setBulkActions(1000) // 攒满1000条执行一次bulk .setBulkSize(new ByteSizeValue(5, ByteSizeUnit.MB)) // 或攒满5MB执行一次 .setFlushInterval(TimeValue.timeValueSeconds(5)) // 或者5秒强制刷一次 .setConcurrentRequests(2) // 并发请求数 .build(); } }这里有几个参数调优经验setBulkActions一般设1000到5000之间过小浪费网络IO过大内存占用高。setBulkSize控制在5MB到15MBES默认bulk最大值是100MB但日常推到10MB左右对集群压力比较友好。setConcurrentRequests表示异步并发请求数设太小会导致写入吞吐上不去设太大会压垮ES。单机Demo建议0或1生产环境结合ES集群配置逐步调整。destroyMethod flush很重要否则Spring容器关闭瞬间还有部分数据留在内存中没刷出去。依赖注入后怎么使用业务代码里不再一个个去client.index()而是bulkProcessor.add(new IndexRequest(mall_product) .id(product.getId().toString()) .source(jsonStr, XContentType.JSON));这样写数据直接扔进BulkProcessor剩下的攒批与刷盘逻辑全交给框架。单次请求远快于同步调用特别适合日志、订单事件这类高频写入场景。4.3 异步写入的更多细节这里再往后走一步。如果业务要求“写入后能立即查询到”使用BulkProcessor时要小心它内部有延迟默认满足批量条件才刷调用add()后马上查询可能会查不到。解决思路是对时效性要求极高的场景走同步API或者把setFlushInterval缩短、配合bulkProcessor.flush()手动刷一次。另外异步场景的异常处理很多人容易忽略。BulkProcessor在afterBulk回调里如果只是打印日志异常数据就直接丢了。我的做法是做一个失败重试队列把失败的请求包装成JSON放到本地Redis或MQ里后台任务消费重试。这个方案在业务数据量不大但偶尔抖动的情况下特别管用。不过要注意BulkProcessor的默认重试机制只发生在HTTP连接异常时业务错误比如Mapping字段类型不符不会重试。这类数据错误直接记录下来人工处理更快不要自动无限重试。5. 与MySQL数据同步几种方案如何选择ES在绝大多数业务系统里都不是数据源头真实数据存在MySQL里ES只是一个搜索层或者说查询加速层。所以“mysql如何与es同步”是每个集成ES的人都绕不开的问题。这里我按方案成熟度排序把主流做法讲一遍。5.1 双写方案最简单最可控但一致性最弱所谓双写就是业务代码在写完MySQL后再写一份到ESTransactional public void createProduct(Product product) { // 1.写入MySQL productMapper.insert(product); // 2.写入ES注意这里要在事务提交后再执行 esProductService.save(product); }这么写有几个问题要注意。第一MySQL事务和ES写入天然不在同一个事务里。MySQL写入成功了ES写入失败业务已经提交数据两边不一致。解决思路是先保证MySQL成功ES写入失败的话把待同步数据丢进MQ通过异步补偿机制重建。第二事务没有完全提交时直接发ES请求可能ES读到的是旧数据。写操作要放在MySQL事务提交之后执行。我喜欢用TransactionSynchronizationManager.registerSynchronization来注册事务提交后的回调TransactionSynchronizationManager.registerSynchronization(new TransactionSynchronization() { Override public void afterCommit() { esProductService.save(product); } });双写的优势是代码直观、延迟最低适合数据量不大、业务简单的系统。缺点是耦合度高、可靠性低一旦出现异常需要引入额外的补偿机制复杂度反而上去了。5.2 Canal方案监控Binlog异步同步Canal是阿里开源的一个MySQL Binlog解析工具。它的原理很简单伪装成MySQL的从库订阅Binlog日志然后把变更事件推送给消费者。SpringBoot项目可以订阅Canal推送的变更消息再写入ES。典型结构是MySQL - Binlog - Canal - MQ - SpringBoot消费 - ES这套方案最大的好处是对业务代码零侵入不需要在Service层写任何同步逻辑。既然能监听到MySQL的增删改那么无论哪天改一条数据都能通过Binlog感知到并同步到ES。它在团队中的落地成本主要体现在搭建Canal服务、做MQ消费链路、处理消息幂等这几个方面。此外Binlog日志里MySQL的时间字段是数据库服务器的时区消费时要注意时区转换否则会出现“同步到的数据时间跟原库差8小时”的情况。如果团队已经有MQ基础设施方案选Canal是长期最优解。5.3 定时任务兜底全量重建与增量对账不管采用双写还是CanalES和MySQL之间永远可能出现数据不一致的情况。比如ES写入失败的重试队列积压太多消息丢失Canal消费出错等等。所以成熟的方案一定需要一个定时对账任务做兜底。我的做法是做一个每天凌晨执行的定时任务从MySQL拉取全部业务主键ID和ES中的_id集合做差集找出缺少的文档补写。对存在但内容不同的文档覆盖更新。对ES中存在但MySQL已删除的文档执行删除。要考虑的边界是全量对账不能在高并发时段跑选凌晨低峰避免对ES和MySQL造成压力。对账任务要支持分批处理比如一次处理1000条。需要把对账任务做成可重入的定时框架里用分布式锁如Redisson的tryLock防止多实例同时跑。提示对账任务不影响在线业务但不能不做。有了这道兜底前面双写还是Canal的取舍就从容许多。我认为ES与MySQL同步这个问题的正解永远是“主链同步 定时对账”的组合单靠某一种方式都不够稳。6. 中文分词HanLP集成与实测心得关于中文检索ES原生对中文不太友好标准分词器会把中文按单个汉字或双字切分搜“苹果手机”的时候召回率惨不忍睹。集成HanLP分词的本质上分成两个层面装分词插件和配置索引分析器。6.1 安装HanLP分词插件HanLP官方提供了ES分词插件GitHub仓库名是hanlp-lucene-plugin。安装流程简单说就是根据ES版本下载对应release包的zip。把zip解压到ES目录下的plugins/analysis-hanlp文件夹。重启ES。确认插件列表里出现analysis-hanlp。验证插件是否生效直接调用ES的_analyze接口curl -X POST http://localhost:9200/_analyze?pretty -H Content-Type: application/json -d { analyzer: hanlp_standard, text: 上海自来水来自海上 }如果返回里能看到“上海”“自来水”“来自”“海上”这样的分词结果说明插件已经生效。6.2 SpringBoot侧如何配置HanLP在ES里创建索引时把字段的analyzer设置为HanLP的analyzer名称比如hanlp_standard或hanlp_index{ properties: { title: { type: text, analyzer: hanlp_standard, search_analyzer: hanlp_standard } } }SpringBoot侧的代码不需要额外处理因为ES已经完成分词Java代码只需要正常传入待搜索的文本就行。用matchQuery搜索时ES会自动对搜索词做同样的分词。这里有个需要提醒的坑如果索引已经创建并且Mapping是hanlp_standard指定好的而HanLP插件在索引创建后又被删掉ES会报analyzer [hanlp_standard] not found导致所有针对该索引的写入和查询全部失败。所以插件安装完成后不要轻易卸载升级前必须考虑存量索引的兼容性。6.3 HanLP与IK分词器的选择“hanlp分词在springboot”这个热搜词下肯定有人对比HanLP和IK。简单说说我的看法对比维度HanLPIK词库规模更大支持繁体、简繁转换通用词库够用但略少分词模式hanlp_standard适合细粒度搜索hanlp_index适合粗粒度索引ik_max_word适合索引阶段ik_smart适合搜索阶段扩展词配置插件目录下配置自定义词典文件IK配置IKAnalyzer.cfg.xml和ext.dic依赖需要安装插件包较新生态成熟资料多中文检索项目里我的个人经验是内容型系统、新闻资讯、商品描述搜索选HanLP更好准确率和召回率更高工具类系统、快速启动的DemoIK更省事。7. 集成过程中常见的坑与完整排查链路最后把项目集成ES时最常遇到的一类问题、排查思路和工作习惯系统梳理一下。这些东西比API本身更值钱因为它们直接决定你踩坑后能不能快速爬起来。7.1 “SpringBoot版本太高”带来的连锁问题热搜词里有一条“springboot版本太高”这个说法在ES集成场景太典型了。SpringBoot 3.x带来两个大变化一是基础Java版本必须升至17及以上二是javax命名空间整体迁移为jakarta。如果项目升级到SpringBoot 3但ES仍是7.x那么需要明确一点SpringBoot 3的spring-boot-starter-data-elasticsearch默认不再提供RestHighLevelClient的自动装配官方把支持聚焦到了新客户端ElasticsearchClient上。直接沿用旧代码会报ClassNotFoundException: RestHighLevelClient或者各种NoSuchBeanDefinitionException。这时三条路把ES服务端升级到8.x客户端也换成ElasticsearchClient走官方新API。手动引入elasticsearch-rest-high-level-client并将其声明为Bean版本锁定7.17.x。这种做法虽然能用但RestHighLevelClient已经停更属于过渡方案。保持SpringBoot 2.7不升级和ES 7.x完美搭配适合不想折腾的场景。我的建议是如果是新项目直接走方案1花点时间熟悉新客户端API长期受益。如果只是给存量系统加ES集成优先方案3。这类问题排查时的链路是这样先看启动日志里有没有NoClassDefFoundError缺哪个类就从哪个依赖入手。再看spring.factories和自动装配源码确认当前SpringBoot版本下定义了什么Bean。最后再决定是升降版本还是换API。7.2 连接超时、批量写入慢、内存溢出问题定位这一节列三个我实测中常遇到的问题及解决思路。问题一建立连接慢请求频繁超时职责通常不在ES本身而在HTTP连接的建立成本。解决方案是检查配置里的connection-timeout是否过小另外如果每次操作都新建RestHighLevelClient那必然慢必须把Client做成Spring容器管理的单例Bean这是最容易被新手忽略的点。问题二批量写入速度上不去先看BulkProcessor的setConcurrentRequests和批量大小是否合理。如果还慢检查ES集群的健康状态curl http://localhost:9200/_cluster/health如果出现yellow甚至red说明有分片未分配写入性能会大幅下降。单机环境出现yellow是正常的因为没有副本节点但如果是多节点集群yellow就要去看未分配分片的原因。问题三堆内存溢出ES的JVM堆默认根据jvm.options设置官方推荐不超过物理内存的50%。SpringBoot侧如果频繁往内存里塞大数据对象然后一次性提交也可能OOM。排查堆内存溢出思路是看GC日志、看dump文件分析大对象来源。常见原因往往是文档体过大或者查询fromsize设置过大一次拉取上万条数据。要避免使用深分页改用search_after机制。7.3 一个排查示例delete_by_query 后“数据还在”某次现场环境我执行了delete_by_query清掉一批过期文档返回deleted1000但再次查询时发现文档还能查到。排查链路是这样的第一步确认是否走了副本。由于ES单机环境只有一个节点副本数为1时该副本分片其实在同一个节点。此时候删除成功的数据不应该能查到。于是排除副本因素。第二步检查删除请求是否带routing。如果写入时带了routing删除时的delete_by_query也必须带routing。不带的话请求虽然返回成功但实际匹配范围不包含目标分片导致“删了个寂寞”。第三步验证结果。我用_id直接GET该文档发现在部分分片上确实还存在。这会排查出routing问题。这个例子给我们的教训很直接ES的API返回状态码正常不代表业务逻辑正确。任何“删除/更新没生效”的问题都要从 routing、分片、副本 三个维度去想。7.4 索引管理中的自动化与规范ES数据模型不像MySQL那样强制Schema但生产环境必须把索引设计当Schema管理。我的习惯是每个索引都有对应的版本号如mall_product_v1版本迭代时创建新索引验证无误后切换别名mall_product指向新索引。索引的Mapping和Settings全部存到项目仓库里的maps/或indices/目录下用版本管理工具管理不能只存在于某个人的本地Kibana里。对重要索引设置监控分片大小、段数、segment merge耗时、慢查询日志。这些指标在ES的_cat/indices和_nodes/stats接口里都能拿到半小时跑一次定期收集即可。8. 我个人在实际项目中的一点总结做了这么多ES与SpringBoot的集成项目最大的感悟是ES的本质是一个“独立的分布式组件”它和SpringBoot没有那么多“魔法联动”。SpringBoot只是帮你把客户端Bean管理起来真正干活的还是ES那套REST API和它的分布式机制。不要把精力全花在starter的封装API上花时间去理解分片、副本、routing、分词这些底层概念遇到问题时排查效率会高很多。如果觉得自己只装了一个ES、连几个接口就够了那只是个Demo不是集成。生产环境里的ES集成要考虑的永远是数据一致性怎么做、性能瓶颈在哪、异常数据怎么兜底。把这些想明白了项目才算真正稳定。最后分享一个小技巧ES的查询日志打开后会非常啰嗦但排错时很有用。在logstash.yml或代码日志级别里把org.elasticsearch.client.RestClient调到DEBUG可以看到每次请求的URI和方法。这比看业务日志直观得多尤其是排查routing、分页这类问题时一眼就能看出请求有没有带routing参数。我是建议在正式动手前先花半天时间把 [1.1] 到 [1.2 节] 的版本矩阵确认好再开始写代码。版本问题解决了这个集成项目至少能少踩一半的坑。 SpringBoot集成Elasticsearch：版本选型、数据同步与中文分词实战
1. 本地环境搭建与版本选型先解决“装不装得上”再谈集成很多朋友上来就写代码写到一半发现版本不对、客户端报错回头又去折腾环境白白浪费一下午。我建议第一步先把ES本身搞清楚你本机到底装没装装的是什么版本SpringBoot那边要用哪个客户端版本。这些问题不先定下来后面全是坑。1.1 Windows下如何确认ES是否安装热搜词里有一条是“windows怎么看自己有没有安装es”问的人很多。其实方法很简单按顺序做一遍就行。第一先看服务。这里我以Windows系统为例按Win R打开运行窗口输入services.msc回车在服务列表里找Elasticsearch开头的服务。如果有并且状态是“正在运行”说明已经装了而且装的是Windows服务版本。第二直接敲端口。ES默认监听9200端口你可以在浏览器访问http://localhost:9200或者在命令行执行curl http://localhost:9200如果返回一串JSON里面带cluster_name、version这些字段那说明ES正在运行。比如类似这样的返回{ name : DESKTOP-ABC123, cluster_name : elasticsearch, cluster_uuid : xxxx, version : { number : 7.17.15, build_flavor : default, build_type : zip, build_hash : xxxx, build_date : 2023-04-05T19:55:28.446154Z, build_snapshot : false, lucene_version : 8.11.1 }, tagline : You Know, for Search }看到version.number你的ES版本就明确了这个信息对接下来的选型至关重要。第三如果端口没通再查一下进程。打开任务管理器在“详细信息”里找名字带java或elasticsearch的进程。因为ES本身就是Java写的进程里可能显示为java.exe。如果有但端口不通多半是配置或启动失败问题去看ES安装目录下logs/elasticsearch.log即可。1.2 版本搭配的原则SpringBoot和ES的版本兼容这是整个集成工程里最容易翻车的地方。SpringBoot的spring-boot-starter-data-elasticsearch会锁定一个ES客户端的版本而ES客户端和ES服务端的版本必须兼容否则请求发出去直接报UnsupportedPluginVersionException或各种协议错误。我自己一直沿用一个保守原则ES服务端版本 SpringBoot Data Elasticsearch 内置版本的次版本尽量选择小版本贴近的搭配。SpringBoot的版本和ES客户端之间的对应关系大致可以参照下表以常见组合为例SpringBoot版本官方默认的ES客户端版本推荐的ES服务端版本2.3.x7.6.x7.6 ~ 7.102.5.x7.12.x7.12 ~ 7.172.6.x7.15.x7.15 ~ 7.172.7.x7.17.x7.17推荐3.0.x8.08.x这里要特别提醒一个关键点ES官方的Java High Level REST ClientRestHighLevelClient在7.15版本已经被标记为废弃到8.0彻底移除。如果你用的SpringBoot版本内置到7.15以上的客户端建议直接用ElasticsearchClient新客户端或底层RestClient自己封装。从SpringBoot 3.0开始官方推荐的是ElasticsearchClientAPI风格跟旧版完全不一样网上很多旧教程代码直接粘过来是跑不起来的。提示如果你只是想快速做个Demo最稳的组合是 SpringBoot 2.7.x ES 7.17.x原因很简单SpringBoot 2.7的自动装配默认用的是 RestHighLevelClientES 7.17是7系最后一个版本兼容性面最广网上的资料也最多。除非项目明确要求上SpringBoot 3否则别一上来就追新。2. 依赖引入与自动装配选择官方starter还是原生客户端版本定好了接下来就进入代码层面的集成。这里有两个路线我分别说清楚免得大家纠结。2.1 官方Starter和原生RestClient怎么选SpringBoot官方提供了一个倒排索引开发包叫spring-boot-starter-data-elasticsearch。这个包给我们封装了ElasticsearchRestTemplate、ElasticsearchRepository这类现成的操作组件用起来很像JPA可以少写很多代码。另一种做法是只引入ES官方的客户端依赖自己在Spring容器里创建RestHighLevelClient或ElasticsearchClient的Bean然后写通用的连接工具类。这样做的好处是代码更透明不受SpringBoot数据封装层的限制可以完全控制底层API。我的经验是分场景选如果项目以ES为主需要大量复杂的查询、聚合、索引管理建议直接走原生客户端路线操作自由、踩坑少、可控性强。如果只是给已有系统加一个简单的全文检索功能实体结构清晰、增删改查为主用SpringBoot官方starter效率更高代码量少一大截。两种方式不冲突甚至可以同时存在。我见过不少项目是两个都引然后按场景选择用哪个这在工程上是可行的。2.2 Maven依赖的三种引入姿势第一种只引入官方starterdependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-data-elasticsearch/artifactId /dependency如果使用SpringBoot 2.7这个依赖会自动传递elasticsearch-rest-high-level-client。但由于SpringBoot2.7的管理版本是7.15或者7.17如果你需要更精确的版本可以显式指定dependency groupIdorg.elasticsearch.client/groupId artifactIdelasticsearch-rest-high-level-client/artifactId version7.17.15/version /dependency第二种只引入ES原生客户端不引入starterdependency groupIdorg.elasticsearch.client/groupId artifactIdelasticsearch-rest-high-level-client/artifactId version7.17.15/version /dependency第三种SpringBoot 3.x ES 8.x 的新方式dependency groupIdco.elastic.clients/groupId artifactIdelasticsearch-java/artifactId version8.11.0/version /dependency dependency groupIdcom.fasterxml.jackson.core/groupId artifactIdjackson-databind/artifactId /dependency这个新客户端需要Jackson参与JSON序列化依赖里要带上。连接时使用的是RestClientTransport这种更底层的传输方式。如果你是从高版本客户端倒退回低版本ES会遇到传输层协议不匹配所以版本搭配一定要按第一节的表格走。2.3 核心配置项与连接参数解读在SpringBoot的application.yml里需要配置ES地址。用官方starter时长这样spring: elasticsearch: uris: http://localhost:9200 username: elastic password: changeme connection-timeout: 3s read-timeout: 30s需要说明的是spring.elasticsearch.username和password是给7.x之后的版本用的如果ES开启了安全认证比如x-pack不加会连不上。自己本地随便装的单机ES一般没有开认证username和password可以不写。如果你走原生客户端路线可以通过Java配置类创建BeanConfiguration public class ElasticsearchConfig { Bean(destroyMethod close) public RestHighLevelClient restHighLevelClient() { RestClientBuilder builder RestClient.builder( new HttpHost(localhost, 9200, http) ); builder.setRequestConfigCallback( requestConfigBuilder - requestConfigBuilder .setConnectTimeout(3000) .setSocketTimeout(30000) ); return new RestHighLevelClient(builder); } }这里把destroyMethod设为close是必须的否则Spring容器关闭时不会释放HTTP连接池在微服务场景下会反复报Connection pool shut down。2.4 自动装配的黑盒逻辑理解starter到底替你做了什么用官方starter后很多人以为只要写个Autowired ElasticsearchRestTemplate就能用。但自动装配是有条件的比如SpringBoot 2.7中的逻辑是当classpath里存在RestHighLevelClient这个类时才自动装配ES连接找不到Bean时会直接报错。所以你会经常遇到一种情况明明加了starter依赖项目能启动但注入ElasticsearchClient时提示没有Bean。原因很简单starter给你装配的主要是ElasticsearchRestTemplate、ElasticsearchDataAutoConfiguration这些组件一些低版本的ES客户端类并不会自动注册。如果你用的是新客户端ElasticsearchClient需要手动定义BeanConfiguration public class EsClientConfig { Bean public ElasticsearchClient elasticsearchClient(RestClient restClient) { RestClientTransport transport new RestClientTransport(restClient, new JacksonJsonpMapper()); return new ElasticsearchClient(transport); } }这层知识如果不主动搞明白排错时会很迷茫。我的建议是每次引入新依赖都打开spring-configuration-metadata.json或者源码的自动装配文件看一眼不要黑盒使用。3. 基础读写API的实操落地索引、文档、查询与删除前面把环境、依赖、配置都梳理通了接下来进入实际编码环节。这一节我只讲高频的、直接在业务里用得上的能力不铺开讲ES所有API。3.1 索引设计与Mapping实践索引就相当于MySQL里的数据库表文档相当于行记录。真正执行增删改查之前得先把索引建好Mapping字段映射设好。在建索引时我建议直接使用代码来建不要每次都跑Kibana里手工去建。对SpringBoot工程来说可以在配置类里做启动时自动建索引Component public class EsIndexInitializer implements ApplicationRunner { Resource private RestHighLevelClient client; Override public void run(ApplicationArguments args) throws IOException { String indexName mall_product; if (!existsIndex(indexName)) { CreateIndexRequest request new CreateIndexRequest(indexName); request.settings(Settings.builder() .put(index.number_of_shards, 3) .put(index.number_of_replicas, 1) ); request.mapping( { properties: { productName: {type: text, analyzer: ik_max_word}, categoryId: {type: keyword}, price: {type: double}, publishTime: {type: date, format: yyyy-MM-dd HH:mm:ss} } } , XContentType.JSON); client.indices().create(request, RequestOptions.DEFAULT); } } private boolean existsIndex(String indexName) throws IOException { GetIndexRequest request new GetIndexRequest(indexName); return client.indices().exists(request, RequestOptions.DEFAULT); } }这里有两个经验点第一analyzer字段不是ES自带的默认只有standard、keyword、simple等标准分词器。上面示例中的ik_max_word需要提前安装IK分词插件否则建Mapping时直接报错。如果不需要中文分词用standard就行。第二number_of_shards创建后不可修改只能重建索引。前期不确定数据量的话先设置3个分片比较合适后期涨了可以用shrink或重建来解决。3.2 文档写入单条与批量写入文档最直接的方式是用IndexRequestIndexRequest request new IndexRequest(mall_product) .id(1001) .source(productJson, XContentType.JSON); IndexResponse response client.index(request, RequestOptions.DEFAULT);如果写入时文档数组非常大单条循环写入性能太差建议用Bulk批量BulkRequest bulkRequest new BulkRequest(); for (Product product : products) { bulkRequest.add(new IndexRequest(mall_product) .id(product.getId().toString()) .source(JSON.toJSONString(product), XContentType.JSON)); } BulkResponse response client.bulk(bulkRequest, RequestOptions.DEFAULT);批量写入的BulkRequest默认是全部命中的当中间有一条失败时默认不会中断后续请求所以记得检查response.hasFailures()和response.buildFailureMessage()。实际业务中批量失败后如果要精确重试失败项可以遍历BulkItemResponse根据isFailed()判断单独捞出失败的那几条再重试。3.3 查询SearchSourceBuilder是核心查询入口查询的核心对象是SearchRequestSearchSourceBuilder日常的term、match、range、bool查询基本都是往这个Builder上叠加。一个常见组合示例——商品名称模糊搜索加价格区间过滤SearchRequest searchRequest new SearchRequest(mall_product); SearchSourceBuilder sourceBuilder new SearchSourceBuilder(); BoolQueryBuilder boolQuery QueryBuilders.boolQuery(); boolQuery.must(QueryBuilders.matchQuery(productName, 手机)); boolQuery.filter(QueryBuilders.rangeQuery(price).gte(1000).lte(5000)); sourceBuilder.query(boolQuery); sourceBuilder.from(0); sourceBuilder.size(20); sourceBuilder.sort(publishTime, SortOrder.DESC); searchRequest.source(sourceBuilder); SearchResponse searchResponse client.search(searchRequest, RequestOptions.DEFAULT);然后解析返回结果。解析SearchHits的时候可以这样处理SearchHits hits searchResponse.getHits(); ListProduct productList new ArrayList(); for (SearchHit hit : hits) { productList.add(JSON.parseObject(hit.getSourceAsString(), Product.class)); }这里尤其注意ES里所有的文档都是JSON字符串必须自己处理Java对象到JSON的转换。我统一用的是 fastjson 或 Jackson无特殊偏好只要全工程保持一致就行。3.4 关于删除条数的一个隐蔽坑delete_by_query 和 精确删除 API热搜词里出现“es删除条数”这个点确实值得专门讲一下。ES里删除文档有两条路第一条路是精确删除单个文档用DeleteRequest返回DeleteResponse里面有getResult()和getShardInfo()可以看出删除是否成功。第二条路是按条件删除用DeleteByQueryRequestDeleteByQueryRequest request new DeleteByQueryRequest(mall_product); request.setQuery(QueryBuilders.termQuery(categoryId, 1001)); BulkByScrollResponse response client.deleteByQuery(request, RequestOptions.DEFAULT);这时候要注意BulkByScrollResponse.getDeleted()统计的是删除动作匹配的文档数但这个数字在ES内部是按分片并行统计的。如果你对索引做了replica副本并且使用某些版本的ESgetDeleted()可能出现“计数不等于实际删除行数”的现象。因为delete by query在执行时会先匹配再删除如果同一分片在ES内部有路由顺序问题极少数版本存在会存在重复匹配或者漏统计的情况。更隐蔽的坑是很多人用SearchRequest先查出待删除文档的数量再用deleteByQuery删除最后对不上一开始查出的数量。这里占大多数原因的是删除前有新的写入发生导致文档量变化或者数据里有相同的_id被不同索引版本覆盖。所以做数据清理时不要依赖返回的计数来判断是否清干净直接按_id一个get请求确认更直观。提示如果需要全量清空索引最快的方式是删除索引再重建比delete_by_query快非常多。API是DeleteIndexRequest但注意先备份数据删索引是物理级操作不可逆。4. 进阶操作routing路由、异步写入与性能调优这一块是ES集成里最能拉开水平的地方。如果只是跑通CRUD那跟操作MySQL没有本质区别。真正在实际生产环境里发现问题、解决问题的能力往往都体现在这节内容里。4.1 routing路由机制为什么它决定查询性能ES的每个文档在写入时会根据_id做一个哈希计算然后决定文档落在哪个分片shard上。公式大致是shard hash(_id) % number_of_primary_shards正常情况下一个查询会广播到所有分片去执行再把结果合并。当数据量大、分片多的时候这种广播开销不可忽视。routing的作用就是人为指定一个路由键让同一个路由值的数据都落到同一个分片上。比如用户A的所有订单都设置routing10001那么查询用户A的订单时只需要查询一个分片查询性能会大幅提升。写入代码里加routing很简单IndexRequest request new IndexRequest(order_index) .id(20240101001) .routing(10001) .source(orderJson, XContentType.JSON);查询时也要带上同样的routingSearchRequest searchRequest new SearchRequest(order_index); searchRequest.routing(10001);有个小细节必须清楚一旦某类文档写入时带routing查询时最好也带同样的routing否则会查不到数据因为文档所在的shard是固定的不带routing的查询是全分片广播理论上能查到但如果你用的是新客户端对某些请求类型有routing限制会查不到或报错。我的建议是从写入到查询routing的使用规则要在代码规范里写死避免后期人员变动导致规则混乱。routing带来的副作用是数据可能分布不均匀。比如热门用户的数据量极大会导致某些分片过热。这个问题在高并发场景下需要提前规划比如用user_id % 分片数这类hash算法做更均匀的路由而不是直接使用原始用户ID。4.2 异步写入高并发场景下的正确姿势热搜词“es异步写入java”其实包含两层含义一层是ES自身的异步API另一层是业务层的异步化写入方案。我这里把两者都讲一下。ES的AsyncAction风格API不常用生产环境用得更多的反而是业务侧异步 批量提交的思路。为了避免每次请求都同步等待ES返回常规做法是业务数据先入内存队列或线程池队列攒到一定数量或时间后批量写入ES。我分享一个自己常用的BulkProcessor方案。ES官方提供的BulkProcessor本身就是一个异步批处理工具配置好之后会自动攒批、自动刷盘不需要我们自己搞队列Configuration public class BulkProcessorConfig { Resource private RestHighLevelClient client; Bean(destroyMethod flush) public BulkProcessor bulkProcessor() { BulkProcessorListener listener new BulkProcessorListener() { Override public void beforeBulk(long executionId, BulkRequest request) { // 可在这里打印日志观察攒批情况 } Override public void afterBulk(long executionId, BulkRequest request, BulkResponse response) { if (response.hasFailures()) { log.error(批量写入ES出现失败: {}, response.buildFailureMessage()); } } Override public void afterBulk(long executionId, BulkRequest request, Throwable failure) { log.error(批量写入ES出现异常, failure); } }; return BulkProcessor.builder( (request, bulkListener) - client.bulkAsync(request, RequestOptions.DEFAULT, bulkListener), listener) .setBulkActions(1000) // 攒满1000条执行一次bulk .setBulkSize(new ByteSizeValue(5, ByteSizeUnit.MB)) // 或攒满5MB执行一次 .setFlushInterval(TimeValue.timeValueSeconds(5)) // 或者5秒强制刷一次 .setConcurrentRequests(2) // 并发请求数 .build(); } }这里有几个参数调优经验setBulkActions一般设1000到5000之间过小浪费网络IO过大内存占用高。setBulkSize控制在5MB到15MBES默认bulk最大值是100MB但日常推到10MB左右对集群压力比较友好。setConcurrentRequests表示异步并发请求数设太小会导致写入吞吐上不去设太大会压垮ES。单机Demo建议0或1生产环境结合ES集群配置逐步调整。destroyMethod flush很重要否则Spring容器关闭瞬间还有部分数据留在内存中没刷出去。依赖注入后怎么使用业务代码里不再一个个去client.index()而是bulkProcessor.add(new IndexRequest(mall_product) .id(product.getId().toString()) .source(jsonStr, XContentType.JSON));这样写数据直接扔进BulkProcessor剩下的攒批与刷盘逻辑全交给框架。单次请求远快于同步调用特别适合日志、订单事件这类高频写入场景。4.3 异步写入的更多细节这里再往后走一步。如果业务要求“写入后能立即查询到”使用BulkProcessor时要小心它内部有延迟默认满足批量条件才刷调用add()后马上查询可能会查不到。解决思路是对时效性要求极高的场景走同步API或者把setFlushInterval缩短、配合bulkProcessor.flush()手动刷一次。另外异步场景的异常处理很多人容易忽略。BulkProcessor在afterBulk回调里如果只是打印日志异常数据就直接丢了。我的做法是做一个失败重试队列把失败的请求包装成JSON放到本地Redis或MQ里后台任务消费重试。这个方案在业务数据量不大但偶尔抖动的情况下特别管用。不过要注意BulkProcessor的默认重试机制只发生在HTTP连接异常时业务错误比如Mapping字段类型不符不会重试。这类数据错误直接记录下来人工处理更快不要自动无限重试。5. 与MySQL数据同步几种方案如何选择ES在绝大多数业务系统里都不是数据源头真实数据存在MySQL里ES只是一个搜索层或者说查询加速层。所以“mysql如何与es同步”是每个集成ES的人都绕不开的问题。这里我按方案成熟度排序把主流做法讲一遍。5.1 双写方案最简单最可控但一致性最弱所谓双写就是业务代码在写完MySQL后再写一份到ESTransactional public void createProduct(Product product) { // 1.写入MySQL productMapper.insert(product); // 2.写入ES注意这里要在事务提交后再执行 esProductService.save(product); }这么写有几个问题要注意。第一MySQL事务和ES写入天然不在同一个事务里。MySQL写入成功了ES写入失败业务已经提交数据两边不一致。解决思路是先保证MySQL成功ES写入失败的话把待同步数据丢进MQ通过异步补偿机制重建。第二事务没有完全提交时直接发ES请求可能ES读到的是旧数据。写操作要放在MySQL事务提交之后执行。我喜欢用TransactionSynchronizationManager.registerSynchronization来注册事务提交后的回调TransactionSynchronizationManager.registerSynchronization(new TransactionSynchronization() { Override public void afterCommit() { esProductService.save(product); } });双写的优势是代码直观、延迟最低适合数据量不大、业务简单的系统。缺点是耦合度高、可靠性低一旦出现异常需要引入额外的补偿机制复杂度反而上去了。5.2 Canal方案监控Binlog异步同步Canal是阿里开源的一个MySQL Binlog解析工具。它的原理很简单伪装成MySQL的从库订阅Binlog日志然后把变更事件推送给消费者。SpringBoot项目可以订阅Canal推送的变更消息再写入ES。典型结构是MySQL - Binlog - Canal - MQ - SpringBoot消费 - ES这套方案最大的好处是对业务代码零侵入不需要在Service层写任何同步逻辑。既然能监听到MySQL的增删改那么无论哪天改一条数据都能通过Binlog感知到并同步到ES。它在团队中的落地成本主要体现在搭建Canal服务、做MQ消费链路、处理消息幂等这几个方面。此外Binlog日志里MySQL的时间字段是数据库服务器的时区消费时要注意时区转换否则会出现“同步到的数据时间跟原库差8小时”的情况。如果团队已经有MQ基础设施方案选Canal是长期最优解。5.3 定时任务兜底全量重建与增量对账不管采用双写还是CanalES和MySQL之间永远可能出现数据不一致的情况。比如ES写入失败的重试队列积压太多消息丢失Canal消费出错等等。所以成熟的方案一定需要一个定时对账任务做兜底。我的做法是做一个每天凌晨执行的定时任务从MySQL拉取全部业务主键ID和ES中的_id集合做差集找出缺少的文档补写。对存在但内容不同的文档覆盖更新。对ES中存在但MySQL已删除的文档执行删除。要考虑的边界是全量对账不能在高并发时段跑选凌晨低峰避免对ES和MySQL造成压力。对账任务要支持分批处理比如一次处理1000条。需要把对账任务做成可重入的定时框架里用分布式锁如Redisson的tryLock防止多实例同时跑。提示对账任务不影响在线业务但不能不做。有了这道兜底前面双写还是Canal的取舍就从容许多。我认为ES与MySQL同步这个问题的正解永远是“主链同步 定时对账”的组合单靠某一种方式都不够稳。6. 中文分词HanLP集成与实测心得关于中文检索ES原生对中文不太友好标准分词器会把中文按单个汉字或双字切分搜“苹果手机”的时候召回率惨不忍睹。集成HanLP分词的本质上分成两个层面装分词插件和配置索引分析器。6.1 安装HanLP分词插件HanLP官方提供了ES分词插件GitHub仓库名是hanlp-lucene-plugin。安装流程简单说就是根据ES版本下载对应release包的zip。把zip解压到ES目录下的plugins/analysis-hanlp文件夹。重启ES。确认插件列表里出现analysis-hanlp。验证插件是否生效直接调用ES的_analyze接口curl -X POST http://localhost:9200/_analyze?pretty -H Content-Type: application/json -d { analyzer: hanlp_standard, text: 上海自来水来自海上 }如果返回里能看到“上海”“自来水”“来自”“海上”这样的分词结果说明插件已经生效。6.2 SpringBoot侧如何配置HanLP在ES里创建索引时把字段的analyzer设置为HanLP的analyzer名称比如hanlp_standard或hanlp_index{ properties: { title: { type: text, analyzer: hanlp_standard, search_analyzer: hanlp_standard } } }SpringBoot侧的代码不需要额外处理因为ES已经完成分词Java代码只需要正常传入待搜索的文本就行。用matchQuery搜索时ES会自动对搜索词做同样的分词。这里有个需要提醒的坑如果索引已经创建并且Mapping是hanlp_standard指定好的而HanLP插件在索引创建后又被删掉ES会报analyzer [hanlp_standard] not found导致所有针对该索引的写入和查询全部失败。所以插件安装完成后不要轻易卸载升级前必须考虑存量索引的兼容性。6.3 HanLP与IK分词器的选择“hanlp分词在springboot”这个热搜词下肯定有人对比HanLP和IK。简单说说我的看法对比维度HanLPIK词库规模更大支持繁体、简繁转换通用词库够用但略少分词模式hanlp_standard适合细粒度搜索hanlp_index适合粗粒度索引ik_max_word适合索引阶段ik_smart适合搜索阶段扩展词配置插件目录下配置自定义词典文件IK配置IKAnalyzer.cfg.xml和ext.dic依赖需要安装插件包较新生态成熟资料多中文检索项目里我的个人经验是内容型系统、新闻资讯、商品描述搜索选HanLP更好准确率和召回率更高工具类系统、快速启动的DemoIK更省事。7. 集成过程中常见的坑与完整排查链路最后把项目集成ES时最常遇到的一类问题、排查思路和工作习惯系统梳理一下。这些东西比API本身更值钱因为它们直接决定你踩坑后能不能快速爬起来。7.1 “SpringBoot版本太高”带来的连锁问题热搜词里有一条“springboot版本太高”这个说法在ES集成场景太典型了。SpringBoot 3.x带来两个大变化一是基础Java版本必须升至17及以上二是javax命名空间整体迁移为jakarta。如果项目升级到SpringBoot 3但ES仍是7.x那么需要明确一点SpringBoot 3的spring-boot-starter-data-elasticsearch默认不再提供RestHighLevelClient的自动装配官方把支持聚焦到了新客户端ElasticsearchClient上。直接沿用旧代码会报ClassNotFoundException: RestHighLevelClient或者各种NoSuchBeanDefinitionException。这时三条路把ES服务端升级到8.x客户端也换成ElasticsearchClient走官方新API。手动引入elasticsearch-rest-high-level-client并将其声明为Bean版本锁定7.17.x。这种做法虽然能用但RestHighLevelClient已经停更属于过渡方案。保持SpringBoot 2.7不升级和ES 7.x完美搭配适合不想折腾的场景。我的建议是如果是新项目直接走方案1花点时间熟悉新客户端API长期受益。如果只是给存量系统加ES集成优先方案3。这类问题排查时的链路是这样先看启动日志里有没有NoClassDefFoundError缺哪个类就从哪个依赖入手。再看spring.factories和自动装配源码确认当前SpringBoot版本下定义了什么Bean。最后再决定是升降版本还是换API。7.2 连接超时、批量写入慢、内存溢出问题定位这一节列三个我实测中常遇到的问题及解决思路。问题一建立连接慢请求频繁超时职责通常不在ES本身而在HTTP连接的建立成本。解决方案是检查配置里的connection-timeout是否过小另外如果每次操作都新建RestHighLevelClient那必然慢必须把Client做成Spring容器管理的单例Bean这是最容易被新手忽略的点。问题二批量写入速度上不去先看BulkProcessor的setConcurrentRequests和批量大小是否合理。如果还慢检查ES集群的健康状态curl http://localhost:9200/_cluster/health如果出现yellow甚至red说明有分片未分配写入性能会大幅下降。单机环境出现yellow是正常的因为没有副本节点但如果是多节点集群yellow就要去看未分配分片的原因。问题三堆内存溢出ES的JVM堆默认根据jvm.options设置官方推荐不超过物理内存的50%。SpringBoot侧如果频繁往内存里塞大数据对象然后一次性提交也可能OOM。排查堆内存溢出思路是看GC日志、看dump文件分析大对象来源。常见原因往往是文档体过大或者查询fromsize设置过大一次拉取上万条数据。要避免使用深分页改用search_after机制。7.3 一个排查示例delete_by_query 后“数据还在”某次现场环境我执行了delete_by_query清掉一批过期文档返回deleted1000但再次查询时发现文档还能查到。排查链路是这样的第一步确认是否走了副本。由于ES单机环境只有一个节点副本数为1时该副本分片其实在同一个节点。此时候删除成功的数据不应该能查到。于是排除副本因素。第二步检查删除请求是否带routing。如果写入时带了routing删除时的delete_by_query也必须带routing。不带的话请求虽然返回成功但实际匹配范围不包含目标分片导致“删了个寂寞”。第三步验证结果。我用_id直接GET该文档发现在部分分片上确实还存在。这会排查出routing问题。这个例子给我们的教训很直接ES的API返回状态码正常不代表业务逻辑正确。任何“删除/更新没生效”的问题都要从 routing、分片、副本 三个维度去想。7.4 索引管理中的自动化与规范ES数据模型不像MySQL那样强制Schema但生产环境必须把索引设计当Schema管理。我的习惯是每个索引都有对应的版本号如mall_product_v1版本迭代时创建新索引验证无误后切换别名mall_product指向新索引。索引的Mapping和Settings全部存到项目仓库里的maps/或indices/目录下用版本管理工具管理不能只存在于某个人的本地Kibana里。对重要索引设置监控分片大小、段数、segment merge耗时、慢查询日志。这些指标在ES的_cat/indices和_nodes/stats接口里都能拿到半小时跑一次定期收集即可。8. 我个人在实际项目中的一点总结做了这么多ES与SpringBoot的集成项目最大的感悟是ES的本质是一个“独立的分布式组件”它和SpringBoot没有那么多“魔法联动”。SpringBoot只是帮你把客户端Bean管理起来真正干活的还是ES那套REST API和它的分布式机制。不要把精力全花在starter的封装API上花时间去理解分片、副本、routing、分词这些底层概念遇到问题时排查效率会高很多。如果觉得自己只装了一个ES、连几个接口就够了那只是个Demo不是集成。生产环境里的ES集成要考虑的永远是数据一致性怎么做、性能瓶颈在哪、异常数据怎么兜底。把这些想明白了项目才算真正稳定。最后分享一个小技巧ES的查询日志打开后会非常啰嗦但排错时很有用。在logstash.yml或代码日志级别里把org.elasticsearch.client.RestClient调到DEBUG可以看到每次请求的URI和方法。这比看业务日志直观得多尤其是排查routing、分页这类问题时一眼就能看出请求有没有带routing参数。我是建议在正式动手前先花半天时间把 [1.1] 到 [1.2 节] 的版本矩阵确认好再开始写代码。版本问题解决了这个集成项目至少能少踩一半的坑。