企业官网建设流程全解析

第一次用 Elasticsearch 做 Java 开发时，我在代码里干过不少蠢事——包括手工拼接 JSON 查询串，再通过 HTTP Client 发出去，结果一个转义符、一层嵌套括号，就能让我在生产环境里排查到半夜。后来彻底转向官方 Java API Client，项目的可维护性才真正拉起来。如果你正准备用 Java API 操作 Elasticsearch，或者已经在用但总觉得写法别扭，这篇就从依赖版本、连接初始化、索引管理、文档 CRUD、查询构建、聚合高亮、批量写入到生产环境排错，一条线完整走一遍，讲清楚每一步“为什么这么做”，也把我在实际项目中踩过的坑一起放出来。

本篇文章适合刚开始接触 Elasticsearch Java API 的读者，也适合已经跑通基础 Demo、却想在真实业务中把读写和查询做得更稳的同学。全文以 8.x 版本的官方 Java API Client 为主线，同时会提一下旧版 High Level REST Client 的区别，方便大家迁移时对照。

1. 从“在代码里拼 JSON”到真正把 Java API 用顺手

1.1 为什么字符串拼接查询这条路走不远

我见过不少项目，连 Elasticsearch 都没有引入官方 Java 客户端，而是自己封装了一个 HttpClient 工具，把查询 DSL 全部写成字符串模板，例如：

String json = "{\"query\":{\"match\":{\"title\":\"手机\"}}}";

这种写法在 Demo 阶段确实很爽，因为不用理解 API 结构，直接把 Kibana 里调试好的 JSON 抄进代码就行。但一进入真实业务，问题立刻暴露：

• 动态参数拼接容易出错。如果 title 的值来自用户输入，你需要处理引号转义；如果值来自变量，字符串模板一不小心就变成 SQL 注入式的结构破坏问题。
• 查询结构稍微复杂一点，比如 bool 里套 must、should、filter，再叠加 range、term、聚合，字符串拼接出来的代码几乎没法做逻辑校验。
• 后端接口改动一个字段名，IDE 重构完全帮不上忙，只能在运行时等报错。

真正用上 Elasticsearch 官方 Java API Client 之后，查询变成类型安全的对象构建。字段名写错了，编译期就能发现；参数类型不匹配，IDE 直接标红。这种体感变化，是手拼 JSON 永远给不了的。

1.2 新旧两代 Java 客户端，到底该用哪个

很多老项目里用的是 High Level REST Client（7.x 时代的主流客户端）。但如果你现在新起项目，建议直接选择官方 Java API Client，也就是带co.elastic.clients包名的那一套。

理由很简单：

• High Level REST Client 在 7.17 之后进入维护状态，官方明确不再为其增加新功能。
• 新客户端采用了更统一的构建器模式，所有请求对象都支持 DSL 式写法，和 Elasticsearch 的 REST API 结构一一对应。
• 新客户端在序列化、反序列化上更灵活，默认基于 Jackson，也支持自定义 JsonpMapper。

如果你正在维护老项目，短期内继续用 High Level REST Client 没问题，但新功能、新字段类型、新查询能力基本都只会先出现在新客户端上。越早迁移，后续成本越低。

2. 依赖层级与连接初始化：最容易翻车的第一道坎

2.1 引入依赖时的版本匹配问题

我第一次引入 Java API Client 时，直接踩了版本不匹配的坑。这里要记住一个核心原则：客户端的版本必须与 Elasticsearch 服务端主版本保持一致，小版本差距一般兼容，但不要跨大版本。

我目前用的是 Elasticsearch 8.11 集群，Maven 依赖如下：

<dependency> <groupId>co.elastic.clients</groupId> <artifactId>elasticsearch-java</artifactId> <version>8.11.0</version> </dependency> <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-databind</artifactId> <version>2.15.2</version> </dependency>

注意，elasticsearch-java这个包本身并不会把 Jackson 带进来，你需要显式引入一个 JSON 序列化实现。官方推荐的是 Jackson，所以jackson-databind必须要有。

如果只引入elasticsearch-java而忘记 Jackson，项目启动时通常不会立刻报错，但第一次发起请求就会抛出NoClassDefFoundError，指向JsonpMapper相关类。这个坑很隐蔽，建议在搭建工程时就把这两个依赖一起写上。

2.2 初始化客户端与连接生命周期

