RestHighLevelClient实战指南：连接、CRUD、搜索与避坑

最近整理项目里一套老搜索服务，发现好几个模块还在用RestHighLevelClient操作Elasticsearch，顺手把使用手册重新撸了一遍，把实际操作中走过的弯路也一并记了下来。如果你正在做ES相关开发，或者项目里刚好有这块代码，这篇内容应该能帮你省下不少时间。

RestHighLevelClient是Elasticsearch官方在7.x时代主推的Java高级别REST客户端，封装了底层HTTP请求，对外提供类型安全的操作API，支持索引、文档、搜索、聚合、异步等几乎所有ES能力。我这里不打算做成官方文档的搬运，而是围绕真实业务场景，把怎么初始化、怎么写增删改查、怎么规避连接泄漏和超时问题，以及常见大坑一次讲清楚。

1. 先搞清楚：RestHighLevelClient到底解决了什么问题

在早期ES版本里，Java客户端分两种：一种是TransportClient，走TCP协议直连集群节点内部端口，它要求客户端版本与服务端版本完全一致，而且传输协议不对外公开，跨语言基本不可能；另一种是NodeClient，直接以节点身份加入集群，也很重。这类客户端的通病是集群部署一变，客户端配置就得跟着动，排查问题还得同时抓TCP报文，非常痛苦。

RestHighLevelClient的出现把客户端和服务端的交互方式统一到了HTTP层。只要服务端暴露了9200端口，客户端就可以通过HTTP请求完成所有操作。这对部署架构是很大的解放：客户端不关心节点之间怎么通信，也不关心数据分片在哪个节点，它只需要知道一个或多个HTTP入口地址。更重要的是，HTTP接口是公开稳定的，理论上有REST接口就能接入，非Java语言也可以参考这套交互逻辑。

RestHighLevelClient本身并不直接发HTTP请求，而是依赖底层RestClient做连接管理、请求重试、负载均衡。RestClient是ES官方提供的低级客户端，只负责把请求发出去并把响应解析成Response对象，不提供任何语义化的方法。HighLevelClient在它之上做了一层强类型封装，把不同类型的操作封装成Request、Response对象，开发者不需要拼JSON、不需要手动解析响应，代码可读性和维护性好很多。

从实际工程角度看，RestHighLevelClient还解决了另一个很实际的问题：多集群支持。在一个应用里可以初始化多个Client实例，分别指向不同的ES集群。比如我们生产环境有订单集群和日志集群，两个集群版本一样，但业务隔离，用两个HighLevelClient实例管理非常清晰。这一点在新版Java API Client里也同样支持。

不过要注意一点：ES从8.x开始官方主推Elasticsearch Java API Client，RestHighLevelClient进入维护模式，不再增加新功能，只做缺陷修复。但存量项目里RestHighLevelClient的使用量依然非常大，而且短期内大版本升级代价也高，所以熟练掌握它仍然很有必要。

2. 环境准备与依赖引入：版本匹配是头等大事

RestHighLevelClient的Maven依赖非常简单，核心就是把elasticsearch-rest-high-level-client这个包引入项目。需要注意的是完整依赖坐标里其实还带了一长串传递依赖，比如elasticsearch-core、elasticsearch-x-content这些，它们会从中央仓库自动拉下来。

我推荐在pom里显式声明rest-high-level-client的同时，把elasticsearch的其他依赖也锁定版本，避免依赖冲突。我这里用Maven做示例：

xml复制<dependency>
    <groupId>org.elasticsearch.client</groupId>
    <artifactId>elasticsearch-rest-high-level-client</artifactId>
    <version>7.17.25</version>
</dependency>

这里最关键的坑就是版本号。RestHighLevelClient的主版本号必须和ES服务端的大版本号一致，最好小版本也一致。比如服务端是7.17.x，客户端就用7.17.x。如果服务端是7.10.x，而客户端强行用7.17.x，很多新API不在服务端能力范围内，调用时会直接报错，比如ElasticsearchStatusException提示unknown operation。

我印象很深的一次是同事把客户端升到7.17，但服务端还是7.6，结果原先能正常跑的日期聚合突然报错，查了好久才发现是客户端把format参数带到了旧版本不认识的字段上。所以版本问题不要抱侥幸心理，匹配是第一原则。

