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

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

一、Spring Data Elasticsearch 核心概述

1.1 核心定位與價(jià)值

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

1.2 版本對(duì)應(yīng)關(guān)系（關(guān)鍵重點(diǎn)！務(wù)必嚴(yán)格遵守）

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

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

切勿混用 7.x 與 8.x 客戶端，API 差異巨大，極易導(dǎo)致運(yùn)行時(shí)錯(cuò)誤。

1.3 核心依賴與官方資源

核心依賴（Maven 示例）

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

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

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

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

配置簡(jiǎn)單、維護(hù)方便，適用于大多數(shù)場(chǎng)景。

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

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

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

適用于需要 認(rèn)證、SSL、自定義 HTTP 客戶端 等高級(jí)場(chǎng)景。

@Configuration
public class ElasticsearchConfig extends ElasticsearchConfiguration {

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

繼承 ElasticsearchConfiguration 可復(fù)用 Spring Data 的自動(dòng)裝配邏輯。

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

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

適合：基礎(chǔ) CRUD、簡(jiǎn)單條件查詢

步驟 1：創(chuàng)建實(shí)體類（與 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
}

關(guān)鍵注解說明?：

• @Document：指定索引名，?索引不存在時(shí)可自動(dòng)創(chuàng)建?（需開啟自動(dòng)創(chuàng)建）。
• @Id：對(duì)應(yīng) 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);
}

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

步驟 3：測(cè)試使用

@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ā)，靈活）

適合：批量操作、復(fù)雜查詢、高亮、聚合等中等復(fù)雜場(chǎng)景

注意：?新版 ElasticsearchTemplate 已基于官方 ElasticsearchClient 實(shí)現(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);

// 復(fù)雜查詢（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 構(gòu)建，靈活性遠(yuǎn)超 Repository。

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

適合：高級(jí)聚合、極致性能優(yōu)化、完全控制請(qǐng)求細(xì)節(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
);

// 聚合查詢（按價(jià)格區(qū)間分組）
SearchResponse<Void> aggResp = esClient.search(b -> b
    .index("products")
    .size(0) // 不返回文檔，只返回聚合結(jié)果
    .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?，語法簡(jiǎn)潔、類型安全、性能最優(yōu)。

四、核心注意事項(xiàng)與關(guān)鍵細(xì)節(jié)

4.1 版本兼容性

• ?必須嚴(yán)格對(duì)齊?：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 服務(wù)器安裝 IK 分詞器插件?。
• 未安裝會(huì)導(dǎo)致啟動(dòng)報(bào)錯(cuò)或分詞失效。

4.3 三種方式對(duì)比與選型建議

新項(xiàng)目建議優(yōu)先使用 ElasticsearchClient，長(zhǎng)期維護(hù)性最佳。

4.4 其他關(guān)鍵細(xì)節(jié)

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

五、總結(jié)

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

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

 ?牢記三點(diǎn)?：

1. ?版本必須嚴(yán)格匹配?；
2. ?IK 分詞器需提前安裝?；
3. ?批量操作用 bulk，聚合查詢?cè)O(shè) size=0?。

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

最新評(píng)論