Elasticsearch（簡稱 ES）是當前最流行的分布式搜索引擎，具備強大的全文檢索與數(shù)據(jù)分析能力。而 Spring Data Elasticsearch 基于 Spring Data API 對 ES 客戶端進行了封裝，極大簡化了 Spring Boot 項目與 ES 的整合開發(fā)流程。

本文基于官方文檔與實戰(zhàn)經驗，系統(tǒng)總結 ?Spring Boot 整合 Elasticsearch 8.x 的核心要點、版本選型、三種主流實現(xiàn)方式（ElasticsearchRepository、ElasticsearchTemplate、ElasticsearchClient）及完整代碼示例?，并附知識體系梳理，助力開發(fā)者快速上手、高效落地。

一、Spring Data Elasticsearch 核心概述

1.1 核心定位與價值

• Spring Data Elasticsearch 是 Spring Data 項目的子模塊，?對 Elasticsearch 官方 Java 客戶端進行封裝?，提供統(tǒng)一、簡潔的編程模型。
• 開發(fā)者無需直接調用復雜的 REST API，即可完成索引管理、文檔 CRUD、高級搜索等操作。
• ?以 POJO 為中心?，通過注解將 Java 實體類與 ES 文檔自動映射，顯著降低整合門檻。
• 在提升開發(fā)效率的同時，?保留 Elasticsearch 的核心特性與高性能優(yōu)勢?。

1.2 版本對應關系（關鍵重點！務必嚴格遵守）

版本不匹配是整合失敗的最常見原因。官方明確的兼容關系如下：

若使用 Spring Boot 3.3.2，Maven/Gradle 會自動引入 spring-data-elasticsearch:5.3.2，?無需手動指定版本?。

切勿混用 7.x 與 8.x 客戶端，API 差異巨大，極易導致運行時錯誤。

1.3 核心依賴與官方資源

核心依賴（Maven 示例）

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-elasticsearch</artifactId>
    <!-- Spring Boot 3.3.2 自動引入 compatible 版本 -->
</dependency>

無需額外引入 elasticsearch-java 客戶端?，starter 已包含。

二、Spring Boot 配置 Elasticsearch 的兩種方式

2.1 方式一：application.yml配置（推薦）

配置簡單、維護方便，適用于大多數(shù)場景。

spring:
  elasticsearch:
    uris: <http://localhost:9200>
    connection-timeout: 1s
    socket-timeout: 30s

支持多個 URI（集群部署）：uris: ["<http://es1:9200>", "<http://es2:9200>"]

2.2 方式二：@Configuration自定義配置類（靈活可控）

適用于需要 認證、SSL、自定義 HTTP 客戶端 等高級場景。

@Configuration
public class ElasticsearchConfig extends ElasticsearchConfiguration {

    @Override
    public ClientConfiguration clientConfiguration() {
        return ClientConfiguration.builder()
            .connectedTo("localhost:9200")
            // .withBasicAuth("user", "password")       // 基礎認證
            // .useSsl()                                // 啟用 HTTPS
            .build();
    }
}

繼承 ElasticsearchConfiguration 可復用 Spring Data 的自動裝配邏輯。

三、三種核心實現(xiàn)方式（實戰(zhàn)詳解）

3.1 方式一：ElasticsearchRepository（聲明式開發(fā)，最簡）

適合：基礎 CRUD、簡單條件查詢

步驟 1：創(chuàng)建實體類（與 ES 索引映射）

@Document(indexName = "employee")
public class Employee {
    @Id
    private String id;

    @Field(type = FieldType.Text, analyzer = "ik_max_word")
    private String name;

    @Field(type = FieldType.Keyword)
    private String department;

    @Field(type = FieldType.Double)
    private Double salary;

    // getters & setters
}

關鍵注解說明?：

• @Document：指定索引名，?索引不存在時可自動創(chuàng)建?（需開啟自動創(chuàng)建）。
• @Id：對應 ES 文檔 _id。
• @Field：控制字段類型、分詞器（如 ik_max_word / ik_smart）。

步驟 2：定義 Repository 接口

public interface EmployeeRepository extends ElasticsearchRepository<Employee, String> {
    List<Employee> findByDepartment(String department);
    List<Employee> findByNameContaining(String name);
}

無需實現(xiàn)類?！Spring Data 自動生成實現(xiàn)，支持 ?方法名派生查詢?（見下表）。

步驟 3：測試使用

@Autowired
private EmployeeRepository employeeRepo;

// 保存
Employee emp = new Employee("1", "張三", "研發(fā)部", 15000.0);
employeeRepo.save(emp);