另外如果你的项目是Spring Boot，还要注意ES客户端依赖中的log4j-api版本是否会与Spring Boot的log4j2冲突。ES客户端默认依赖log4j-api，如果项目里存在两个不同版本，会出现NoClassDefFoundError之类的诡异问题。解决办法是显式排除后引入统一版本，或者直接在dependencyManagement里锁定log4j版本。

Gradle项目写法类似：

gradle复制implementation 'org.elasticsearch.client:elasticsearch-rest-high-level-client:7.17.25'

依赖引入完之后，顺手在代码里打印一下版本信息，确认类加载用的是你期望的版本，这点排查疑难杂症时很有用。

3. 连接管理：不要只new一个RestClient就开工

很多刚接触RestHighLevelClient的同学看到示例代码里三行就初始化了客户端，很容易误以为连接管理和超时设置不需要关心。实际上，生产环境里很多诡异的超时、连接被重置、线程卡死问题，根因都在这个阶段配置得不合理。

3.1 HttpHost、超时与认证配置

最基础的初始化方式是这样：

java复制RestHighLevelClient client = new RestHighLevelClient(
    RestClient.builder(
        new HttpHost("es-node-1", 9200, "http"),
        new HttpHost("es-node-2", 9200, "http")
    )
);

但真实生产环境不可能这样裸配。至少要做三件事：设置请求超时、设置连接超时、设置认证信息。完整的初始化代码推荐这样写：

java复制RestClientBuilder builder = RestClient.builder(
    new HttpHost("es-node-1", 9200, "http"),
    new HttpHost("es-node-2", 9200, "http")
);

// 设置请求头，比如认证Token、User-Agent等
builder.setDefaultHeaders(new Header[]{
    new BasicHeader("Authorization", "Basic " + base64Credentials)
});

// 设置连接失败后是否重试
builder.setFailureListener(new RestClient.FailureListener() {
    @Override
    public void onFailure(Node node) {
        System.err.println("ES节点失败: " + node.getHost());
    }
});

// 设置连接超时、Socket超时、最大连接数等
builder.setRequestConfigCallback(requestConfigBuilder -> requestConfigBuilder
    .setConnectTimeout(5000)
    .setSocketTimeout(60000)
    .setConnectionRequestTimeout(0)
);

// 设置连接池参数
builder.setHttpClientConfigCallback(httpClientBuilder -> {
    httpClientBuilder.setMaxConnTotal(200);
    httpClientBuilder.setMaxConnPerRoute(100);
    httpClientBuilder.setKeepAliveStrategy((response, context) -> 60000);
    return httpClientBuilder;
});

RestHighLevelClient client = new RestHighLevelClient(builder);

这里每个参数都值得说一下。setConnectTimeout是建立TCP连接的超时时间，网络环境差或ES负载高时容易触发，建议设在3到5秒之间。setSocketTimeout是等待服务端响应的最大时间，搜索请求如果数据量大，60秒并不夸张。setConnectionRequestTimeout是从连接池获取连接的等待时间，默认-1表示无限等待，但在高并发场景下我建议显式设为0或一个较小值，这样当连接池被占满时不用傻等，而是快速抛出异常让上层感知。

3.2 客户端线程安全与连接池的坑

RestHighLevelClient是线程安全的，这点官方明确说了。一个应用全局维护一个单例客户端就够了，多个线程可以共享使用。实际项目中经常犯的错误是每次请求都new一个客户端，这会导致两个问题：一是大量TCP连接建立和销毁，拖慢请求；二是底层HttpClient连接池没有被复用，连接数直接打满。

我在一个项目里接手过一段代码，每次查询都初始化新Client，生产环境一旦并发量上来，机器端口立刻耗尽。后来改成Spring容器里注册一个单例Bean，启动时初始化一次，问题马上消失。记住：一个ES集群一个Client实例，用Spring管理生命周期即可。