初始化整个客户端，市面上很多教程只给三行代码，但我要多说几句连接生命周期的事情。

RestClientBuilder builder = RestClient.builder( new HttpHost("localhost", 9200, "http") ); ElasticsearchTransport transport = new RestClientTransport(builder, new JacksonJsonpMapper()); ElasticsearchClient client = new ElasticsearchClient(transport);

这里有几个关键点：

• RestClientTransport是整个客户端的核心，它持有底层 HTTP 连接池。整个应用里应该只初始化一次，不要每次请求都 new 一个。
• 如果连接的是集群，可以传入多个HttpHost，客户端会自动做节点发现和故障转移。
• 生产环境建议开启连接池配置，通过RestClientBuilder设置连接超时、请求超时、最大连接数等参数。

举个例子，我在一个高并发服务里，曾经因为没有显式配置setHttpClientConfigCallback，默认连接池太小，导致高峰期出现大量连接等待。后来的配置大致是这样：

RestClientBuilder builder = RestClient.builder( new HttpHost("es-node-1", 9200, "http"), new HttpHost("es-node-2", 9200, "http") ).setRequestConfigCallback(config -> config .setConnectTimeout(5000) .setSocketTimeout(60000) );

超时时间要结合业务场景调整。查询类接口可以设置 10 到 30 秒，但写入类接口不要设置太短，因为批量写入在高峰期可能排队。

2.3 Transport 与 JsonpMapper 的作用

很多人不理解为什么新客户端要单独拆一个Transport层。我的理解是：Elasticsearch 官方希望把“HTTP 通信”和“JSON 映射”解耦，以便未来可以替换不同的 JSON 框架，甚至替换传输层协议。

JsonpMapper决定了 Java 对象如何序列化成 JSON。默认的JacksonJsonpMapper使用 Jackson 的注解和 ObjectMapper，所以你完全可以用@JsonProperty来定制字段名映射。

有一个非常重要的经验：如果你在索引文档时返回 400 错误，报错信息里提到Unknown key for a START_OBJECT，十有八九是 Java Bean 里的字段名和索引 mapping 里的字段名对不上。比如索引里字段叫user_name，Java 类里叫username，中间没有加@JsonProperty("user_name")，序列化出来的 JSON 就会多出字段或者缺失字段。

我一般会定义一个统一的配置：

ObjectMapper mapper = new ObjectMapper(); mapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false); JacksonJsonpMapper jsonpMapper = new JacksonJsonpMapper(mapper);

FAIL_ON_UNKNOWN_PROPERTIES设为 false 之后，读取文档时如果返回结果里有 Java 类未定义的字段，不会报反序列化错误。这个配置在索引结构经常调整的项目里非常实用。

3. 索引与映射：显式管理才是正确姿势

3.1 创建索引前先做存在性检查

很多初学者写完第一版程序，就直接client.indices().create()创建索引。结果第二次运行时报错，因为索引已经存在。这个错误本身不可怕，但反映了写法上的坏习惯：Elasticsearch 的索引生命周期管理，应该像数据库表结构一样被显式管理。

我的习惯是封装一个初始化方法，启动时检查所有关键索引是否存在：

boolean exists = client.indices().exists(e -> e.index("products")).value(); if (!exists) { client.indices().create(c -> c.index("products")); }

indices().exists()返回的是一个BooleanResponse，取出.value()得到布尔值。这样每次服务重启，索引初始化逻辑都是幂等的，不会因为重复创建而中断。

3.2 映射设置：分析器和字段类型别靠猜

如果你不显式设置 mapping，Elasticsearch 会为每个字段自动推断类型。开发环境下这很方便，但生产环境里自动推断经常出问题。最典型的是：一个本该是keyword的订单号字段，因为第一个文档里值是数字，被推断成long类型，后续带有字母前缀的订单号根本无法写入。

所以创建索引时，一定要显式定义 mapping：

client.indices().create(c -> c .index("products") .mappings(m -> m .properties("id", p -> p.keyword(k -> k)) .properties("title", p -> p.text(t -> t.analyzer("ik_max_word"))) .properties("price", p -> p.double_(d -> d)) .properties("stock", p -> p.integer(i -> i)) .properties("category", p -> p.keyword(k -> k)) .properties("created_at", p -> p.date(d -> d.format("yyyy-MM-dd HH:mm:ss"))) ) );

