简介：面向需要将Spring Boot应用接入Elasticsearch 7.2.0的Java开发人员，这份PDF文档围绕版本兼容痛点，系统讲解从Spring Boot 2.1.X默认依赖与ES版本错配，到改采Spring-data-elasticsearch与RestHighLevelClient的完整实现思路。文章对比了传输层（transport）与REST两种连接方式，说明官方推荐及后续废弃策略，并给出依赖坐标、application.yml配置及客户端连接类等关键代码，其中也包含连接超时与请求超时等参数设置细节。文档中的配置类示例清晰展示了RestHighLevelClient的初始化过程，能帮助减少调试连接问题的时间。这份资料可帮助开发者避开版本对应关系不一致的常见坑，为日志检索、全文搜索、站内搜索等场景快速搭建可用的Elasticsearch客户端环境，也适合在学习搜索引擎集成或项目升级时作为速查参考。压缩包仅含1个PDF文档，体积约58KB，内容聚焦无冗余，便于移动端阅读；目前已有6768人学习下载。
1. 整合 Elasticsearch 7.2.0 为什么是 springboot 项目里最容易被版本坑一环
搜索引擎这块，Elasticsearch 在 7.2.0 这个版本上其实是个分水岭：6.x 时代常用的 TransportClient 在 7.0 被标记废弃，8.0 直接移除；同时 Spring Data Elasticsearch 的版本对应关系又极其挑剔，SpringBoot 2.1.x 对应 ES 7.x 早期版本，SpringBoot 2.2.x 对应 7.6，中间错一个版本，启动时要么连不上、要么序列化直接抛异常。很多人从网上拷贝一段依赖就开干，结果卡在版本兼容上长达一天，这是整个 springboot 整合 Elasticsearch 7.2.0 的过程里最消耗人耐心的一关。
这篇文章定位很明确：用 SpringBoot 把 Elasticsearch 7.2.0 跑通、跑稳，并覆盖写接口、查接口、分页、高亮、聚合、批量写入和索引重建。读者如果是第一次做 ES 整合，跟着章节顺序搭环境即可；如果已经跑通但查询性能不理想或者老遇到列名映射问题，直接跳到第 5 章和第 6 章，那里的参数和场景对照表能省下不少排查时间。
2. 整合前先做对选择题：版本对应、依赖坐标和两条路线
2.1 SpringBoot 与 ES 7.2.0 的版本硬对应关系
Spring Data Elasticsearch 的版本号不会和 Elasticsearch 完全对齐，它通过内部一套映射关系来适配。常见的版本对应如下表，这也是排查报错时第一份需要对照的清单：
| SpringBoot 版本 | Spring Data Elasticsearch 版本 | 兼容的 ES 版本 |
|---|---|---|
| 2.1.x | 3.2.x | ES 7.2.0 可用 |
| 2.2.x | 3.3.x | ES 7.6+ 首选 |
| 2.3.x | 4.0.x | ES 7.6+ |
| 2.4.x | 4.1.x | ES 7.9+ |
要做 ES 7.2.0，最稳的组合是 SpringBoot 2.1.x 或手动锁定 spring-data-elasticsearch 3.2.x 坐标。如果项目已经被迫使用 SpringBoot 2.2 或更高版本，你依然可以把 ES 版本固定在 7.2.0，前提是不要使用 Spring Data 自动装配的 TransportClient，完全转向 RestHighLevelClient。我一般会先跑一个最小启动类，确认 Spring Data ES 版本确实被解析到了预期版本，再往下推进业务代码。这个做法很笨，却能过滤掉大量后续的“找到一个坑，修一个坑”的无谓消耗。
2.2 两条整合路线：RestHighLevelClient 与 Spring Data Elasticsearch 的取舍
SpringBoot 整合 ES 7.2.0 常见有两条路线。一条是 Spring Data Elasticsearch 的 Repository 风格，适合纯粹的增删改查与简单条件查询。它的优点是无需手写查询 DSL，甚至不需要自己 new RestHighLevelClient，框架自动帮你注入 ElasticsearchRestTemplate。缺点也很明显——一旦需要复杂 bool 嵌套、聚合桶、高亮解析，Spring Data 的抽象会变得很绕，生成的查询也未必符合预期，性能问题一旦出现，排查难度反而上升。
另一条路线是原生 RestHighLevelClient。它是 ES 官方 Java 客户端，语义与 REST API 一一对应，查询 JSON 怎么写，代码就怎么写，逻辑完全透明。代价是一切都要自己搭：连接配置、索引初始化、查询响应解析、分页逻辑，没有自动实体映射。综合来看，推荐做法是：CRUD 用 Spring Data 提速，复杂检索用 RestHighLevelClient 兜底。两种方式共存于同一个项目没有任何冲突，这也是我目前在多数 springboot 项目里采用的标准结构。
2.3 在 pom.xml 里正确引入依赖坐标
以 SpringBoot 2.1.5.RELEASE 为例子，以下是同时支持两条路线的依赖配置：
<parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>2.1.5.RELEASE</version> </parent> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-data-elasticsearch</artifactId> </dependency> <dependency> <groupId>org.elasticsearch.client</groupId> <artifactId>elasticsearch-rest-high-level-client</artifactId> <version>7.2.0</version> </dependency> <dependency> <groupId>org.elasticsearch</groupId> <artifactId>elasticsearch</artifactId> <version>7.2.0</version> </dependency> <dependency> <groupId>com.alibaba</groupId> <artifactId>fastjson</artifactId> <version>1.2.83</version> </dependency> </dependencies>spring-boot-starter-data-elasticsearch 这个 starter 会自动引入一个 Spring Data ES 版本，它很可能不是你想要的 3.2.x。此时最直接的做法是在 properties 节点中强制锁定版本号：
<properties> <spring-data-elasticsearch.version>3.2.0.RELEASE</spring-data-elasticsearch.version> </properties>另外，elasticsearch-rest-high-level-client 与 elasticsearch 两个坐标的版本必须保持一致，否则运行时会报 Jackson 序列化层面的 NoClassDefFoundError。fastjson 不是必须的，但在做批量写入时能把实体序列化成 JSON 字符串，代码量会少很多，推荐引入。
3. 用 Spring Data Elasticsearch 快速跑通第一个索引和 CRUD
3.1 在 application.yml 里配置连接参数
Spring Data Elasticsearch 在 SpringBoot 2.1.x 使用的是 spring.data.elasticsearch 前缀，而不是有些老博客里提到的 spring.elasticsearch。这个前缀写错，应用能启动，但 ES 连接永远是 localhost:9300，然后报连接超时。
spring: data: elasticsearch: cluster-name: docker-cluster cluster-nodes: 192.168.1.10:9300 repositories: enabled: true注意，这里配置的是 9300 端口，这是 TransportClient 的端口。Spring Data ES 3.2.x 在 SpringBoot 2.1.x 下确实默认走 TransportClient，所以如果你没有在依赖中接入 RestHighLevelClient 的话，会面临 ES 7.2.0 已经不推荐 TransportClient 的问题。为了避免把时间浪费在废弃客户端上，我一般不会只配这个 yml，还会配合手动注入 RestHighLevelClient 来使用 RestClient 风格的连接，并配置 9200 端口：
@Configuration public class EsRestClientConfig { @Value("${elasticsearch.host:127.0.0.1}") private String host; @Value("${elasticsearch.port:9200}") private Integer port; @Bean(destroyMethod = "close") public RestHighLevelClient restHighLevelClient() { return new RestHighLevelClient( RestClient.builder(new HttpHost(host, port, "http")) ); } }两个配置并存不会冲突：Spring Data 负责实体映射和 Repository，RestHighLevelClient 负责手动查询。注意新版高版本客户端在建立连接时如果 ES 端没有开 http，也就是默认的 9200 端口没有监听，那么所有调用都会报 Connection refused。
3.2 定义实体类与索引映射
ES 7.x 中 type 概念已经弱化，Spring Data ES 3.2.x 默认索引类型为 _doc。实体类写法如下：
@Document(indexName = "product", shards = 3, replicas = 1) public class Product { @Id private String id; @Field(type = FieldType.Text, analyzer = "ik_max_word") private String name; @Field(type = FieldType.Keyword) private String brand; @Field(type = FieldType.Double) private Double price; @Field(type = FieldType.Date) private Date createTime; // getter setter 省略 }@Document 指定索引名。shards 与 replicas 在索引首次创建时生效，之后修改需要走索引重建。@Field 里的 analyzer 指定了中文分词器，这里用 ik_max_word 是常见做法，前提是 ES 端已安装 IK 分词插件，否则索引创建时会直接报错。price 用 Double 是因为 ES 7.2.0 对数值类型默认不支持 float 与 double 做精确匹配，除非在 mapping 中单独声明为 keyword。
首次启动项目时，Spring Data 会依据实体自动创建索引。这个行为由 spring.data.elasticsearch.repositories.enabled 控制，但索引结构一旦创建，后面修改字段类型不会自动更新，这属于 ES 的常见限制，需要走重建索引流程，这块偏后边第 6 章我再细说。
3.3 使用 Repository 实现增删改查
定义接口继承 ElasticsearchRepository，泛型第一个参数是实体类，第二个是主键类型：
public interface ProductRepository extends ElasticsearchRepository<Product, String> { List<Product> findByName(String name); List<Product> findByNameAndBrand(String name, String brand); Page<Product> findByPriceBetween(Double min, Double max, Pageable pageable); @Query("{\"bool\": {\"must\": [{\"match\": {\"name\": \"?0\"}}]}}") Page<Product> searchByName(String name, Pageable pageable); }ElasticsearchRepository 内置了 save、findById、findAll、deleteById 等基础方法，无需额外实现。方法命名规则与 Spring Data JPA 非常相似，支持 And、Or、Between、Like 等关键字，框架会自动生成查询 DSL。上述代码里的 findByPriceBetween 返回 Page，配合 PageRequest.of(0, 10) 就能实现带分页的区间查询。
@Query 注解适合手动编写 JSON 查询语句，?0 表示第一个参数占位符。在开发阶段我个人比较推荐对 core 查询用 @Query 明确定义 DSL，因为一旦实体字段多，方法名自动生成的查询语义会变得难以确认，而手写 JSON 字段与 ES 返回结构一致，参数好不好排查一眼就能看出来。
@Service public class ProductService { @Resource private ProductRepository productRepository; public Product save(Product product) { return productRepository.save(product); } public void delete(String id) { productRepository.deleteById(id); } public Page<Product> search(String name, int page, int size) { return productRepository.findByName(name, PageRequest.of(page, size)); } }这种写法的缺点是隔离性不好，如果查询条件一变，比如动态拼接多个 should、must，Repository 的方法签名会变得难以维护。所以接下来第 4 章是你在实际项目中真正要被考验的部分——复杂查询。
4. 用 RestHighLevelClient 构建复杂检索：bool 组合、高亮与分页
4.1 为什么复杂场景必须回到 RestHighLevelClient
Spring Data 的方法名推导，遇到超过两个条件就已显得生硬；如果条件里还有 should、filter、range 的混排，方法名越长越难读，生成的 DSL 也难以预料。RestHighLevelClient 完全规避了这个问题：查询怎么写，代码就是什么结构。它还支持异步调用与 scroll 滚动查询，适合大数据量导出。
初始化方式已在第 2 章写了配置类，这里直接把 client 注入到 Service 使用：
@Service public class ProductSearchService { @Resource private RestHighLevelClient client; public List<Product> searchByCondition(SearchCondition condition) throws IOException { SearchRequest searchRequest = new SearchRequest("product"); SearchSourceBuilder sourceBuilder = new SearchSourceBuilder(); BoolQueryBuilder boolQuery = QueryBuilders.boolQuery(); boolQuery.must(QueryBuilders.matchQuery("name", condition.getName())); boolQuery.filter(QueryBuilders.termQuery("brand", condition.getBrand())); boolQuery.filter(QueryBuilders.rangeQuery("price").gte(condition.getMinPrice())); sourceBuilder.query(boolQuery); sourceBuilder.from(condition.getPage() * condition.getSize()); sourceBuilder.size(condition.getSize()); searchRequest.source(sourceBuilder); SearchResponse response = client.search(searchRequest, RequestOptions.DEFAULT); return parseResponse(response); } }BoolQueryBuilder 是 7.2.0 中组合查询的核心入口。must 对应 AND 语义，must 里的 match 查询会做分词匹配。这里品牌用的是 termQuery，因为品牌在实体里声明为了 keyword，不分词，用 term 才能精确匹配。filter 与 must 的区别在于 filter 不计算相关度分数，查询速度更快，且可以被 ES 缓存。所以范围过滤、状态过滤等不影响排序的硬性条件，建议一律放入 filter 中。
4.2 同时返回关键词高亮片段
搜索引擎场景有一个高频需求：搜索命中的关键词需要在前端标红展示。ES 高亮原理是在查询时指定字段名，ES 返回该字段中命中的片段。RestHighLevelClient 的写法如下：
public Map<String, Object> searchWithHighlight(SearchCondition condition) throws IOException { SearchRequest searchRequest = new SearchRequest("product"); SearchSourceBuilder sourceBuilder = new SearchSourceBuilder(); BoolQueryBuilder boolQuery = QueryBuilders.boolQuery(); boolQuery.must(QueryBuilders.matchQuery("name", condition.getKeyword())); sourceBuilder.query(boolQuery); HighlightBuilder highlightBuilder = new HighlightBuilder(); HighlightBuilder.Field highlightName = new HighlightBuilder.Field("name"); highlightName.preTags("<span style='color:red'>"); highlightName.postTags("</span>"); highlightBuilder.field(highlightName); sourceBuilder.highlighter(highlightBuilder); searchRequest.source(sourceBuilder); SearchResponse response = client.search(searchRequest, RequestOptions.DEFAULT); Map<String, Object> result = new HashMap<>(); List<Map<String, Object>> list = new ArrayList<>(); for (SearchHit hit : response.getHits().getHits()) { Map<String, Object> source = hit.getSourceAsMap(); source.put("highlightName", hit.getHighlightFields() .get("name") .fragments()[0] .string()); list.add(source); } result.put("list", list); result.put("total", response.getHits().getTotalHits().value); return result; }高亮字段有三个常见翻车点需要提一下：字段类型必须是 Text，keyword 类型无法高亮；查询时如果有多个条件，但高亮只对包含关键词的字段生效，不要对 filter 字段声明高亮；preTags 与 postTags 如果不设置，默认返回标签，很多前端框架需要自定义样式，所以建议在服务端直接拼接好带色 HTML 或约定标签交由前端处理。fragments()[0] 需要判空，因为当高亮字段没有命中时，fragments 数组是空的，直接取下标会抛 ArrayIndexOutOfBoundsException。
4.3 7.2.0 的分页细节：from.size 与最大窗口限制
ES 分页有两种常用方式。一是 from + size 浅分页，适合页面跳转，页码越深性能越差。二是 search_after 深分页，适合 app 下拉加载与后台导出场景。7.2.0 的默认限制是 from + size 不能超过 10000，这个参数是 index 级别的 max_result_window 控制的。
public List<Product> searchByScrollAfter(String lastSortValue, int size) throws IOException { SearchRequest searchRequest = new SearchRequest("product"); SearchSourceBuilder sourceBuilder = new SearchSourceBuilder(); sourceBuilder.query(QueryBuilders.matchAllQuery()); sourceBuilder.size(size); sourceBuilder.sort("price", SortOrder.ASC); if (StringUtils.isNotBlank(lastSortValue)) { sourceBuilder.searchAfter(new Object[]{new BigDecimal(lastSortValue)}); } searchRequest.source(sourceBuilder); SearchResponse response = client.search(searchRequest, RequestOptions.DEFAULT); List<Product> list = new ArrayList<>(); for (SearchHit hit : response.getHits().getHits()) { list.add(JSONObject.parseObject(hit.getSourceAsString(), Product.class)); } return list; }search_after 依赖排序字段生成一个全局唯一的游标值。翻页时把上一页最后一条记录里用于排序的值传回来，替代 from 参数。这里排序字段用 price，它可能出现相同值，为了确保唯一，建议在排序里追加一个 _id 字段作为最终排序条件。使用 search_after 时不能再指定 from，这是 ES 的硬性要求。对于后台导出这种需要全量遍历的场景，scroll API 才会更合适，但 scroll 要求保持上下文，ES 会维护一个快照，长时间挂起会占用大量内存，7.2.0 中不推荐超过 5 分钟。
5. 整合 ES 7.2.0 的避坑清单：5 个高频踩坑记录与修复
5.1 启动报错：Received fatal alert: protocol_version
现象：SpringBoot 项目启动正常，但第一次调用 ES 接口时报错，堆栈信息包含 Received fatal alert: protocol_version。
原因：这是 JDK 版本与 ES 7.2.0 传输层协议不兼容导致的坑。ES 7.2.0 的 TransportClient 底层 Netty 与 JDK 11+ 的 TLS 协议协商存在版本不匹配，如果你恰好用 JDK 11 或更高版本跑项目，这个问题极其典型。
解决：优先切换到 RestHighLevelClient，它走 HTTP 协议，不受 TransportClient 的 TLS 实现影响。如果项目里暂时离不开 Spring Data 的自动 Repository，也可以把 JDK 降到 8 并明确使用 3.2.x 的 spring-data-elasticsearch。生产环境我推荐前者，一劳永逸地避开这条废弃链路。
5.2 max_result_window 超限：Result window is too large
现象：分页查询访问了第 10000 条之后的数据，ES 直接抛异常，提示 Result window is too large，from + size must be less than or equal to 10000。
原因：ES 索引默认 max_result_window 为 10000，超出这个范围的 from+size 组合会被拦截。这个限制是索引级配置，不是全局的，需要针对具体索引修改。
解决：在 Kibana 或通过 REST API 修改索引设置：
PUT /product/_settings { "index": { "max_result_window": "100000" } }修改索引的 settings 不影响索引现有数据，是热更新操作。但如果未来数据量继续增长，把窗口调大治标不治本。更合理的方案是：前后台分页用 search_after 或 scroll 替代 from+size。我一般在业务量超过千万级才会把 max_result_window 调大，并且只调到 5 万以内，避免深度分页把内存耗光导致全文检索性能集体下降。
5.3 集群无主节点导致索引创建卡死
现象：应用启动时创建索引卡住，es 日志显示 red 状态，或者日志反复出现 waiting for master node。
原因：ES 7.2.0 对集群健康度比旧版更敏感。单节点启动时，如果 discovery.type 不是 single-node，节点会期待加入现有集群，没有发现其他节点时不会自封为 master，导致整个集群处于无主状态。
解决：单机开发环境启动时，在 elasticsearch.yml 中设置：
discovery.type: single-node如果是多节点测试环境，确认所有节点配置了相同的 cluster.name 并且网络可互通。另外注意 Spring Data 配置里 cluster-name 必须与 elasticsearch.yml 中的 cluster.name 完全一致，否则节点发现了也不会加入，这个参数玄学味道比较重，排错时优先检查两边字符串是否完全相等。
5.4 IK 分词插件缺失导致索引创建失败
现象：实体类字段配置了 analyzer = ik_max_word，应用启动创建索引时报 MapperParsingException，提示 Analyzer [ik_max_word] not found。
原因：ES 服务端没有安装 IK 分词插件，但客户端实体仍然声明了该分词器。
解决：进入 ES 的 plugins 目录，安装 IK 分词器，需要选用与 ES 7.2.0 匹配的版本，然后重启 ES：
./bin/elasticsearch-plugin install https://github.com/medcl/elasticsearch-analysis-ik/releases/download/v7.2.0/elasticsearch-analysis-ik-7.2.0.zip安装前先确认 ES 是否已经启用了 security 或证书校验，如果有需要额外调整 rest client 的 SSL 配置。插件的版本必须与 ES 主版本完全一致，7.2.0 的插件不能装到 7.3.0 上，这与部分读者已有的 mysql、redis 类插件经验不同，ES 插件对版本绑定非常严。
5.5 实体字段与 ES 返回字段类型不一致导致反序列化报错
现象：查询接口报错，异常堆栈是 ClassCastException 或者 JSON parse error，提示 Long can not cast to Integer、BigDecimal 无法解析等。
原因：ES 数字类型与 Java 实体类型之间的映射不对。比如 ES 里字段映射成 long，实体类却声明为 Integer，反序列化时 fastjson 或 Jackson 的严格模式就会拒绝。另一个常见场景是 date 字段在 ES 中返回的时间戳格式与 Java Date 不兼容。
解决：先通过 Kibana 查看索引 mapping，确认字段的实际类型，再回来修改实体类。ES 7.2.0 的 Date 字段默认格式通常形如 yyyy-MM-dd HH:mm:ss 或 epoch_millis，Java 侧要么用 Long 接收时间戳，要么通过 @JsonFormat 显式指定格式。数值字段统一定义为 BigDecimal 或 Long 能绕开多数精度问题，不推荐用 float 存金额类字段，浮点精度在 ES 聚合中会造成统计偏差，这是实战中容易让人忽视的。另外 double 无法精确匹配等于特定值，如果需要精确过滤就必须映射为 keyword。
6. 进阶技巧：批量写入、索引重建与聚合统计
6.1 用 Bulk 批量写入 10 万级数据
单条 save 在数据量上来后效率很低，常见做法是用 BulkRequest 一次性提交成批数据。批量写入必须控制每批条数和数据大小，7.2.0 建议每批 5000 到 10000 条，或者单批数据量不超过 15MB。超过这个大小，ES 的 HTTP 层会返回 413 或直接超时。
public boolean bulkInsert(List<Product> products) throws IOException { BulkRequest bulkRequest = new BulkRequest(); for (Product product : products) { bulkRequest.add(new IndexRequest("product") .id(product.getId()) .source(JSONObject.toJSONString(product), XContentType.JSON)); } BulkResponse response = client.bulk(bulkRequest, RequestOptions.DEFAULT); if (response.hasFailures()) { log.error("批量插入失败: {}", response.buildFailureMessage()); return false; } return true; }BulkRequest 是顺序写入的，如果中途有失败项，hasFailures 会返回 true，ES 会把失败原因拼接在 buildFailureMessage 中。注意单条失败不会中止整个批次的请求，所以批量写入必需要处理部分失败的情况。整批处理失败时，回滚 ES 本身不提供事务能力，只能通过重试单个文档或对比日志与源数据，这就是 ES 建立在最终一致性之上的现实，天然无强事务，只能靠业务侧补偿。
批量写入前建议先关闭 refresh 间隔，这个参数是写入速率的隐藏瓶颈。ES 默认每秒刷新一次索引，数据量大的时候，把 refresh_interval 临时设成 -1，等待写入完成后调回 1s，索引速度会有明显提升：
PUT /product/_settings { "index": { "refresh_interval": "-1" } }6.2 索引重建流程：字段类型改错的最佳后悔药
ES 不支持直接修改字段类型，这是新手最容易碰壁的地方。如果你在实体里把 price 声明成了 text 并且已经创建索引，想要改成 double，必须走重建索引。正确步骤是先基于新结构创建临时索引，再通过 reindex 将数据复制过去，最后切换别名。
PUT /product_v2 { "mappings": { "properties": { "name": { "type": "text", "analyzer": "ik_max_word" }, "brand": { "type": "keyword" }, "price": { "type": "double" }, "createTime": { "type": "date" } } } } POST /_reindex { "source": { "index": "product" }, "dest": { "index": "product_v2" } }reindex 是 ES 自带的数据搬迁接口，它不会修改原索引。操作完成后，应用层需要将搜索结果指向 product_v2，推荐用索引别名 xuan。给索引起别名并让应用连接别名之后，后续版本切换与回滚都只需要改别名，业务代码不动：
POST /_aliases { "actions": [ { "add": { "index": "product_v2", "alias": "product_alias" } }, { "remove": { "index": "product", "alias": "product_alias" } } ] }这样一来，即使新索引有问题，也可以快速把别名切回旧索引，算得上是对付结构变更的一剂后悔药。需要注意 reindex 在数据量大时是异步行为，在 Kibana 中可以查看 task API 的进度，reindex 期间不要删除原索引，避免失败后没有回退路径。
6.3 一个基于 terms 聚合的统计用例
聚合查询是搜索引擎比关系型数据库出色很多的能力，7.2.0 的 rest client 支持各种聚合器。以按品牌统计商品数为例：
public Map<String, Long> aggregateByBrand() throws IOException { SearchRequest searchRequest = new SearchRequest("product"); SearchSourceBuilder sourceBuilder = new SearchSourceBuilder(); sourceBuilder.size(0); sourceBuilder.aggregation(AggregationBuilders .terms("brand_count") .field("brand") .size(20)); searchRequest.source(sourceBuilder); SearchResponse response = client.search(searchRequest, RequestOptions.DEFAULT); Terms brandCount = response.getAggregations().get("brand_count"); Map<String, Long> result = new HashMap<>(); for (Terms.Bucket bucket : brandCount.getBuckets()) { result.put(bucket.getKeyAsString(), bucket.getDocCount()); } return result; }sourceBuilder.size(0) 表示不返回文档明细，只返回聚合结果，这一步能省下大量传输开销。terms 聚合的字段必须是 keyword 类型，否则聚合报错或结果不符合预期。聚合桶数量通过 size 控制，这里 20 代表只返回品牌计数最多的前 20 个桶，而不是全部。聚合计算是基于 Lucene 的倒排索引，性能远高于同等条件下关系型数据库的 group by，这也是后端用 ES 做报表统计的核心原因。
在我经手的项目里，SpringBoot 打包后一般直接部署在容器中，ES 服务单独部署在专用机器上。两者之间隔了一层网络，应用层必须对 ES 调用做超时与降级，不要无限等待；我习惯给 RestHighLevelClient 的 RequestOptions 设置连接超时与 socket 超时，ES 集群抖动时应用不至于整体卡死。设置方法如下：
RequestOptions.Builder options = RequestOptions.DEFAULT.toBuilder(); options.setHttpAsyncResponseConsumerFactory( new HttpAsyncResponseConsumerFactory .HeapBufferedResponseConsumerFactory(30 * 1024 * 1024));这套组合下来，SpringBoot 与 ES 7.2.0 的整合已经能覆盖日常开发中从简单 CRUD 到复杂检索、批量索引、聚合统计的大部分场景。做这类整合时保持一个习惯：所有索引结构变动，优先改映射字段，而不是在代码里做兼容；所有查询参数，先在 Kibana 验证 DSL 再写进 java，这个习惯帮我避开了无数坑，希望帮到你。
本文还有配套的精品资源，点击获取