连接池的另一个问题是KeepAlive。默认情况下，ES服务端的keepAlive是30秒，如果你客户端设置的Socket超时太长，连接空闲超过服务端keepAlive时间后，服务端会主动断开。此时客户端以为连接还在，下次发请求时会遇到Connection reset by peer。解决办法是自定义KeepAliveStrategy，把空闲连接存活时间调成与服务端一致或略短。

3.3 多集群与滚动升级场景

有的业务会同时连接多个ES集群。比如读写分离：写入走主集群，查询走读集群。这时候就需要维护两个Client实例。注意两个实例的配置可以不一样，比如读集群查询量大，连接数设置大一些；写集群吞吐高，SocketTimeout可以适当拉长。这样多实例配置是工程上很常见的做法，但也意味着你要格外注意关闭时的顺序，先停流量再关客户端，防止正在进行的请求被中断。

4. 索引与文档CRUD：从建索引到更新删除的完整链路

索引和文档操作是ES最基础的能力。RestHighLevelClient把这类操作都封装成了会话级别的API，使用上很直观。

4.1 索引操作与mapping管理

创建索引前，我会先检查索引是否存在，避免重复创建报错。检查索引是否存在可以通过IndicesClient实现：

java复制GetIndexRequest request = new GetIndexRequest("order");
boolean exists = client.indices().exists(request, RequestOptions.DEFAULT);

创建索引时如果对分词、排序有要求，需要设置settings和mapping。这里用CreateIndexRequest的mapping方法传入JSON字符串或Map，推荐放classpath下的JSON文件，方便维护：

java复制CreateIndexRequest createIndexRequest = new CreateIndexRequest("order");
createIndexRequest.settings(Settings.builder()
    .put("index.number_of_shards", 3)
    .put("index.number_of_replicas", 1)
    .put("index.refresh_interval", "5s")
);

// 从classpath读取mapping JSON
try (InputStream is = getClass().getResourceAsStream("/mapping/order_mapping.json")) {
    createIndexRequest.mapping(IOUtils.toString(is, StandardCharsets.UTF_8), XContentType.JSON);
}

CreateIndexResponse createIndexResponse = client.indices().create(createIndexRequest, RequestOptions.DEFAULT);

mapping里经常会遇到一个坑：某个字段既是text类型需要全文搜索，又需要精确匹配做排序或聚合。ES里不能直接用同一字段做两种操作，解决办法是为字段定义fields子字段，比如把orderName设为text，同时配置orderName.keyword为keyword类型。如果你在mapping里漏掉这点，后面排序或聚合会报Fielddata is disabled on text fields by default，这个报错很常见。

4.2 文档写入和获取

写入单条文档用IndexRequest：

java复制IndexRequest indexRequest = new IndexRequest("order")
    .id("order_20240101_001")
    .source("{\"orderNo\":\"NO123456\",\"amount\":99.9,\"status\":\"PAID\"}", XContentType.JSON);

IndexResponse indexResponse = client.index(indexRequest, RequestOptions.DEFAULT);

如果只有对象，可以通过Jackson转成Map，再用XContentType.JSON写入。写入响应里有result字段，值是CREATED或UPDATED，可以据此判断是新增还是覆盖。

按ID查询用GetRequest：

java复制GetRequest getRequest = new GetRequest("order", "order_20240101_001");
GetResponse getResponse = client.get(getRequest, RequestOptions.DEFAULT);
if (getResponse.isExists()) {
    String json = getResponse.getSourceAsString();
    // 用Jackson反序列化成业务对象
}

这里要注意，getResponse.getSource()返回的是Map，如果你在mapping里把_source禁用了，那这里返回就是null。虽然禁用_source能省存储，但很多业务场景需要原始文档，建议默认开启。

4.3 更新、删除与版本冲突

更新文档有几种方式。最简单的用法是传新的部分字段：

java复制UpdateRequest updateRequest = new UpdateRequest("order", "order_20240101_001")
    .doc("{\"status\":\"SHIPPED\"}", XContentType.JSON);
UpdateResponse updateResponse = client.update(updateRequest, RequestOptions.DEFAULT);

ES更新并不是原地改，而是先查后改，它会读取原文档，应用修改，再写回新文档。所以更新操作比普通索引操作开销更大。很多人误以为Update性能很高，其实不然，写多读少场景建议直接用IndexRequest全量覆盖。

