在当今的电商、日志分析以及内容管理系统中，面对海量的数据检索需求，传统关系型数据库的LIKE查询往往会导致全表扫描，严重拖垮系统性能。为了解决这一痛点，引入Elasticsearch这样的分布式搜索引擎成为了业界共识。Spring Data Elasticsearch作为Spring Boot生态中的重要组件，极大地简化了与Elasticsearch的交互操作。本文将深入探讨如何通过Spring Boot整合Spring Data Elasticsearch，从零开始搭建一个具备复杂条件过滤与高亮显示功能的搜索服务模块。
环境配置与依赖管理
在开始编写业务代码之前，合理的依赖管理和环境配置是保障整合顺利进行的前提。Spring Boot与Elasticsearch的版本对应关系非常严格，如果版本不匹配，极易出现客户端连接报错或API方法不兼容的问题。通常情况下，我们通过spring-boot-starter-parent来统一管理版本，这样可以最大程度避免版本冲突。
在pom.xml文件中，我们需要引入spring-boot-starter-data-elasticsearch依赖。这个起步依赖内部已经包含了Elasticsearch的高级REST客户端以及Spring Data的相关核心包。不需要再单独引入底层的elasticsearch-rest-high-level-client，以免造成依赖冲突。
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-elasticsearch</artifactId>
</dependency>
接下来是配置文件的编写。在application.yml中，我们需要指定Elasticsearch集群的连接地址和端口。如果是本地开发环境，确保Elasticsearch服务已经启动并监听了相应端口。为了演示方便，我们通常配置单个节点地址。同时，可以通过设置连接超时和读取超时时间，来防止因网络波动导致的请求阻塞。
spring:
elasticsearch:
uris: http://127.0.0.1:9200
connection-timeout: 1s
read-timeout: 30s
配置好环境后，我们需要定义与索引对应的实体类。Spring Data Elasticsearch提供了一套丰富的注解，用于将Java对象映射为Elasticsearch中的JSON文档。其中，@Document注解用于指定索引名称和分片副本数量，@Id注解标记主键字段，@Field注解则用于定义字段的数据类型、是否需要分词以及使用哪种分词器。正确设置分词器对中文搜索至关重要，通常我们会使用ik_max_word进行细粒度分词，使用ik_smart进行粗粒度分词。
自定义Repository接口与基础检索
Spring Data Elasticsearch的强大之处在于它遵循了Spring Data JPA的设计理念，开发者只需要定义一个接口，就能自动获得基础的增删改查功能。我们创建一个ProductRepository接口，让它继承ElasticsearchRepository。这个接口默认提供了保存、删除、根据ID查询以及分页查询等开箱即用的方法，基本能满足简单的业务需求。
public interface ProductRepository extends ElasticsearchRepository<Product, String> {
}
除了内置方法，Spring Data还支持通过方法名派生查询。这意味着只要你的方法命名符合特定规范，框架就能自动为你生成对应的查询语句。例如，如果你想根据商品名称和价格区间进行查询，可以直接定义方法名为findByNameAndPriceBetween。框架在运行时会解析方法名，将其转换为Elasticsearch的Query DSL。这种方式极大地减少了模板代码的编写，提升了开发效率。
然而，方法名派生查询在面对多条件动态组合或复杂排序时显得力不从心。这时，我们可以使用@Query注解直接编写Elasticsearch的JSON查询模板。通过这种方式，我们可以利用Elasticsearch原生的强大查询能力，比如使用bool查询来组合must、should和must_not条件。在@Query注解中，可以使用?0、?1等占位符来绑定方法参数，使得查询既灵活又直观。
复杂查询与高亮显示实战
在实际的搜索场景中，用户输入的搜索词往往需要同时在多个字段中进行匹配，并且搜索结果需要对匹配的关键词进行高亮显示，以提升用户体验。此时，基础的Repository接口已经无法满足需求，我们需要引入ElasticsearchRestTemplate来进行更底层的操作。ElasticsearchRestTemplate是Spring Data Elasticsearch提供的核心模板类，它封装了Elasticsearch的高阶REST客户端操作，允许我们构建极其复杂的查询。
通过ElasticsearchRestTemplate，我们可以使用NativeQuery来构建原生的查询条件。相比于注解方式，NativeQuery提供了纯Java API的构建方式，非常适合处理动态查询条件。我们可以使用Criteria类来链式添加查询条件，比如模糊匹配、精确匹配、范围查询等。然后通过NativeQuery.builder()将这些条件组合起来，并指定排序规则和分页参数。
@Autowired
private ElasticsearchRestTemplate elasticsearchTemplate;
public SearchHits<Product> searchProducts(String keyword, int page, int size) {
Criteria criteria = new Criteria("name").contains(keyword)
.or("description").contains(keyword);
NativeQuery query = NativeQuery.builder()
.withQuery(new CriteriaQuery(criteria))
.withSort(Sort.by(Sort.Direction.DESC, "price"))
.withPageable(PageRequest.of(page, size))
.build();
return elasticsearchTemplate.search(query, Product.class);
}
高亮显示是搜索功能不可或缺的一环。在构建NativeQuery时，我们可以通过withHighlightQuery方法添加高亮构建器。我们需要指定需要高亮显示的字段，以及高亮标签的前缀和后缀，比如使用<em>标签包裹匹配到的关键词。当查询执行完毕后，返回的SearchHits对象中会包含高亮结果。我们需要遍历这些结果，将原始实体类中的对应字段替换为带有高亮标签的字符串。需要注意的是，高亮处理后的结果与实体类是分离的，不能直接通过实体类获取，必须通过SearchHit对象的getHighlightFields方法来提取并手动赋值。
最后，在处理搜索结果时，我们还需要关注分页的元数据信息。SearchHits对象不仅包含了当前页的数据列表，还提供了总命中数、总分等关键信息。我们可以利用这些信息计算出总页数，并封装成统一的分页响应对象返回给前端。通过合理利用ElasticsearchRestTemplate和NativeQuery，我们能够构建出既具备高性能又具备高度灵活性的企业级搜索模块。
Spring BootSpring Data Elasticsearch全文搜索修改时间：2026-08-25 01:46:57