关于 text 和 keyword 的选择，我用一个通俗的类比：

• keyword就像数据库里的精确字段，适合排序、聚合、精确匹配。
• text是全文检索字段，适合模糊搜索，但默认不能直接做排序聚合。

如果业务上既需要模糊搜索，又需要按标题聚合，可以在 mapping 里同时定义text字段和一个keyword子字段，类似：

.properties("title", p -> p.text(t -> t .analyzer("ik_max_word") .fields("raw", f -> f.keyword(k -> k)) ))

这样查询时可以用title做全文匹配，聚合排序时用title.raw，互不干扰。

3.3 索引设置与分片数量规划

创建索引时，我会在创建步骤里顺带设置分片数和副本数：

client.indices().create(c -> c .index("products") .settings(s -> s .numberOfShards("3") .numberOfReplicas("1") ) .mappings(m -> m.properties(...)) );

分片数量在索引创建后是可以调整的，但调整需要走_split或_shrinkAPI，过程麻烦。所以创建之初就应该估算数据量。

我通常的参考标准是：每个分片的数据量控制在 20GB 到 50GB 之间。比如预计一年数据 100GB，设置 3 到 5 个分片比较合适。副本数至少 1，否则节点宕机时数据就丢了。

4. 文档 CRUD 操作：写入、读取、更新、删除的完整套路

4.1 写入数据的两种方式和版本冲突

写入单条文档，最简单的方式是用document直接传 Java 对象：

Product product = new Product(); product.setId("p001"); product.setTitle("无线蓝牙耳机"); product.setPrice(299.0); product.setStock(50); product.setCategory("数码"); IndexResponse response = client.index(i -> i .index("products") .id(product.getId()) .document(product) );

这里有一个隐含行为：如果id对应的文档已存在，默认会覆盖更新，并且_version会递增。如果你希望在版本冲突时不盲目覆盖，可以基于外部版本号或ifSeqNo/ifPrimaryTerm做乐观锁控制。

比如读取文档后，把响应的seqNo和primaryTerm拿出来，更新时带上：

GetResponse<Product> getResp = client.get(g -> g.index("products").id("p001"), Product.class); IndexResponse updateResp = client.index(i -> i .index("products") .id("p001") .document(product) .ifSeqNo(getResp.seqNo()) .ifPrimaryTerm(getResp.primaryTerm()) );

如果文档在读取后被其他请求修改过，这次写入会因为版本不匹配直接返回 409 冲突错误。这个机制非常适合处理并发更新同一个文档的业务场景。

4.2 读取文档时的反序列化细节

读取单条文档直接用到getAPI，第二个参数传目标类型：

GetResponse<Product> resp = client.get(g -> g .index("products") .id("p001"), Product.class ); if (resp.found()) { Product product = resp.source(); }

需要注意的一点是，resp.source()只有在found()为 true 时才非空。如果文档不存在，直接调用source()会得到 null，后续操作容易引发空指针。

我在封装查询工具类时，会把这一步包装成 Optional：

public Optional<Product> getProduct(String id) { GetResponse<Product> resp = client.get(g -> g.index("products").id(id), Product.class); return resp.found() ? Optional.ofNullable(resp.source()) : Optional.empty(); }

这样调用方不需要关心文档是否存在，直接用orElseThrow或者ifPresent处理即可。

4.3 更新与删除的注意事项

更新文档有两种常见思路。第一种是整体替换，也就是用index传入新对象，简单直接。第二种是局部更新，用updateAPI 只更新指定字段：

client.update(u -> u .index("products") .id("p001") .doc(Map.of("stock", 45)), Product.class );

这里值得注意的是：update里传的doc会执行一次“字段级合并”，而不是全量替换。好处是并发下更安全，坏处是如果字段值是需要计算后再写入的逻辑，比如stock = stock - 1，直接传固定值会有并发超卖问题。

这种场景我会改用脚本：

client.update(u -> u .index("products") .id("p001") .script(s -> s .inline(i -> i .lang("painless") .source("ctx._source.stock -= 1") ) ), Product.class );

删除文档相对简单：

DeleteResponse resp = client.delete(d -> d.index("products").id("p001"));

但有一个细节：删除操作默认是准实时的，也就是说删除后立刻再按 id 查询，可能还能查到旧数据，需要等一小段时间。如果你的业务要求删除后立即可见，需要显式设置refresh策略为Refresh.WaitFor：