更新时如果没有指定版本，ES会使用InternalVersion类型做乐观锁控制，基于_seq_no和_primary_term保证并发安全。如果想手动控制版本，可以这样：

java复制updateRequest.setIfSeqNo(2L);
updateRequest.setIfPrimaryTerm(1L);

当并发发起两个更新，后提交的请求如果带的是旧版本号，ES会抛出VersionConflictEngineException，业务代码里捕获这个异常做重试或提示即可。

删除文档是DeleteRequest，比较直接：

java复制DeleteRequest deleteRequest = new DeleteRequest("order", "order_20240101_001");
DeleteResponse deleteResponse = client.delete(deleteRequest, RequestOptions.DEFAULT);

另外，ES删除文档是逻辑删除，不会立刻从磁盘上抹掉，而是打上删除标记，等到合并segment时真正清理。所以删除操作本身很快，但频繁删除又大量写入会导致磁盘空间暂时膨胀。

4.4 _source过滤与stored字段

在实际查询中，一个文档可能有几十个字段，但业务只需要其中两三个。此时不应该每次都获取整个_source，而应该在GetRequest或SearchRequest里明确指定返回字段：

java复制GetRequest getRequest = new GetRequest("order", "order_20240101_001");
String[] includes = new String[]{"orderNo", "status", "amount"};
String[] excludes = new String[]{"internalRemark"};
getRequest.fetchSourceContext(new FetchSourceContext(true, includes, excludes));

这样可以显著减少网络传输和反序列化开销，请求大文档时收益很明显。

5. 搜索查询API：从简单查询到复合查询实战

搜索是业务开发用得最多的能力。RestHighLevelClient把ES的搜索DSL做了对象化封装，用SearchSourceBuilder和QueryBuilders组合各种条件。

5.1 搜索请求的基本结构

一个典型的搜索请求包含索引名、查询条件、分页、排序、source过滤等：

java复制SearchRequest searchRequest = new SearchRequest("order");
SearchSourceBuilder sourceBuilder = new SearchSourceBuilder();

// 查询条件：会员ID匹配 + 金额范围
BoolQueryBuilder boolQuery = QueryBuilders.boolQuery()
    .must(QueryBuilders.termQuery("memberId", 10086))
    .filter(QueryBuilders.rangeQuery("amount").gte(50).lte(500));

sourceBuilder.query(boolQuery);
sourceBuilder.from(0);
sourceBuilder.size(20);
sourceBuilder.sort("createTime", SortOrder.DESC);

// 只返回需要的字段
sourceBuilder.fetchSource(new String[]{"orderNo", "status", "amount"}, null);

searchRequest.source(sourceBuilder);
SearchResponse searchResponse = client.search(searchRequest, RequestOptions.DEFAULT);

5.2 QueryBuilders里细节最多的几个查询

termQuery用于精确匹配，它不会对搜索词分词，适合keyword类型或数字类型字段。这一点我在实际中经常确认：如果是text类型的字段，termQuery几乎查不到内容，因为它拿整个短语去倒排索引里匹配，而倒排索引里存的都是分词后的词项。

matchQuery则会对输入做分词，适用于全文检索场景。比如用户输入"高端连衣裙"，matchQuery会按分词器切成多个词，任何一个词命中就可能返回。如果希望所有词都要命中，可以设置operator(Operator.AND)。

rangeQuery用于范围查询，日期和数字都用它。有个很隐蔽的问题：当字段是date类型且查询时直接传字符串日期，ES默认解析为UTC时间，如果你在查询条件里传的是北京时间，会有8小时差。解决办法有两个，一是在mapping时指定时区，二是查询时调用timeZone(ZoneId.of("Asia/Shanghai"))明确时区。

wildcardQuery支持通配符，但性能很差，因为它无法利用倒排索引，必须全字段扫描。我的建议是：能不用尽量不用，如果必须用，加前缀限制，比如orderNo: NO*能减少扫描范围。这种情况在日志检索里比较常见，但量大的业务表一定慎用。

5.3 高亮与聚合

高亮是搜索引擎最常见的功能。RestHighLevelClient中的实现很直接：