// 查詢
List<Employee> list = employeeRepo.findByDepartment("研發(fā)部");

3.2 方式二：ElasticsearchTemplate（模板式開發(fā)，靈活）

適合：批量操作、復雜查詢、高亮、聚合等中等復雜場景

注意：?新版 ElasticsearchTemplate 已基于官方 ElasticsearchClient 實現(xiàn)?，不再依賴廢棄的 RestHighLevelClient。

核心操作示例

@Autowired
private ElasticsearchTemplate elasticsearchTemplate;

// 創(chuàng)建索引（帶 mapping）
elasticsearchTemplate.createIndex(Employee.class);

// 批量插入
List<IndexQuery> queries = employees.stream()
    .map(emp -> new IndexQueryBuilder().withId(emp.getId()).withObject(emp).build())
    .collect(Collectors.toList());
elasticsearchTemplate.bulkIndex(queries);

// 復雜查詢（Match + 高亮）
Query query = NativeQuery.builder()
    .withQuery(q -> q.match(m -> m.field("name").query("工程師")))
    .withHighlight(h -> h.fields(Map.of("name", HighlightField.of(hf -> hf)))))
    .build();

SearchHits<Employee> hits = elasticsearchTemplate.search(query, Employee.class);

支持原生 DSL 構建，靈活性遠超 Repository。

3.3 方式三：ElasticsearchClient（官方推薦原生客戶端）

適合：高級聚合、極致性能優(yōu)化、完全控制請求細節(jié)

Spring Boot 3.3+ 中可直接注入：

@Autowired
private ElasticsearchClient esClient;

核心操作示例

// 索引文檔
Product product = new Product("p1", "山地自行車", 2999.0);
esClient.index(i -> i
    .index("products")
    .id(product.getId())
    .document(product)
);

// 搜索（Match 查詢）
String keyword = "自行車";
SearchResponse<Product> response = esClient.search(s -> s
    .index("products")
    .query(q -> q.match(m -> m.field("name").query(keyword))),
    Product.class
);

// 聚合查詢（按價格區(qū)間分組）
SearchResponse<Void> aggResp = esClient.search(b -> b
    .index("products")
    .size(0) // 不返回文檔，只返回聚合結果
    .aggregations("price_ranges", a -> a
        .range(r -> r
            .field("price")
            .ranges(
                r1 -> r1.from(0).to(1000),
                r2 -> r2.from(1000).to(5000)
            )
        )
    ),
    Void.class
);

完全兼容 Elasticsearch 8.x 新 API?，語法簡潔、類型安全、性能最優(yōu)。

四、核心注意事項與關鍵細節(jié)

4.1 版本兼容性

• ?必須嚴格對齊?：ES 8.14 → Spring Data ES 5.3 → Spring Boot 3.3。
• 使用 mvn dependency:tree 或 gradle dependencies 檢查依賴沖突。

4.2 分詞器配置

• 使用 ik_max_word / ik_smart 前，?必須在 ES 服務器安裝 IK 分詞器插件?。
• 未安裝會導致啟動報錯或分詞失效。

4.3 三種方式對比與選型建議

新項目建議優(yōu)先使用 ElasticsearchClient，長期維護性最佳。

4.4 其他關鍵細節(jié)

• ?批量操作?：避免循環(huán)單條插入，使用 bulk API 提升性能 10 倍 +。
• ?聚合查詢?：設置 size: 0 避免返回無用文檔，減少網絡開銷。
• ?單節(jié)點開發(fā)環(huán)境?：創(chuàng)建索引時設置 "number_of_replicas": 0，防止副本分配失敗。
• ?日志調試?：開啟 logging.level.org.elasticsearch.client=DEBUG 查看實際請求。

五、總結

Spring Boot 整合 Elasticsearch 8.x 的核心在于 ?合理選型 + 規(guī)范配置 + 場景化使用?：

• 簡單場景 → ElasticsearchRepository，開發(fā)效率最高；
• 中等復雜度 → ElasticsearchTemplate，平衡靈活性與便捷性；
• 復雜/高性能場景 → ?**ElasticsearchClient（官方推薦）**?，掌控全局。

 ?牢記三點?：

1. ?版本必須嚴格匹配?；
2. ?IK 分詞器需提前安裝?；
3. ?批量操作用 bulk，聚合查詢設 size=0?。

到此這篇關于SpringBoot整合Elasticsearch 8.x的實戰(zhàn)總結(附完整示例)的文章就介紹到這了,更多相關SpringBoot整合Elasticsearch 8.x內容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關文章希望大家以后多多支持腳本之家！

最新評論