client.delete(d -> d .index("products") .id("p001") .refresh(Refresh.WaitFor) );

这个操作会让删除请求等待刷新完成才返回，延迟会增加，但一致性更强。具体用不用，取决于业务对实时性的要求。

5. 查询构建：从 Match 到复合 BoolQuery

5.1 单层查询与排序分页

Elasticsearch 的查询构建逻辑，我一直用一个通俗类比来理解：match是“模糊找”，term是“精确找”，bool是“组合找”。

最基础的分页排序查询是这样：

SearchResponse<Product> resp = client.search(s -> s .index("products") .query(q -> q .match(m -> m.field("title").query("蓝牙耳机")) ) .sort(sort -> sort .field(f -> f.field("price").order(SortOrder.Asc)) ) .from(0) .size(20), Product.class );

这里有两个常见误区：

• from + size做深度分页非常不推荐。当from超过一万条，Elasticsearch 默认直接拒绝这种查询。业务上要翻页翻得很深时，应该用search_after或scroll。我在实际操作中，移动端列表接口通常用search_after，因为需要缓存sort值才能翻页，协议上稍复杂，但对集群压力小得多。
• size不要一次拉几万条数据。很多人会用size全量导出，这种方式对集群内存冲击很大。全量导出场景应该走scrollAPI 或者间检查全量导出是否能分批完成。

5.2 BoolQuery 的组合逻辑，把复杂条件拆开写

真实业务里很少只有一个查询条件。最常见的做法是包裹一层bool，把多个条件按语义拆成must、should、filter。我的经验是，filter里的条件不计分，查询性能比must更好。

举个实际例子，查询“标题包含蓝牙耳机、分类属于数码、价格在 200 到 500 之间、库存大于 0”的商品：

SearchResponse<Product> resp = client.search(s -> s .index("products") .query(q -> q .bool(b -> b .must(m -> m.match(t -> t.field("title").query("蓝牙耳机"))) .filter(f -> f.term(t -> t.field("category").value("数码"))) .filter(f -> f.range(r -> r .number(n -> n .field("price") .gte(200.0) .lte(500.0) ) )) .filter(f -> f.range(r -> r .number(n -> n .field("stock") .gt(0) ) )) ) ) .sort(sort -> sort.field(f -> f.field("price").order(SortOrder.Asc))) .from(0) .size(20), Product.class );

注意一个细节：filter里连续调用多个filter(...)是可以的，它会自动组合成一个布尔数组，不需要手动嵌套。

must里多个条件都用match时，默认是 AND 关系还是 OR 关系？这是非常容易混淆的点。在 BoolQuery 中，must表示“必须全部满足”，所以多个must之间是 AND。如果你想实现 OR，就得放到should里，并且配合minimumShouldMatch来控制最少命中几个条件。

.bool(b -> b .should(s1 -> s1.match(m -> m.field("title").query("耳机"))) .should(s2 -> s2.match(m -> m.field("description").query("耳机"))) .minimumShouldMatch(1) )

这段代码表示标题或者描述任一字段能匹配“耳机”即可。

5.3 查询结果里你需要关心哪些东西

SearchResponse里最常用的几个部分：

• hits().total()返回总命中数，注意在 8.x 里它是一个TotalHits对象，需要区分relation是Eq还是Gte。当命中数超过阈值时，ES 可能只返回近似值。
• hits().hits()是命中文档列表，每个Hit里通过.source()拿到反序列化后的 Java 对象。
• aggregations()聚合结果，后面单独讲。

还有一个小技巧，如果你只需要返回文档的某几个字段，可以在查询上使用source过滤，减少传输数据量：

.source(s -> s .filter(f -> f .includes("id", "title", "price") ) )

这在列表页接口里很实用，不用把整个文档内容都拉回应用层。

6. 聚合分析、高亮显示与批量写入，进阶操作一次说清

6.1 聚合分析：从写死循环改成对象嵌套

聚合是 Elasticsearch 的一大核心能力，但很多 Java 开发者在代码里引用聚合结果时非常痛苦。其实新客户端的聚合语法把嵌套关系表达得很清晰。

举个例子，按分类统计每个分类的商品数量，并计算每个分类的平均价格：