java复制HighlightBuilder highlightBuilder = new HighlightBuilder();
highlightBuilder.field("title");
highlightBuilder.preTags("<em>");
highlightBuilder.postTags("</em>");
HighlightBuilder.Field highlightTitle = new HighlightBuilder.Field("title");
highlightTitle.highlighterType("unified");
highlightBuilder.field(highlightTitle);
sourceBuilder.highlighter(highlightBuilder);

响应解析时，从SearchHit的getHighlightFields()里取高亮片段。需要注意：如果source里不包含高亮字段，也没关系，高亮是从原始字段内容里单独处理的，只要字段是索引里存在的即可。

聚合是分析类需求的利器。比如按状态分组统计订单数：

java复制TermsAggregationBuilder aggregation = AggregationBuilders.terms("status_group")
    .field("status.keyword")
    .size(10);
sourceBuilder.aggregation(aggregation);

如果字段是text且没有keyword子字段，聚合会报错。这块我在前面提过，mapping设计时一定要提前考虑聚合需求。

5.4 深度分页：from/size、scroll与searchAfter

一般业务列表页用from/size就够了，但一旦页码深，比如到第1000页，ES就要在每个分片上取出from+size条数据再合并排序，这会导致内存和延迟都急剧上升。所以ES默认限制max_result_window为10000。

深度分页有几种替代方案。scroll适用于导出、大批量遍历，它通过生成快照游标持续拉取数据，但它是非实时快照，会有额外内存开销。searchAfter则适合实时深度分页，它通过上一页最后一条记录的排序值作为下一页起点，没有快照，性能好很多。

searchAfter的写法：

java复制SearchRequest searchRequest = new SearchRequest("order");
SearchSourceBuilder sourceBuilder = new SearchSourceBuilder();
sourceBuilder.query(QueryBuilders.termQuery("status", "PAID"));
sourceBuilder.size(100);
sourceBuilder.sort("amount", SortOrder.DESC);
sourceBuilder.sort("_id", SortOrder.ASC); // 需要唯一排序值避免丢失

SearchResponse response = client.search(searchRequest, RequestOptions.DEFAULT);

// 解析完当前页数据后，拿到最后一条hit的排序值
Object[] sortValues = response.getHits().getAt(response.getHits().getHits().length - 1).getSortValues();
// 下一页设置
sourceBuilder.searchAfter(sortValues);

这里面有个细节：如果只按一个字段排序且该字段值有重复，分页时可能丢数据，所以通常要加一个唯一性字段如_id做次级排序。

5.5 复杂查询建议

多个查询条件时不要无脑用must，能用filter的就用filter。因为must会影响相关性评分，需要额外计算分数，而filter只做过滤，不计算分，性能更好。实际业务里那些类别、状态、时间范围过滤，都不需要评分，用filter包起来会让查询快不少。

6. 批量操作与BulkProcessor：写入性能和内存的取舍

ES写入慢在单条请求的网络往返和数据解析上。如果场景是一次写入几千条数据，用单条IndexRequest挨个循环发，效率极低。正确姿势是批量提交。

6.1 手动构造BulkRequest

最简单的批量提交：

java复制BulkRequest bulkRequest = new BulkRequest();
for (Order order : orderList) {
    IndexRequest indexRequest = new IndexRequest("order")
        .id(order.getId())
        .source(JacksonUtil.toJson(order), XContentType.JSON);
    bulkRequest.add(indexRequest);
}
BulkResponse bulkResponse = client.bulk(bulkRequest, RequestOptions.DEFAULT);

批量请求要注意单次请求体大小。太小的批量（比如一次10条）不会带来明显收益，太大的批量（比如一次5万条）虽然请求次数少了，但构造BulkRequest时所有文档都在内存中，如果数据量大容易OOM，而且一次大请求ES端解析和索引压力也很大。我实测下来，1000到5000条一次是比较合理的区间。更精确的判断标准是看请求体大小，一个BulkRequest控制在5MB到15MB之间比较合适。

6.2 BulkProcessor：自动攒批的利器

如果你希望积攒够一定的条数或大小后自动提交，同时不阻塞业务线程，用BulkProcessor最合适。它有两种提交触发条件，攒够条数、攒够字节数或到达刷写间隔，任一触发都会执行提交。

