1. 项目概述与前期准备断断续续把 SpringBoot 整合 Elasticsearch 8.0 的新版 Java API Client 用了一遍发现网上铺天盖地还在讲旧版的 RestHighLevelClient或者各种包装过的 Spring Data Elasticsearch。确实老客户端已经进入维护期官方主推的就是 Java API Client for Elasticsearch。这一篇专门讲文档操作也就是最常用的增删改查、批量写入、条件查询这些基于我自己在一个实际项目里的完整落地记录来写直接能拿过去用。1.1 核心需求解析这个项目的场景很典型某团队内部的知识库系统需要把文档内容、标签、作者、创建时间这些信息同步到 Elasticsearch 里做全文检索和聚合分析。数据量不算大但要求响应快而且要支持按关键词搜正文、按标签过滤、按时间范围统计这类操作所以数据库里的内容得实时同步到 ES。技术选型上既然已经确定用 SpringBoot 2.7 做基础框架ES 服务端是 8.0 版本那客户端就必须用最新的 Java API Client原因很简单RestHighLevelClient 在 ES 8.x 里已经不再推荐新版 API 在连接管理、类型安全、响应式调用上都更干净。整个项目拆成四块来做第一块是依赖引入和配置类第二块是索引创建和映射定义第三块是文档的单条操作和批量操作第四块是查询与聚合。这篇重点关注第三块但前面两块是基础会一并把关键代码和踩坑点说清楚。1.2 工具选型与核心依赖先看 Maven 依赖。新版 Java API Client 的坐标是co.elastic.clients:elasticsearch-java版本号要和服务端对应。ES 8.0 对应 8.x 的客户端我用的 8.5.1。这里有个容易忽略的点新版客户端底层走的是 Elasticsearch TransportClient 重构后的 REST 协议但它依赖一个独立的 JSON 解析库默认是 Jackson所以还需要引入jackson-databind和jackson-datatype-jsr310来处理 LocalDateTime 这类 Java 时间类型。dependency groupIdco.elastic.clients/groupId artifactIdelasticsearch-java/artifactId version8.5.1/version /dependency dependency groupIdcom.fasterxml.jackson.core/groupId artifactIdjackson-databind/artifactId version2.13.4/version /dependency dependency groupIdcom.fasterxml.jackson.datatype/groupId artifactIdjackson-datatype-jsr310/artifactId version2.13.4/version /dependency如果用的是 SpringBoot 2.7Spring 本身自带了一个 Jackson 版本直接引可能版本冲突。我当时的处理办法是把上面两个 Jackson 依赖的版本去掉让 SpringBoot 的 BOM 统一管理只保留elasticsearch-java单独指定版本。elasticsearch-java内部会传递依赖elasticsearch-rest-client这个是底层 HTTP 通信的组件不需要单独引。提示不要用spring-boot-starter-data-elasticsearch的自动配置来管理 ES 客户端版本它的版本管理策略和新版 Java API Client 不是一套体系混用容易出兼容性问题。建议全部手动建 Bean不走 SpringBoot 的自动配置。2. 建立客户端连接的细节拆解2.1 新版 API 的编程模型ES 8.0 的 Java API Client 和旧版最大区别是全面拥抱 builder 模式几乎每个请求对象都要通过XxxRequest.Builder来构造然后用client.xxx(request)方式调用。刚开始写会觉得很啰嗦比如查询一个文档要先new GetRequest.Builder().index(...).id(...).build()但是好处是每个参数在 IDE 里都有提示不容易写错而且请求和响应都是强类型的编译期就能发现大部分问题。连接配置上核心是RestClient和ElasticsearchClient两层。RestClient负责底层的 HTTP 连接管理ElasticsearchClient在它之上做请求封装和结果解析。实际使用中我建议把ElasticsearchClient注册成一个 Spring 单例 Bean避免每次调用都创建客户端连接复用和线程安全都由框架帮你处理。2.2 连接池与超时参数的取舍下面是我项目里用的配置类参数是跑了一段时间后调出来的结果。Configuration public class ElasticsearchConfig { Bean(destroyMethod close) public ElasticsearchClient elasticsearchClient() { RestClientBuilder builder RestClient.builder( new HttpHost(127.0.0.1, 9200, http) ); builder.setRequestConfigCallback(requestConfigBuilder - requestConfigBuilder .setConnectTimeout(5000) .setSocketTimeout(60000) .setConnectionRequestTimeout(5000) ); builder.setHttpClientConfigCallback(httpClientBuilder - { httpClientBuilder.setMaxConnTotal(100); httpClientBuilder.setMaxConnPerRoute(20); return httpClientBuilder; }); RestClient restClient builder.build(); JacksonJsonpMapper mapper new JacksonJsonpMapper(); return new ElasticsearchClient(restClient, mapper); } }setConnectTimeout(5000)是建立 TCP 连接的等待时间这个值设太大容易在 ES 集群故障时让请求线程全部挂住设太小又可能因为网络抖动频繁报连接超时。setSocketTimeout(60000)比较关键ES 的聚合查询和数据量大的批量写入可能超过 10 秒如果沿用默认的 30 秒很容易踩到SocketTimeoutException。setMaxConnTotal(100)和setMaxConnPerRoute(20)的意思是总连接数最多 100 条单个 ES 节点最多 20 条这个要结合项目并发量来定如果 QPS 高连接数太小会造成请求排队等待我在压测环境里出现过因为连接池打满导致大量ConnectionPoolTimeoutException的情况。JacksonJsonpMapper这一行特别值得说。ES 8 的 Java API Client 把 JSON 序列化做成可插拔设计默认可以是 Jackson、JSON-B 或者自带的轻量实现。用 Jackson 的好处是能和我们 Spring 项目里的 ObjectMapper 保持风格一致但要注意日期格式的处理。Elasticsearch 对日期类型默认用yyyy-MM-ddTHH:mm:ssZ格式存储Jackson 默认序列化 LocalDateTime 是一串数组比如[2023,5,10,14,30,0]ES 解析不了。解决办法是给 mapper 注册 JavaTimeModule 并设置写入日期为 ISO 格式。ObjectMapper objectMapper new ObjectMapper(); objectMapper.registerModule(new JavaTimeModule()); objectMapper.disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS); JacksonJsonpMapper mapper new JacksonJsonpMapper(objectMapper);这块不改的话你往索引里写带时间字段的文档时大概率会遇到failed to parse field [createTime] of type [date]的报错非常坑。3. 索引创建与映射定义3.1 为什么文档操作前要先做映射Elasticsearch 的索引相当于数据库里的表文档相当于一行记录。但表和表有个重要区别索引在写入第一个文档前如果不显式定义映射ES 会自动为每个字段推断类型。比如第一次写入的tags字段是字符串数组ES 就把tags映射成text类型后面如果又写入一个中文标题titleES 会默认给它生成title的text类型和title.keyword子字段。自动映射看起来省事但对生产环境是隐患。最典型的问题是中文分词默认 mapping 对text类型不会做中文分词查询分布式三个字匹配不到内容是常有的事。所以我建议在文档操作前先把索引的 mapping 和 settings 定义好尤其是analysis分词器配置以及哪些字段需要精确匹配、哪些字段需要聚合统计。3.2 定义索引与分词器的完整代码当时项目文档索引要求标题用 IK 分词器标签不做分词只做精确匹配创建时间用 date 类型。代码如下public void createIndex(String indexName) throws IOException { String settingsJson { settings: { number_of_shards: 3, number_of_replicas: 1, analysis: { filter: { ik_smart_pinyin: { type: pinyin, keep_first_letter: true, keep_separate_first_letter: false, keep_full_pinyin: true, keep_joined_full_pinyin: true, lowercase: true } }, analyzer: { ik_pinyin_analyzer: { type: custom, tokenizer: ik_max_word, filter: [ik_smart_pinyin] } } } }, mappings: { properties: { id: { type: keyword }, title: { type: text, analyzer: ik_max_word, search_analyzer: ik_smart, fields: { keyword: { type: keyword, ignore_above: 256 } } }, content: { type: text, analyzer: ik_max_word, search_analyzer: ik_smart }, author: { type: keyword }, tags: { type: keyword }, createTime: { type: date, format: yyyy-MM-dd HH:mm:ss }, viewCount: { type: integer } } } } ; CreateIndexRequest request CreateIndexRequest.of(r - r.index(indexName).withJson(new StringReader(settingsJson))); boolean exists client.indices().exists(e - e.index(indexName)).value(); if (!exists) { client.indices().create(request); } }number_of_shards设 3 是因为单节点上 3 个分片能发挥多线程并行检索的优势但如果机器性能一般也可以设 1分片太多反而增加协调开销。number_of_replicas至少 1如果集群只有一个节点副本会处于未分配状态这时可以临时改成 0或者等后续加节点后再调回来否则集群健康状态是 yellow不影响读写但不建议长期这样。title字段这里特别设计了keyword子字段。因为在前端列表页经常要按照标题精确过滤或者做排序text类型本身无法排序只能通过子字段title.keyword来实现。ignore_above: 256表示超过 256 字符的字符串不会写入 keyword 子字段防止超长标题撑爆内存。创建索引的时机我放在应用启动后的一个初始化方法里判断索引不存在才创建重启不会重复报错。索引一旦创建mapping 基本不能改后面要加字段只能通过_mappingAPI 增量追加所以前期想清楚字段设计能省不少事。4. 单文档增删改查的实操详解4.1 用 Index 和 Create 写入文档的区别写入单条文档有两条路径IndexRequest和CreateRequest。前者是存在则覆盖不存在则新增的 upsert 语义后者是如果文档已存在就报版本冲突的只新增语义。我项目里知识库文档的 ID 由业务系统生成需要保证同一篇文档多次同步不会产生重复数据所以用IndexRequest更合适但要实现仅首次导入不允许覆盖历史记录的场景就用CreateRequest。public void indexDocument(DocEntity doc) throws IOException { IndexRequestDocEntity request IndexRequest.of(r - r .index(docs) .id(doc.getId()) .document(doc) ); IndexResponse response client.index(request); log.info(索引文档结果, id{}, result{}, response.id(), response.result()); }document()方法接收一个对象框架内部通过 JsonpMapper 把它序列化成 JSON。这也是新版客户端比旧版舒服的地方——不需要手动构造XContentBuilder直接丢一个 Java 对象进去就行。实体类定义如下public class DocEntity { private String id; private String title; private String content; private String author; private ListString tags; private LocalDateTime createTime; private Integer viewCount; // getter/setter 省略 }字段名序列化出来和 Java 属性名保持一致createTime会被格式化成yyyy-MM-dd HH:mm:ss字符串。4.2 查询、更新和删除文档的完整链路按 ID 查询文档是高频操作代码很简单public DocEntity getDocById(String id) throws IOException { GetResponseDocEntity response client.get(g - g.index(docs).id(id), DocEntity.class); if (response.found()) { return response.source(); } return null; }注意found()方法有两个用途判断文档是否存在之外还能避免响应里 source 为空时强转 NPE。ES 允许你查询一个不存在的 ID响应 HTTP 状态是 404但客户端在found()返回 false 的情况下不会抛异常所以要自己判断。更新文档有全量替换和局部更新两种。局部更新的底层走_updateAPI不会重传整个文档适合只改一个字段的场景public void updateDoc(String id, String newContent) throws IOException { DocEntity doc new DocEntity(); doc.setContent(newContent); UpdateRequestDocEntity, DocEntity request UpdateRequest.of(u - u .index(docs) .id(id) .doc(doc) ); UpdateResponse response client.update(request, DocEntity.class); log.info(更新文档结果, result{}, response.result()); }这里有个难点UpdateRequest.of方法有两个泛型参数前面是文档类型后面是部分更新数据类型。如果只传doc一个对象两个泛型参数可以都用DocEntity。更新的字段会做 merge没传的字段原样保留。删除文档用DeleteRequest同理不再赘述。但有一个实际项目很容易踩的坑用update方法更新时ES 要求传入的部分更新文档里不能包含值为 null 的字段如果实体类里有 null 属性Jackson 序列化的时候会写出field:nullES 会把该字段也更新为 null。解决办法是给需要忽略 null 的字段加JsonInclude(Include.NON_NULL)注解或者更新时构造一个只包含目标字段的 Map 传进去。我踩过这个坑有一次更新文档时新建的 DocEntity 里没给 tags 赋值结果 tags 为 null 直接把原来的标签清空了。后来把所有更新场景统一改成用 Map 或单独构造 partial 实体只放要改的字段这个问题才彻底解决。4.3 利用版本号做乐观锁并发控制ES 文档有内部的_seq_no和_primary_term两个字段合在一起相当于版本号。多线程同时更新同一文档时可以用IfSeqNo和IfPrimaryTerm做乐观锁类似数据库的乐观锁机制。public void updateWithVersion(String id, String newTitle, long seqNo, long primaryTerm) throws IOException { UpdateRequestDocEntity, DocEntity request UpdateRequest.of(u - u .index(docs) .id(id) .ifSeqNo(seqNo) .ifPrimaryTerm(primaryTerm) .doc(Map.of(title, newTitle)) ); try { client.update(request, DocEntity.class); } catch (ElasticsearchException e) { if (e.status() 409) { log.warn(版本冲突文档已被他人修改id{}, id); } } }实际使用时先把查询出的_seq_no和_primary_term带在业务对象里提交更新时传给服务端。如果这期间文档被别人改过ES 返回 409 Conflict客户端捕获后可以根据业务决定重试还是提示冲突。这个方法在旧版 RestHighLevelClient 里命名不同新版 API 中直接叫ifSeqNo和ifPrimaryTerm搞混了会编译不过。5. 批量文档操作的性能之门5.1 Bulk 批量写入的正确打开方式同步文档进 ES如果一篇一篇地写 IndexRequest网络往返开销非常大。项目里第一批要导入 5 万条历史数据单条写入耗时差不多在 20 分钟以上换成 Bulk 批量写入后整个流程缩短到 3 分钟左右。核心思路是攒够一定数量或一段时间再一次性提交。public void bulkIndexDocs(ListDocEntity docList) throws IOException { BulkRequest.Builder br new BulkRequest.Builder(); for (DocEntity doc : docList) { br.operations(op - op .index(idx - idx .index(docs) .id(doc.getId()) .document(doc) ) ); } BulkResponse response client.bulk(br.build()); if (response.errors()) { for (BulkResponseItem item : response.items()) { if (item.error() ! null) { log.error(批量写入失败, id{}, error{}, item.id(), item.error().reason()); } } } }BulkRequest.Builder的operations()方法可以连续追加操作一次请求支持多个不同类型的操作混合比如一部分是 index、一部分是 delete。实际生产里一次 Bulk 请求的 body 大小建议控制在 5MB 到 15MB 之间太大容易把 ES 的 HTTP 服务压死太小又浪费网络吞吐。我一般按固定条数分批比如每 5000 条一个批次再配合循环提交。5.2 批量更新与批量删除批量更新在数据订正场景很常见比如某个字段规则调整后要全量替换。操作方式类似但在operations()里用update子操作需要额外指定doc内容public void bulkUpdateDoc(ListDocEntity docList) throws IOException { BulkRequest.Builder br new BulkRequest.Builder(); for (DocEntity doc : docList) { br.operations(op - op .update(u - u .index(docs) .id(doc.getId()) .action(a - a.doc(doc)) ) ); } BulkResponse response client.bulk(br.build()); ... }批量删除是给前端做勾选删除接口用的一次删除几千个 ID如果循环 DeleteRequest 也会有明显延迟。直接构建 Bulk 请求public void bulkDeleteDoc(ListString ids) throws IOException { BulkRequest.Builder br new BulkRequest.Builder(); for (String id : ids) { br.operations(op - op.delete(d - d.index(docs).id(id))); } BulkResponse response client.bulk(br.build()); }批量请求返回的BulkResponse里有一个errors()方法判断整个批量操作是否全部成功。注意这个方法是全局的只要有一条失败就返回 true。逐条检查items()定位失败的具体 item 和原因一般多为字段格式错误或版本冲突。不要只在errors()为 true 时打印一个笼统的错误日志那样排查问题没有抓手。提示批量写入前建议关闭 refresh 间隔或者设置为-1。ES 默认每 1 秒刷新一次索引批量导入时每次 refresh 都会产生额外的段合并开销。等批量导入完了再手动执行一次_refresh让数据立即可查。5.3 批量操作的分批与异常处理策略我第一批导入 5 万条数据时最初拿全部数据一次性提交结果 ES 节点直接内存飙高请求超时。后面调整为每批 3000 条加Thread.sleep(200)的节奏稳定很多。这个数值不是拍脑袋定的3000 条文档如果平均每条 1KB一批大概 3MB 请求体单节点完全扛得住200 毫秒的间隔是给 ES 一点 refresh 和 disk flush 的时间。如果机器配置更高可以适当加大批量、缩短间隔但建议观察 ES 节点 CPU 和堆内存使用率来动态调整。批量失败的重试策略也很关键。ES 返回的失败分两种一种是单个文档格式错误这种重试一万次还是错应该记录下来走人工修正另一种是 ES 集群临时压力大导致的EsRejectedExecutionException这种可以退避重试。我的做法是捕获异常后对失败批次做指数退避重试第一次等 1 秒第二次等 2 秒最多重试 3 次超过就写入本地错误日志文件等后续补偿任务处理。6. 结构化条件查询与结果处理6.1 Bool 查询组合条件的开发范式文档操作不止增删改查询才是使用频率最高的。ES 8 的 Java API Client 里查询统一走SearchRequest核心是通过Query.Builder构建查询 DSL。最常用的是bool查询用来组合 must、filter、should、must_not 四种条件。这个项目里的典型需求是首页搜索框输入关键词要求标题和正文都匹配同时按标签过滤、按时间范围限制、排除已删除状态。public SearchResponseDocEntity searchDocs(String keyword, String tag, LocalDateTime startTime, LocalDateTime endTime) throws IOException { SearchRequest request SearchRequest.of(s - s .index(docs) .query(q - q .bool(b - { if (keyword ! null !keyword.isBlank()) { b.must(m - m .multiMatch(mm - mm .query(keyword) .fields(title^3, content) .operator(Operator.And) ) ); } if (tag ! null !tag.isBlank()) { b.filter(f - f.term(t - t.field(tags).value(tag))); } if (startTime ! null) { b.filter(f - f.range(r - r .date(d - d.field(createTime).gte(startTime.toString())) )); } if (endTime ! null) { b.filter(f - f.range(r - r .date(d - d.field(createTime).lte(endTime.toString())) )); } b.mustNot(m - m.term(t - t.field(status).value(deleted))); return b; }) ) .from(0) .size(10) .sort(srt - srt.field(f - f.field(createTime).order(SortOrder.Desc))) ); return client.search(request, DocEntity.class); }multiMatch是同时检索多个字段的利器。fields(title^3, content)里的^3表示标题字段的权重是正文的 3 倍搜索分布式锁时标题命中的文档会排在正文命中的文档前面。Operator.And表示关键词分词后每个词都必须命中防止出现只匹配一半的情况。must、filter、should的区别是很多新手比较容易混淆的地方must影响文档的相关性评分filter只在过滤结果时不参与打分性能更好。所以像标签、时间范围这类条件我统一放filter只有关键词搜索这种真正影响排序的才放must。从执行计划来看filter条件可以被缓存多次执行相同过滤时性能提升非常明显。6.2 分页、排序与高亮的显示细节分页参数from和size是最直观的from默认从 0 开始size是每页条数。但 ES 的深分页有性能陷阱from5000,size10这种请求需要在每个分片上先取 5010 条文档再聚合排序非常耗内存。要做深度分页必须换search_after或scroll方式前者适合前端翻页后者适合大数据量导出。排序上text字段不能直接排序所以我当时在 mapping 里设计了title.keyword子字段排序时用createTime默认倒序这个字段是 date 类型天然支持排序不需要额外处理。高亮显示是搜索场景的刚需。ES 返回的高亮片段可以直接嵌入前端页面不需要后端再进行关键词截取。代码里给搜索请求追加highlight配置SearchRequest request SearchRequest.of(s - s .index(docs) .query(...) .highlight(h - h .fields(title, f - f.preTags(em classhighlight).postTags(/em)) .fields(content, f - f.fragmentSize(100).numberOfFragments(1)) ) );fragmentSize(100)表示每个高亮片段截取 100 个字符numberOfFragments(1)表示每个字段最多返回 1 个高亮片段。这样控制返回体大小也避免前端展示大量重复上下文。响应处理时高亮内容不在source()里要单独从response.highlight()取。做法是先拿Hit列表对每个 hit 重新组装一个带高亮文本的 DTO。或者更简单粗暴的办法把高亮字段直接拼进source()对应字段里返回给前端省去前端 parsing 工作。6.3 聚合统计的响应结构理解聚合是 ES 相比传统数据库的差异化优势。当时的需求是统计不同标签下文档数量的分布接口给前端画饼图用。构建聚合请求和解析响应都不复杂但结构需要理解清楚。public void countByTag() throws IOException { SearchRequest request SearchRequest.of(s - s .index(docs) .size(0) .aggregations(tagCount, agg - agg .terms(t - t.field(tags).size(10)) ) ); SearchResponseDocEntity response client.search(request, DocEntity.class); StringTermsAggregate tagCount response.aggregations().get(tagCount).terms(); for (StringTermsBucket bucket : tagCount.buckets().array()) { log.info(标签{}, 数量{}, bucket.key().stringValue(), bucket.docCount()); } }size(0)表示不返回文档详情只返回聚合结果对纯粹统计场景来说能省下大量网络传输。聚合响应里的buckets()因为 JSON 数组可能为空老版本直接返回数组新版本返回一个BucketCollection包装对象要调用.array()才能拿列表。关键词的多字段聚合有个坑如果tags是text类型terms聚合会报failed to parse field [tags] of type [text]必须用tags.keyword来聚合。这也是为什么前期 mapping 设计里要给需要过滤和聚合的字段多定义一个 keyword 子字段否则后期没法加。7. 常见问题与排查技巧实录7.1 版本兼容与环境问题速查整个项目过程中我整理了一个常见问题表基本都是实际踩过或者帮别人排查过的问题现象根本原因解决方案NoSuchMethodError: RestClientBuilder.setHttpClientConfigCallbackelasticsearch-java与elasticsearch-rest-client版本不一致检查依赖树确保两者版本同属一个 release必要时显式指定版本写入LocalDateTime字段报 query 解析失败Jackson 默认序列化时间格式与 ES date 格式不匹配注册JavaTimeModule关闭WRITE_DATES_AS_TIMESTAMPS启动时报Unable to parse response body客户端版本低于服务端版本响应 JSON 结构对不上让客户端版本不高于服务端主版本8.x 客户端尽量选最新小版本聚合报fielddata错误对text字段执行 terms 聚合使用字段的 keyword 子字段或映射时把字段类型改为 keyword连接池打满异常并发请求数超过MaxConnTotal调高连接数配置或排查是否有连接泄漏确保客户端是单例bulk 批量响应 errors 为 true 但单条没有 error部分操作被 retry 后成功但整体仍有失败项遍历items()检查所有失败项不要只看第一项7.2 排查思路与调试手段在排查 ES 客户端问题的时候我的经验是先分清是客户端问题还是 ES 服务端问题。第一步看 ES 日志如果服务端没有输出异常多半是请求构造或响应解析的问题。第二步开启客户端的 trace 日志新版客户端支持设置 logger 级别能看到完整的 HTTP 请求和响应报文这一步最直观。logback 配置里加logger nameorg.apache.http levelDEBUG/ logger nameco.elastic.clients levelDEBUG/不过 trace 日志量非常大生产环境不要一直开着排查问题时临时开个 5 分钟够了。是针对某个特定请求定位字段格式问题很有效。7.3 写入吞吐与慢查询的调优笔记写入性能上除了前面提到的批量大小和 refresh 间隔外还有几个不起眼但影响很大的参数。number_of_replicas在批量导入期间可以临时设为 0副本复制会占用大量 IO 和网络带宽导入完成后再改回来。index.translog.durability也可以从默认的request调成async减少每次写入后的磁盘 flush 次数但要做好节点宕机丢失少量数据的心理准备这个参数只在数据可重建的场景用。慢查询调优要看_search慢日志。在索引 settings 里设置index.search.slowlog.threshold.query.warn: 2s, index.search.slowlog.threshold.fetch.warn: 1s超过阈值的搜索会被记录到 ES 日志里能直观看到哪些查询走了全表扫描、哪些聚合拖慢了整体响应。一次我们线上出现搜索超时排查后发现是某个wildcard查询对keyword字段做了前缀模糊匹配这类查询无法利用倒排索引后来改成edge_ngram分词器才解决。8. 实操过程与代码总结8.1 完整链路代码串联我把项目中经过验证的完整流程串成一段演示代码包含了建索引、批量写入、搜索聚合的核心方法调用顺序方便整体感知。这个演示代码对应一个测试类可以直接运行验证环境SpringBootTest public class EsDocOperationDemo { Autowired private ElasticsearchClient client; Test void testDocLifecycle() throws Exception { // 建索引幂等 createIndex(docs); // 单条写入 DocEntity doc new DocEntity(); doc.setId(1); doc.setTitle(SpringBoot整合ES实战); doc.setContent(本文详细讲解新版Java API Client的文档操作包括增删改查和批量操作。); doc.setAuthor(某开发者); doc.setTags(List.of(Java, Elasticsearch)); doc.setCreateTime(LocalDateTime.now()); doc.setViewCount(100); client.index(i - i.index(docs).id(doc.getId()).document(doc)); // 按ID查询 GetResponseDocEntity getResp client.get(g - g.index(docs).id(1), DocEntity.class); System.out.println(JSON.toJSONString(getResp.source())); // 局部更新 client.update(u - u.index(docs).id(1).action(a - a.doc(Map.of(viewCount, 101))), DocEntity.class); // 条件搜索 SearchResponseDocEntity searchResp client.search(s - s .index(docs) .query(q - q.bool(b - b .must(m - m.multiMatch(mm - mm.fields(title^3, content).query(ES 实战))) .filter(f - f.term(t - t.field(tags).value(Java))) )), DocEntity.class); // 聚合统计 SearchResponseDocEntity aggResp client.search(s - s .index(docs) .size(0) .aggregations(byTag, a - a.terms(t - t.field(tags.keyword))), DocEntity.class); } }注意最后的聚合里用tags.keyword而不是tags原因前面已经讲过。如果图省事直接用tags在这个 mapping 定义下一定报错。8.2 对旧项目迁移的取舍建议如果你现在有个项目还在用 RestHighLevelClient想迁到新版 API我的建议是不要做全局重写采用双客户端并存的方式过渡。在配置类里同时注册旧版 RestHighLevelClient 和新版 ElasticsearchClient新增代码用新客户端老代码逐步替换等完全替换后再移除旧依赖。这样能保证业务不中断也留出验证时间。迁移时的映射关系大致是RestHighLevelClient.get(...)变成client.get(...)SearchSourceBuilder变成Query.BuilderBulkRequest加doc变成BulkRequest.Builder.operations(...)。整体思路一致但 builder 模式的写法需要适应几天。注意新版客户端的client.get()返回的是GetResponseT而不是旧版的GetResponse裸类型响应里的source()方法直接返回泛型对象不需要再手动反序列化。8.3 从项目复盘里提炼的三个建议第一ES 版本升级时要顺带检查客户端版本。ES 8.0 和 8.5 之间的 API 有微调比如UpdateRequest的doc方法在某个小版本后要改成action(a - a.doc(...))直接用旧代码编译不通过时不要强行降版本而是查一下当前版本对应的 API 写法。第二文档操作是把数据同步进 ES 的第一步但它不是终点。ES 的数据一致性保障不如数据库不要在业务代码里把 ES 当主存储。项目里知识库系统的查询走 ES但修改和删除同时操作 MySQL 和 ES两侧都带上事务语义失败时用消息队列补偿这样 ES 出问题不会导致核心数据丢失。第三生产环境一定要监控 ES 集群的磁盘水位和堆内存使用率文档操作越多段合并和 GC 压力越大。我见过因为日志索引无限增长导致磁盘打满整个集群变成只读的严重事故确保索引生命周期管理策略从一开始就配好能省掉很多凌晨被叫醒的烦恼。
1. 项目概述与前期准备断断续续把 SpringBoot 整合 Elasticsearch 8.0 的新版 Java API Client 用了一遍发现网上铺天盖地还在讲旧版的 RestHighLevelClient或者各种包装过的 Spring Data Elasticsearch。确实老客户端已经进入维护期官方主推的就是 Java API Client for Elasticsearch。这一篇专门讲文档操作也就是最常用的增删改查、批量写入、条件查询这些基于我自己在一个实际项目里的完整落地记录来写直接能拿过去用。1.1 核心需求解析这个项目的场景很典型某团队内部的知识库系统需要把文档内容、标签、作者、创建时间这些信息同步到 Elasticsearch 里做全文检索和聚合分析。数据量不算大但要求响应快而且要支持按关键词搜正文、按标签过滤、按时间范围统计这类操作所以数据库里的内容得实时同步到 ES。技术选型上既然已经确定用 SpringBoot 2.7 做基础框架ES 服务端是 8.0 版本那客户端就必须用最新的 Java API Client原因很简单RestHighLevelClient 在 ES 8.x 里已经不再推荐新版 API 在连接管理、类型安全、响应式调用上都更干净。整个项目拆成四块来做第一块是依赖引入和配置类第二块是索引创建和映射定义第三块是文档的单条操作和批量操作第四块是查询与聚合。这篇重点关注第三块但前面两块是基础会一并把关键代码和踩坑点说清楚。1.2 工具选型与核心依赖先看 Maven 依赖。新版 Java API Client 的坐标是co.elastic.clients:elasticsearch-java版本号要和服务端对应。ES 8.0 对应 8.x 的客户端我用的 8.5.1。这里有个容易忽略的点新版客户端底层走的是 Elasticsearch TransportClient 重构后的 REST 协议但它依赖一个独立的 JSON 解析库默认是 Jackson所以还需要引入jackson-databind和jackson-datatype-jsr310来处理 LocalDateTime 这类 Java 时间类型。dependency groupIdco.elastic.clients/groupId artifactIdelasticsearch-java/artifactId version8.5.1/version /dependency dependency groupIdcom.fasterxml.jackson.core/groupId artifactIdjackson-databind/artifactId version2.13.4/version /dependency dependency groupIdcom.fasterxml.jackson.datatype/groupId artifactIdjackson-datatype-jsr310/artifactId version2.13.4/version /dependency如果用的是 SpringBoot 2.7Spring 本身自带了一个 Jackson 版本直接引可能版本冲突。我当时的处理办法是把上面两个 Jackson 依赖的版本去掉让 SpringBoot 的 BOM 统一管理只保留elasticsearch-java单独指定版本。elasticsearch-java内部会传递依赖elasticsearch-rest-client这个是底层 HTTP 通信的组件不需要单独引。提示不要用spring-boot-starter-data-elasticsearch的自动配置来管理 ES 客户端版本它的版本管理策略和新版 Java API Client 不是一套体系混用容易出兼容性问题。建议全部手动建 Bean不走 SpringBoot 的自动配置。2. 建立客户端连接的细节拆解2.1 新版 API 的编程模型ES 8.0 的 Java API Client 和旧版最大区别是全面拥抱 builder 模式几乎每个请求对象都要通过XxxRequest.Builder来构造然后用client.xxx(request)方式调用。刚开始写会觉得很啰嗦比如查询一个文档要先new GetRequest.Builder().index(...).id(...).build()但是好处是每个参数在 IDE 里都有提示不容易写错而且请求和响应都是强类型的编译期就能发现大部分问题。连接配置上核心是RestClient和ElasticsearchClient两层。RestClient负责底层的 HTTP 连接管理ElasticsearchClient在它之上做请求封装和结果解析。实际使用中我建议把ElasticsearchClient注册成一个 Spring 单例 Bean避免每次调用都创建客户端连接复用和线程安全都由框架帮你处理。2.2 连接池与超时参数的取舍下面是我项目里用的配置类参数是跑了一段时间后调出来的结果。Configuration public class ElasticsearchConfig { Bean(destroyMethod close) public ElasticsearchClient elasticsearchClient() { RestClientBuilder builder RestClient.builder( new HttpHost(127.0.0.1, 9200, http) ); builder.setRequestConfigCallback(requestConfigBuilder - requestConfigBuilder .setConnectTimeout(5000) .setSocketTimeout(60000) .setConnectionRequestTimeout(5000) ); builder.setHttpClientConfigCallback(httpClientBuilder - { httpClientBuilder.setMaxConnTotal(100); httpClientBuilder.setMaxConnPerRoute(20); return httpClientBuilder; }); RestClient restClient builder.build(); JacksonJsonpMapper mapper new JacksonJsonpMapper(); return new ElasticsearchClient(restClient, mapper); } }setConnectTimeout(5000)是建立 TCP 连接的等待时间这个值设太大容易在 ES 集群故障时让请求线程全部挂住设太小又可能因为网络抖动频繁报连接超时。setSocketTimeout(60000)比较关键ES 的聚合查询和数据量大的批量写入可能超过 10 秒如果沿用默认的 30 秒很容易踩到SocketTimeoutException。setMaxConnTotal(100)和setMaxConnPerRoute(20)的意思是总连接数最多 100 条单个 ES 节点最多 20 条这个要结合项目并发量来定如果 QPS 高连接数太小会造成请求排队等待我在压测环境里出现过因为连接池打满导致大量ConnectionPoolTimeoutException的情况。JacksonJsonpMapper这一行特别值得说。ES 8 的 Java API Client 把 JSON 序列化做成可插拔设计默认可以是 Jackson、JSON-B 或者自带的轻量实现。用 Jackson 的好处是能和我们 Spring 项目里的 ObjectMapper 保持风格一致但要注意日期格式的处理。Elasticsearch 对日期类型默认用yyyy-MM-ddTHH:mm:ssZ格式存储Jackson 默认序列化 LocalDateTime 是一串数组比如[2023,5,10,14,30,0]ES 解析不了。解决办法是给 mapper 注册 JavaTimeModule 并设置写入日期为 ISO 格式。ObjectMapper objectMapper new ObjectMapper(); objectMapper.registerModule(new JavaTimeModule()); objectMapper.disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS); JacksonJsonpMapper mapper new JacksonJsonpMapper(objectMapper);这块不改的话你往索引里写带时间字段的文档时大概率会遇到failed to parse field [createTime] of type [date]的报错非常坑。3. 索引创建与映射定义3.1 为什么文档操作前要先做映射Elasticsearch 的索引相当于数据库里的表文档相当于一行记录。但表和表有个重要区别索引在写入第一个文档前如果不显式定义映射ES 会自动为每个字段推断类型。比如第一次写入的tags字段是字符串数组ES 就把tags映射成text类型后面如果又写入一个中文标题titleES 会默认给它生成title的text类型和title.keyword子字段。自动映射看起来省事但对生产环境是隐患。最典型的问题是中文分词默认 mapping 对text类型不会做中文分词查询分布式三个字匹配不到内容是常有的事。所以我建议在文档操作前先把索引的 mapping 和 settings 定义好尤其是analysis分词器配置以及哪些字段需要精确匹配、哪些字段需要聚合统计。3.2 定义索引与分词器的完整代码当时项目文档索引要求标题用 IK 分词器标签不做分词只做精确匹配创建时间用 date 类型。代码如下public void createIndex(String indexName) throws IOException { String settingsJson { settings: { number_of_shards: 3, number_of_replicas: 1, analysis: { filter: { ik_smart_pinyin: { type: pinyin, keep_first_letter: true, keep_separate_first_letter: false, keep_full_pinyin: true, keep_joined_full_pinyin: true, lowercase: true } }, analyzer: { ik_pinyin_analyzer: { type: custom, tokenizer: ik_max_word, filter: [ik_smart_pinyin] } } } }, mappings: { properties: { id: { type: keyword }, title: { type: text, analyzer: ik_max_word, search_analyzer: ik_smart, fields: { keyword: { type: keyword, ignore_above: 256 } } }, content: { type: text, analyzer: ik_max_word, search_analyzer: ik_smart }, author: { type: keyword }, tags: { type: keyword }, createTime: { type: date, format: yyyy-MM-dd HH:mm:ss }, viewCount: { type: integer } } } } ; CreateIndexRequest request CreateIndexRequest.of(r - r.index(indexName).withJson(new StringReader(settingsJson))); boolean exists client.indices().exists(e - e.index(indexName)).value(); if (!exists) { client.indices().create(request); } }number_of_shards设 3 是因为单节点上 3 个分片能发挥多线程并行检索的优势但如果机器性能一般也可以设 1分片太多反而增加协调开销。number_of_replicas至少 1如果集群只有一个节点副本会处于未分配状态这时可以临时改成 0或者等后续加节点后再调回来否则集群健康状态是 yellow不影响读写但不建议长期这样。title字段这里特别设计了keyword子字段。因为在前端列表页经常要按照标题精确过滤或者做排序text类型本身无法排序只能通过子字段title.keyword来实现。ignore_above: 256表示超过 256 字符的字符串不会写入 keyword 子字段防止超长标题撑爆内存。创建索引的时机我放在应用启动后的一个初始化方法里判断索引不存在才创建重启不会重复报错。索引一旦创建mapping 基本不能改后面要加字段只能通过_mappingAPI 增量追加所以前期想清楚字段设计能省不少事。4. 单文档增删改查的实操详解4.1 用 Index 和 Create 写入文档的区别写入单条文档有两条路径IndexRequest和CreateRequest。前者是存在则覆盖不存在则新增的 upsert 语义后者是如果文档已存在就报版本冲突的只新增语义。我项目里知识库文档的 ID 由业务系统生成需要保证同一篇文档多次同步不会产生重复数据所以用IndexRequest更合适但要实现仅首次导入不允许覆盖历史记录的场景就用CreateRequest。public void indexDocument(DocEntity doc) throws IOException { IndexRequestDocEntity request IndexRequest.of(r - r .index(docs) .id(doc.getId()) .document(doc) ); IndexResponse response client.index(request); log.info(索引文档结果, id{}, result{}, response.id(), response.result()); }document()方法接收一个对象框架内部通过 JsonpMapper 把它序列化成 JSON。这也是新版客户端比旧版舒服的地方——不需要手动构造XContentBuilder直接丢一个 Java 对象进去就行。实体类定义如下public class DocEntity { private String id; private String title; private String content; private String author; private ListString tags; private LocalDateTime createTime; private Integer viewCount; // getter/setter 省略 }字段名序列化出来和 Java 属性名保持一致createTime会被格式化成yyyy-MM-dd HH:mm:ss字符串。4.2 查询、更新和删除文档的完整链路按 ID 查询文档是高频操作代码很简单public DocEntity getDocById(String id) throws IOException { GetResponseDocEntity response client.get(g - g.index(docs).id(id), DocEntity.class); if (response.found()) { return response.source(); } return null; }注意found()方法有两个用途判断文档是否存在之外还能避免响应里 source 为空时强转 NPE。ES 允许你查询一个不存在的 ID响应 HTTP 状态是 404但客户端在found()返回 false 的情况下不会抛异常所以要自己判断。更新文档有全量替换和局部更新两种。局部更新的底层走_updateAPI不会重传整个文档适合只改一个字段的场景public void updateDoc(String id, String newContent) throws IOException { DocEntity doc new DocEntity(); doc.setContent(newContent); UpdateRequestDocEntity, DocEntity request UpdateRequest.of(u - u .index(docs) .id(id) .doc(doc) ); UpdateResponse response client.update(request, DocEntity.class); log.info(更新文档结果, result{}, response.result()); }这里有个难点UpdateRequest.of方法有两个泛型参数前面是文档类型后面是部分更新数据类型。如果只传doc一个对象两个泛型参数可以都用DocEntity。更新的字段会做 merge没传的字段原样保留。删除文档用DeleteRequest同理不再赘述。但有一个实际项目很容易踩的坑用update方法更新时ES 要求传入的部分更新文档里不能包含值为 null 的字段如果实体类里有 null 属性Jackson 序列化的时候会写出field:nullES 会把该字段也更新为 null。解决办法是给需要忽略 null 的字段加JsonInclude(Include.NON_NULL)注解或者更新时构造一个只包含目标字段的 Map 传进去。我踩过这个坑有一次更新文档时新建的 DocEntity 里没给 tags 赋值结果 tags 为 null 直接把原来的标签清空了。后来把所有更新场景统一改成用 Map 或单独构造 partial 实体只放要改的字段这个问题才彻底解决。4.3 利用版本号做乐观锁并发控制ES 文档有内部的_seq_no和_primary_term两个字段合在一起相当于版本号。多线程同时更新同一文档时可以用IfSeqNo和IfPrimaryTerm做乐观锁类似数据库的乐观锁机制。public void updateWithVersion(String id, String newTitle, long seqNo, long primaryTerm) throws IOException { UpdateRequestDocEntity, DocEntity request UpdateRequest.of(u - u .index(docs) .id(id) .ifSeqNo(seqNo) .ifPrimaryTerm(primaryTerm) .doc(Map.of(title, newTitle)) ); try { client.update(request, DocEntity.class); } catch (ElasticsearchException e) { if (e.status() 409) { log.warn(版本冲突文档已被他人修改id{}, id); } } }实际使用时先把查询出的_seq_no和_primary_term带在业务对象里提交更新时传给服务端。如果这期间文档被别人改过ES 返回 409 Conflict客户端捕获后可以根据业务决定重试还是提示冲突。这个方法在旧版 RestHighLevelClient 里命名不同新版 API 中直接叫ifSeqNo和ifPrimaryTerm搞混了会编译不过。5. 批量文档操作的性能之门5.1 Bulk 批量写入的正确打开方式同步文档进 ES如果一篇一篇地写 IndexRequest网络往返开销非常大。项目里第一批要导入 5 万条历史数据单条写入耗时差不多在 20 分钟以上换成 Bulk 批量写入后整个流程缩短到 3 分钟左右。核心思路是攒够一定数量或一段时间再一次性提交。public void bulkIndexDocs(ListDocEntity docList) throws IOException { BulkRequest.Builder br new BulkRequest.Builder(); for (DocEntity doc : docList) { br.operations(op - op .index(idx - idx .index(docs) .id(doc.getId()) .document(doc) ) ); } BulkResponse response client.bulk(br.build()); if (response.errors()) { for (BulkResponseItem item : response.items()) { if (item.error() ! null) { log.error(批量写入失败, id{}, error{}, item.id(), item.error().reason()); } } } }BulkRequest.Builder的operations()方法可以连续追加操作一次请求支持多个不同类型的操作混合比如一部分是 index、一部分是 delete。实际生产里一次 Bulk 请求的 body 大小建议控制在 5MB 到 15MB 之间太大容易把 ES 的 HTTP 服务压死太小又浪费网络吞吐。我一般按固定条数分批比如每 5000 条一个批次再配合循环提交。5.2 批量更新与批量删除批量更新在数据订正场景很常见比如某个字段规则调整后要全量替换。操作方式类似但在operations()里用update子操作需要额外指定doc内容public void bulkUpdateDoc(ListDocEntity docList) throws IOException { BulkRequest.Builder br new BulkRequest.Builder(); for (DocEntity doc : docList) { br.operations(op - op .update(u - u .index(docs) .id(doc.getId()) .action(a - a.doc(doc)) ) ); } BulkResponse response client.bulk(br.build()); ... }批量删除是给前端做勾选删除接口用的一次删除几千个 ID如果循环 DeleteRequest 也会有明显延迟。直接构建 Bulk 请求public void bulkDeleteDoc(ListString ids) throws IOException { BulkRequest.Builder br new BulkRequest.Builder(); for (String id : ids) { br.operations(op - op.delete(d - d.index(docs).id(id))); } BulkResponse response client.bulk(br.build()); }批量请求返回的BulkResponse里有一个errors()方法判断整个批量操作是否全部成功。注意这个方法是全局的只要有一条失败就返回 true。逐条检查items()定位失败的具体 item 和原因一般多为字段格式错误或版本冲突。不要只在errors()为 true 时打印一个笼统的错误日志那样排查问题没有抓手。提示批量写入前建议关闭 refresh 间隔或者设置为-1。ES 默认每 1 秒刷新一次索引批量导入时每次 refresh 都会产生额外的段合并开销。等批量导入完了再手动执行一次_refresh让数据立即可查。5.3 批量操作的分批与异常处理策略我第一批导入 5 万条数据时最初拿全部数据一次性提交结果 ES 节点直接内存飙高请求超时。后面调整为每批 3000 条加Thread.sleep(200)的节奏稳定很多。这个数值不是拍脑袋定的3000 条文档如果平均每条 1KB一批大概 3MB 请求体单节点完全扛得住200 毫秒的间隔是给 ES 一点 refresh 和 disk flush 的时间。如果机器配置更高可以适当加大批量、缩短间隔但建议观察 ES 节点 CPU 和堆内存使用率来动态调整。批量失败的重试策略也很关键。ES 返回的失败分两种一种是单个文档格式错误这种重试一万次还是错应该记录下来走人工修正另一种是 ES 集群临时压力大导致的EsRejectedExecutionException这种可以退避重试。我的做法是捕获异常后对失败批次做指数退避重试第一次等 1 秒第二次等 2 秒最多重试 3 次超过就写入本地错误日志文件等后续补偿任务处理。6. 结构化条件查询与结果处理6.1 Bool 查询组合条件的开发范式文档操作不止增删改查询才是使用频率最高的。ES 8 的 Java API Client 里查询统一走SearchRequest核心是通过Query.Builder构建查询 DSL。最常用的是bool查询用来组合 must、filter、should、must_not 四种条件。这个项目里的典型需求是首页搜索框输入关键词要求标题和正文都匹配同时按标签过滤、按时间范围限制、排除已删除状态。public SearchResponseDocEntity searchDocs(String keyword, String tag, LocalDateTime startTime, LocalDateTime endTime) throws IOException { SearchRequest request SearchRequest.of(s - s .index(docs) .query(q - q .bool(b - { if (keyword ! null !keyword.isBlank()) { b.must(m - m .multiMatch(mm - mm .query(keyword) .fields(title^3, content) .operator(Operator.And) ) ); } if (tag ! null !tag.isBlank()) { b.filter(f - f.term(t - t.field(tags).value(tag))); } if (startTime ! null) { b.filter(f - f.range(r - r .date(d - d.field(createTime).gte(startTime.toString())) )); } if (endTime ! null) { b.filter(f - f.range(r - r .date(d - d.field(createTime).lte(endTime.toString())) )); } b.mustNot(m - m.term(t - t.field(status).value(deleted))); return b; }) ) .from(0) .size(10) .sort(srt - srt.field(f - f.field(createTime).order(SortOrder.Desc))) ); return client.search(request, DocEntity.class); }multiMatch是同时检索多个字段的利器。fields(title^3, content)里的^3表示标题字段的权重是正文的 3 倍搜索分布式锁时标题命中的文档会排在正文命中的文档前面。Operator.And表示关键词分词后每个词都必须命中防止出现只匹配一半的情况。must、filter、should的区别是很多新手比较容易混淆的地方must影响文档的相关性评分filter只在过滤结果时不参与打分性能更好。所以像标签、时间范围这类条件我统一放filter只有关键词搜索这种真正影响排序的才放must。从执行计划来看filter条件可以被缓存多次执行相同过滤时性能提升非常明显。6.2 分页、排序与高亮的显示细节分页参数from和size是最直观的from默认从 0 开始size是每页条数。但 ES 的深分页有性能陷阱from5000,size10这种请求需要在每个分片上先取 5010 条文档再聚合排序非常耗内存。要做深度分页必须换search_after或scroll方式前者适合前端翻页后者适合大数据量导出。排序上text字段不能直接排序所以我当时在 mapping 里设计了title.keyword子字段排序时用createTime默认倒序这个字段是 date 类型天然支持排序不需要额外处理。高亮显示是搜索场景的刚需。ES 返回的高亮片段可以直接嵌入前端页面不需要后端再进行关键词截取。代码里给搜索请求追加highlight配置SearchRequest request SearchRequest.of(s - s .index(docs) .query(...) .highlight(h - h .fields(title, f - f.preTags(em classhighlight).postTags(/em)) .fields(content, f - f.fragmentSize(100).numberOfFragments(1)) ) );fragmentSize(100)表示每个高亮片段截取 100 个字符numberOfFragments(1)表示每个字段最多返回 1 个高亮片段。这样控制返回体大小也避免前端展示大量重复上下文。响应处理时高亮内容不在source()里要单独从response.highlight()取。做法是先拿Hit列表对每个 hit 重新组装一个带高亮文本的 DTO。或者更简单粗暴的办法把高亮字段直接拼进source()对应字段里返回给前端省去前端 parsing 工作。6.3 聚合统计的响应结构理解聚合是 ES 相比传统数据库的差异化优势。当时的需求是统计不同标签下文档数量的分布接口给前端画饼图用。构建聚合请求和解析响应都不复杂但结构需要理解清楚。public void countByTag() throws IOException { SearchRequest request SearchRequest.of(s - s .index(docs) .size(0) .aggregations(tagCount, agg - agg .terms(t - t.field(tags).size(10)) ) ); SearchResponseDocEntity response client.search(request, DocEntity.class); StringTermsAggregate tagCount response.aggregations().get(tagCount).terms(); for (StringTermsBucket bucket : tagCount.buckets().array()) { log.info(标签{}, 数量{}, bucket.key().stringValue(), bucket.docCount()); } }size(0)表示不返回文档详情只返回聚合结果对纯粹统计场景来说能省下大量网络传输。聚合响应里的buckets()因为 JSON 数组可能为空老版本直接返回数组新版本返回一个BucketCollection包装对象要调用.array()才能拿列表。关键词的多字段聚合有个坑如果tags是text类型terms聚合会报failed to parse field [tags] of type [text]必须用tags.keyword来聚合。这也是为什么前期 mapping 设计里要给需要过滤和聚合的字段多定义一个 keyword 子字段否则后期没法加。7. 常见问题与排查技巧实录7.1 版本兼容与环境问题速查整个项目过程中我整理了一个常见问题表基本都是实际踩过或者帮别人排查过的问题现象根本原因解决方案NoSuchMethodError: RestClientBuilder.setHttpClientConfigCallbackelasticsearch-java与elasticsearch-rest-client版本不一致检查依赖树确保两者版本同属一个 release必要时显式指定版本写入LocalDateTime字段报 query 解析失败Jackson 默认序列化时间格式与 ES date 格式不匹配注册JavaTimeModule关闭WRITE_DATES_AS_TIMESTAMPS启动时报Unable to parse response body客户端版本低于服务端版本响应 JSON 结构对不上让客户端版本不高于服务端主版本8.x 客户端尽量选最新小版本聚合报fielddata错误对text字段执行 terms 聚合使用字段的 keyword 子字段或映射时把字段类型改为 keyword连接池打满异常并发请求数超过MaxConnTotal调高连接数配置或排查是否有连接泄漏确保客户端是单例bulk 批量响应 errors 为 true 但单条没有 error部分操作被 retry 后成功但整体仍有失败项遍历items()检查所有失败项不要只看第一项7.2 排查思路与调试手段在排查 ES 客户端问题的时候我的经验是先分清是客户端问题还是 ES 服务端问题。第一步看 ES 日志如果服务端没有输出异常多半是请求构造或响应解析的问题。第二步开启客户端的 trace 日志新版客户端支持设置 logger 级别能看到完整的 HTTP 请求和响应报文这一步最直观。logback 配置里加logger nameorg.apache.http levelDEBUG/ logger nameco.elastic.clients levelDEBUG/不过 trace 日志量非常大生产环境不要一直开着排查问题时临时开个 5 分钟够了。是针对某个特定请求定位字段格式问题很有效。7.3 写入吞吐与慢查询的调优笔记写入性能上除了前面提到的批量大小和 refresh 间隔外还有几个不起眼但影响很大的参数。number_of_replicas在批量导入期间可以临时设为 0副本复制会占用大量 IO 和网络带宽导入完成后再改回来。index.translog.durability也可以从默认的request调成async减少每次写入后的磁盘 flush 次数但要做好节点宕机丢失少量数据的心理准备这个参数只在数据可重建的场景用。慢查询调优要看_search慢日志。在索引 settings 里设置index.search.slowlog.threshold.query.warn: 2s, index.search.slowlog.threshold.fetch.warn: 1s超过阈值的搜索会被记录到 ES 日志里能直观看到哪些查询走了全表扫描、哪些聚合拖慢了整体响应。一次我们线上出现搜索超时排查后发现是某个wildcard查询对keyword字段做了前缀模糊匹配这类查询无法利用倒排索引后来改成edge_ngram分词器才解决。8. 实操过程与代码总结8.1 完整链路代码串联我把项目中经过验证的完整流程串成一段演示代码包含了建索引、批量写入、搜索聚合的核心方法调用顺序方便整体感知。这个演示代码对应一个测试类可以直接运行验证环境SpringBootTest public class EsDocOperationDemo { Autowired private ElasticsearchClient client; Test void testDocLifecycle() throws Exception { // 建索引幂等 createIndex(docs); // 单条写入 DocEntity doc new DocEntity(); doc.setId(1); doc.setTitle(SpringBoot整合ES实战); doc.setContent(本文详细讲解新版Java API Client的文档操作包括增删改查和批量操作。); doc.setAuthor(某开发者); doc.setTags(List.of(Java, Elasticsearch)); doc.setCreateTime(LocalDateTime.now()); doc.setViewCount(100); client.index(i - i.index(docs).id(doc.getId()).document(doc)); // 按ID查询 GetResponseDocEntity getResp client.get(g - g.index(docs).id(1), DocEntity.class); System.out.println(JSON.toJSONString(getResp.source())); // 局部更新 client.update(u - u.index(docs).id(1).action(a - a.doc(Map.of(viewCount, 101))), DocEntity.class); // 条件搜索 SearchResponseDocEntity searchResp client.search(s - s .index(docs) .query(q - q.bool(b - b .must(m - m.multiMatch(mm - mm.fields(title^3, content).query(ES 实战))) .filter(f - f.term(t - t.field(tags).value(Java))) )), DocEntity.class); // 聚合统计 SearchResponseDocEntity aggResp client.search(s - s .index(docs) .size(0) .aggregations(byTag, a - a.terms(t - t.field(tags.keyword))), DocEntity.class); } }注意最后的聚合里用tags.keyword而不是tags原因前面已经讲过。如果图省事直接用tags在这个 mapping 定义下一定报错。8.2 对旧项目迁移的取舍建议如果你现在有个项目还在用 RestHighLevelClient想迁到新版 API我的建议是不要做全局重写采用双客户端并存的方式过渡。在配置类里同时注册旧版 RestHighLevelClient 和新版 ElasticsearchClient新增代码用新客户端老代码逐步替换等完全替换后再移除旧依赖。这样能保证业务不中断也留出验证时间。迁移时的映射关系大致是RestHighLevelClient.get(...)变成client.get(...)SearchSourceBuilder变成Query.BuilderBulkRequest加doc变成BulkRequest.Builder.operations(...)。整体思路一致但 builder 模式的写法需要适应几天。注意新版客户端的client.get()返回的是GetResponseT而不是旧版的GetResponse裸类型响应里的source()方法直接返回泛型对象不需要再手动反序列化。8.3 从项目复盘里提炼的三个建议第一ES 版本升级时要顺带检查客户端版本。ES 8.0 和 8.5 之间的 API 有微调比如UpdateRequest的doc方法在某个小版本后要改成action(a - a.doc(...))直接用旧代码编译不通过时不要强行降版本而是查一下当前版本对应的 API 写法。第二文档操作是把数据同步进 ES 的第一步但它不是终点。ES 的数据一致性保障不如数据库不要在业务代码里把 ES 当主存储。项目里知识库系统的查询走 ES但修改和删除同时操作 MySQL 和 ES两侧都带上事务语义失败时用消息队列补偿这样 ES 出问题不会导致核心数据丢失。第三生产环境一定要监控 ES 集群的磁盘水位和堆内存使用率文档操作越多段合并和 GC 压力越大。我见过因为日志索引无限增长导致磁盘打满整个集群变成只读的严重事故确保索引生命周期管理策略从一开始就配好能省掉很多凌晨被叫醒的烦恼。
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