SearchResponse<Void> resp = client.search(s -> s .index("products") .size(0) .aggregations("by_category", agg -> agg .terms(t -> t.field("category").size(10)) .aggregations("avg_price", avg -> avg .average(a -> a.field("price")) ) ), Void.class );

注意这里我用了Void.class作为目标类型，因为我们只关心聚合结果，不需要反序列化文档数据。

取出结果的写法：

Aggregation categoryAgg = resp.aggregations().get("by_category"); List<KeyedBucket> buckets = categoryAgg.sterms().buckets().array(); for (KeyedBucket bucket : buckets) { String category = bucket.key().stringValue(); long count = bucket.docCount(); double avgPrice = bucket.aggregations() .get("avg_price") .avg() .value(); System.out.println(category + ": " + count + " items, avg price = " + avgPrice); }

这里的KeyedBucket对象是官方客户端对聚合 bucket 的封装，层级结构非常直观。bucket.aggregations()拿到的又是一个Aggregation对象，继续往下取子聚合即可。

这个写法对比起早期版本里手写Buckets解析，已经舒服太多了。

6.2 高亮显示：搜索词命中片段怎么取出来

做全文搜索站点时，高亮几乎是标配。Java API Client 里构建高亮也很直接：

SearchResponse<Product> resp = client.search(s -> s .index("products") .query(q -> q.match(m -> m.field("title").query("蓝牙耳机"))) .highlight(h -> h .fields("title", f -> f .preTags("<em>") .postTags("</em>") ) ), Product.class );

取高亮片段时需要注意，Hit对象里的highlight()返回的是Map<String, List<String>>，键是字段名，值是高亮片段列表：

for (Hit<Product> hit : resp.hits().hits()) { List<String> snippets = hit.highlight().getOrDefault("title", List.of()); String highlighterText = snippets.isEmpty() ? "" : snippets.get(0); System.out.println(highlighterText); }

这里有个实际经验：高亮默认只在匹配到的字段上生效，如果你要针对全文检索字段高亮，但展示的是另一个字段，那么需要在查询里把两个字段都加入搜索词匹配，或者在 mapping 中使用copy_to把多个字段复制到一个组合字段里，再对这个组合字段做高亮。

另外，高亮的默认片段大小，对于短文本没问题，长文本建议显式设置numberOfFragments和fragmentSize，否则可能返回一堆碎片。我一般设置fragmentSize(100)、numberOfFragments(1)，展示时更干净。

6.3 批量操作 Bulk API：数据写入效率的关键

单条索引文档在批量导入场景下效率很低。每一条索引请求都要走一次完整的 HTTP 往返，集群还要逐个处理。正确做法是用bulkAPI 一次处理大量请求。

BulkRequest.Builder br = new BulkRequest.Builder(); for (Order order : orderList) { br.operations(op -> op .index(idx -> idx .index("orders") .id(order.getId()) .document(order) ) ); } BulkResponse response = client.bulk(br.build());

批量写入的核心调优点是“一批多大”。我的经验是：

• 条数维度控制在 1000 到 5000 条左右，不要盲目追求条数大。
• 数据量维度控制在 5MB 到 15MB 之间，这个范围对集群内存和 HTTP 传输都比较友好。
• 如果批量里有部分文档失败，BulkResponse里会有items()数组，需要逐个检查是否有 error。我通常只把失败的 id 收集起来打日志，然后重试一次，不要让整个任务失败。

批量请求中偶尔也会出现节点内存压力过大、返回429或者EsRejectedExecutionException。这种情况下不要以更快的速度重试，而应该退避一定时间后再重试。可以把批量提交的逻辑包在一个带重试的工具类里，设置最大重试次数和指数退避间隔。

7. 生产环境踩坑实录：那些文档里不会写的事

7.1 深度分页与搜索性能

生产环境最常见的问题之一，就是有人把from设成几万来翻页。Elasticsearch 之所以默认限制from + size不能超过一万，是因为每次查询都要把所有命中文档收集到内存里排序，深度分页的代价呈线性甚至更糟地增长。

我有一次接手一个后台管理列表接口，用户筛选条件命中 20 万条数据，前几页还正常，翻到 200 页之后接口直接超时。当时临时方案是改成search_after：