java复制BulkProcessor bulkProcessor = BulkProcessor.builder(
    (request, bulkListener) -> client.bulkAsync(request, RequestOptions.DEFAULT, bulkListener),
    new BulkProcessor.Listener() {
        @Override
        public void beforeBulk(long executionId, BulkRequest request) {
            // 提交前回调，可以记录日志
        }

        @Override
        public void afterBulk(long executionId, BulkRequest request, BulkResponse response) {
            if (response.hasFailures()) {
                System.err.println("批量写入有失败: " + response.buildFailureMessage());
            }
        }

        @Override
        public void afterBulk(long executionId, BulkRequest request, Throwable failure) {
            // 这里要处理异常，最好做重试或日志告警
        }
    }
)
.setBulkActions(3000)      // 攒够3000条执行一次
.setBulkSize(new ByteSizeValue(10, ByteSizeUnit.MB)) // 攒够10MB执行一次
.setFlushInterval(TimeValue.timeValueSeconds(5))     // 每5秒刷新一次
.setConcurrentRequests(2)   // 并发提交请求数
.build();

BulkProcessor最容易被忽略的是concurrentRequests参数。它表示允许并发执行的异步请求数，如果设成0，表示每次提交都是同步等待。生产环境建议设置1到4之间。另外，使用完毕后必须在应用关闭前调用bulkProcessor.awaitClose(30, TimeUnit.SECONDS)，把积压的数据全部刷完，否则会丢数据。

6.3 批量写入的失败重试

即使批量提交，也必然存在个别文档失败的情况。BulkResponse里提供hasFailures()和buildFailureMessage()方法，可以定位具体失败项。一般失败原因可能是文档格式问题、版本冲突或分片处理失败，这些需要业务侧处理或重试。如果是网络超时或ES端繁忙，通常整体请求抛异常，这时候需要考虑指数退避重试。

我习惯在BulkProcessor的afterBulk异常回调里记录哪些批次失败，并将失败批次的消息体发到MQ，由另一个线程做补偿重试。这样整个写入链路不会因为批量失败而全部阻塞。

7. 异步客户端与线程模型：高并发下别让请求排队

RestHighLevelClient除了同步方法，也提供同等的异步方法，命名规则统一是方法名前加async。比如index对应indexAsync，search对应searchAsync，返回值是一个Cancellable对象，结果通过ActionListener回调通知。

java复制client.searchAsync(searchRequest, RequestOptions.DEFAULT, new ActionListener<SearchResponse>() {
    @Override
    public void onResponse(SearchResponse searchResponse) {
        // 处理结果
    }

    @Override
    public void onFailure(Exception e) {
        // 处理异常
    }
});

很多人误以为用了异步就一定能提升性能，其实关键在于调用线程是否被释放。同步请求会阻塞调用线程直到响应返回，异步请求则立即返回，底层通过回调在IO线程中处理结果。这对于Tomcat线程池是好事，因为大量请求等待ES响应时，同步方式会占用大量Tomcat线程，异步方式则不会。

异步请求的一个隐蔽坑是回调线程里的异常。如果你在onResponse回调里没有捕获异常，而这个回调线程是Netty的EventLoop线程，异常会直接导致该线程被污染，严重的会影响整个连接通道上的请求。所以异步回调里第一行就要加try-catch，哪怕只是打日志也一定要兜底。

另外，异步请求如果你不再需要结果了，可以使用返回的Cancellable对象调用cancel()取消请求。这在用户快速翻页或取消导出时很有用，能及时释放ES端资源。

线程模型上要注意的是，RestHighLevelClient底层使用Apache HttpClient，它有自己的连接管理器，同时Netty负责处理部分IO。默认情况下HttpClient会为每个路由创建最多2个连接，这就是我之前为什么强调要设置setMaxConnPerRoute。高并发下如果不调大连接数，很多请求会在连接池等待，表现为接口RT突然升高但CPU不高。

8. 踩坑记录：这半年遇到过的RestHighLevelClient问题

很多问题是运行一段时间后才暴露的，这里分享几个印象最深的案例，希望能帮你提前避坑。