SearchResponse<Product> firstPage = client.search(s -> s .index("products") .query(q -> q.matchAll()) .sort(sort -> sort.field(f -> f.field("created_at").order(SortOrder.Desc))) .size(50), Product.class ); List<Object> lastSort = firstPage.hits().hits().get(0).sort(); // 需要保存上一页最后一个文档的 sort 值 SearchResponse<Product> nextPage = client.search(s -> s .index("products") .query(q -> q.matchAll()) .sort(sort -> sort.field(f -> f.field("created_at").order(SortOrder.Desc))) .searchAfter(lastSort) .size(50), Product.class );

search_after使用上一页最后一个文档的排序值作为锚点，翻页再多也只扫描必要的数据。代价是翻页不能直接跳转，只能一页一页往下翻，但大多数业务场景都能接受。

7.2 连接池耗尽与超时配置

Elasticsearch Java 客户端底层依赖 Apache HttpClient。默认连接池的配置往往不适合高并发场景。

我遇到过一个问题：服务上有多个定时任务同时往 Elasticsearch 写入数据，连接数是 100，高峰期一过，大量线程阻塞在获取连接上，整个接口响应时间从 50ms 暴涨到 5 秒。最后排查发现就是连接池配置没有调大。

当时把配置改成这样：

RestClientBuilder builder = RestClient.builder( new HttpHost("es-node-1", 9200, "http") ).setHttpClientConfigCallback(httpClient -> httpClient.setMaxConnTotal(200) .setMaxConnPerRoute(100) );

同时，写入任务之间增加信号量控制并发数，避免所有任务一窝蜂发起批量请求。

这里要强调一点：连接池调大不是万能的，如果你批量请求太大、太频繁，集群本身先瓶颈了，客户端连接池再大也只是在队列里堆积。应该先监控集群 CPU、内存、磁盘 IO 和线程池队列，再决定调什么。

7.3 refresh 与查询实时性

Elasticsearch 的写入不是立即可见的。默认refresh_interval是 1 秒，意味着写入之后最多等 1 秒才能被查询到。如果业务上要求写入后立刻能查到，大家的第一反应可能是把refresh设成true。但这里有个很大的陷阱：频繁 refresh 会生成大量小分段，导致段合并压力剧增。

我的建议是：

• 绝大多数业务场景，默认 1 秒刷新已经够了。
• 如果确实需要即时可见，比如订单支付后立刻查询订单状态，可以在写入请求上单独设置refresh(Refresh.WaitFor)，而不是全局调低refresh_interval。
• 如果是批量导入场景，反而建议把refresh_interval临时调成-1（禁止刷新），导入完成后再恢复。这样导入速度能快很多。

我做过一个对比测试：10 万条数据批量导入，默认刷新间隔下耗时大约 80 秒；把刷新间隔临时设为-1，导入后手动刷新，整体耗时能降到 20 秒左右，差距非常明显。

7.4 字段类型不可变更的教训

最后分享一个在真实项目里改了很久的坑。某次需求里，商品原价字段一开始是double类型，后来因为要做精确金额匹配，需要改为keyword类型。结果 Elasticsearch 直接拒绝写入，因为字段类型创建后就不能直接修改。

解决办法只有一个：新建一个索引，用新 mapping 重新导数据，再用 alias 切换线上索引。这和教育系统里“改表结构要重建表再倒数据”是一个道理。

现在我在设计索引时，会尽量把字段类型一次性定义清楚。特别是那些可能既要做范围查询、又要做精确匹配、还要做排序的字段，我会在 mapping 里同时定义keyword子字段和double字段，而不是依赖后续变更。

写在最后的一点个人体会

从刚开始在代码里拼 JSON，到后来把所有 Elasticsearch 操作收敛到统一的 Repository 封装层，我最大的体会是：Java API Client 的价值远不止于“少写几行字符串”，它逼着你把索引结构、查询逻辑、序列化规则都想清楚，最终带来的是一套可维护、可测试的数据访问层。

如果你正在做类似的项目，我建议按这样的顺序推进：先搭好依赖和连接，再建索引和 mapping，接着跑通 CRUD，然后才是查询和聚合。不要一上来就写复杂查询，否则出了问题很难判断是客户端封装问题、查询逻辑问题还是索引数据问题。

最后给个小技巧：每当索引 mapping 调整、或者客户端版本升级时，先写一个冒烟测试类，把“创建索引、写入文档、查询文档、删除文档”完整跑一遍，再往外扩展业务代码。这个小习惯帮我在后面好几次版本升级中省下了大量的排错时间。