8.1 连接池耗尽导致的雪崩

有一次线上服务突然大面积超时，排查发现ES集群本身负载不高。最后看日志，很多线程卡在PoolingHttpClientConnectionManager的requestConnection方法。原因是我们设置setMaxConnPerRoute(100)，但业务同时发起了远超100的并发查询，连接池被占满，后续请求都在等连接。修复方法有两个，一是提高连接数上限，二是给setConnectionRequestTimeout设一个较小值，比如300毫秒，快速失败而不是让请求无限等待。后来我把两者都做了，排队问题基本消失。

8.2 LocalDateTime序列化导致写入失败

有一次写入文档时抛异常，错误信息大致是Cannot construct instance of java.time.LocalDateTime。原因是我们把JodaTime或Java8时间字段直接放在业务对象里，默认Jackson序列化配置不识别。解决办法是在ObjectMapper上注册JavaTimeModule，并设置WRITE_DATES_AS_TIMESTAMPS为false，或者在写入前把时间字段统一转成格式化字符串。这个看起来是小问题，但一旦写入量大了，定位起来很费时间。

8.3 大批量查询size设置不当导致ES内存溢出

业务上曾经查一个月的订单量，直接设置size(50000)，结果ES返回Trying to create too many buckets或OOM。这其实是滥用from/size的典型后果。ES搜索的内存消耗是大概是分片数 * (from+size) * 文档大小，当数据分散在多个分片时，这个值是成倍增长的。后来改为scroll分批导出，一次10000条，内存占用大幅下降。

8.4 索引不存在时的响应处理

ES在查询不存在的索引时，不会返回404，而是返回一个空的搜索结果。但如果你用GetRequest去拿一条不存在的文档，它的isExists()是false。这里有个值得注意的地方：在调用getSourceAsString()之前一定要判断isExists()，否则会返回null，反序列化时空指针。这个坑很不起眼，但确实有人在生产代码里踩过。

8.5 幂等和非幂等操作混用

IndexRequest没有指定id时，ES会自动生成一个随机id，同样的内容写两次会产生两条文档。如果业务希望重复提交不产生重复数据，必须显式传id。这看起来是基本常识，但真实业务里因为遗漏id导致重复数据的问题相当常见。批量场景更是如此，每一条都要在循环里显式设置id。

9. RestHighLevelClient与新版Java API Client：现在该不该迁移

ES 8.x官方推出了新的Java API Client（即elasticsearch-java），和RestHighLevelClient最大的区别是基于Elasticsearch核心库的类型安全API，代码风格更现代，使用起来不需要拼凑Builder，同时它内置了JSON映射层，支持Jackson等序列化框架。

官方从8.0开始就不再为新功能更新RestHighLevelClient，只修复bug。如果你正在从零搭建新项目，且ES版本是8.x及以上，我推荐直接用新客户端。新客户端的API设计更符合现代Java习惯，方法名也更直观。

但如果你是维护存量项目，且ES集群是7.x版本，我的建议是保持RestHighLevelClient不动。原因很简单：迁移成本不只在于客户端API的替换，还包括mapping、索引模板、应用代码里所有查询逻辑的改写。如果项目已经运行稳定，没有必要为了追新而付出高昂回归测试成本。

如果未来确实要迁移，我的建议是分步走：先用新客户端和RestHighLevelClient同时对接ES，做好接口层封装，业务代码不直接依赖某个客户端的实现；然后逐步把查询逻辑迁移到新客户端，每个模块单独验证后再全部切换。不要尝试一次性替换，风险太大。

工具是为业务服务的，不是业务为工具服务。只要当前的客户端在你的场景下稳定可靠，不影响业务迭代，维持现状完全是合理选择。

最后分享一个我个人觉得很有用的习惯：在Spring Boot项目里，把所有ES客户端操作封装到一个独立的Dao层，业务代码只面向业务模型编程，不直接暴露Request和Response对象。这样未来不管是用RestHighLevelClient还是新客户端，替换成本都会低很多。另外，ES客户端的配置项，比如连接超时、连接池大小、批量Size、失败重试策略，全部放在配置文件里，运维同学调优时不用改代码，开发也能少背几个锅。