后端脚手架

脚手架

DigitalHainan Spring 微服务框架脚手架与集成指南，覆盖 POM、缓存、MyBatis、认证、OSS 等核心模块。

概述

digitalhainan-elasticsearch

本文档用于指导在目标项目中完成 digitalhainan-elasticsearch 模块集成。
执行顺序：
先完成「10.1.2 快速集成」的全部步骤（必须）
根据业务需求，查阅「功能集成决策索引」选择对应路径，逐项实现
遇到配置问题时参考「10.1.3 配置属性参考」
出现异常时查阅「10.1.6 常见问题」
代码约定： 所有代码示例均包含完整 import 路径和类声明，可直接用于代码生成。

10.1.1 模块简介

digitalhainan-elasticsearch（artifactId: elasticsearch-spring-boot-starter）是数字海南框架的 ElasticSearch 搜索组件，基于 EasyES + Spring Data Elasticsearch 封装，提供：

IElasticsearchDocManager — 文档分页查询接口，支持动态查询条件、排序
SearchPage — 分页查询参数对象（索引名、排序、查询条件 Map）
ElasticUtils — 查询 Map 转 XContentParser、排序工具
RestHighLevelClient — 自动配置 ES 高级客户端（连接池、认证、心跳）
EasyES — 简化 ES CRUD 操作

Maven 坐标：

xml

<dependency>
    <groupId>cn.com.digitalhainan</groupId>
    <artifactId>elasticsearch-spring-boot-starter</artifactId>
</dependency>

前置依赖：

依赖	说明
`digitalhainan-pom`	父 POM
`digitalhainan-common`	通用基础组件
`digitalhainan-tools`	工具集（JacksonMapper）

当前版本： 3.1.0-SNAPSHOT

10.1.2 快速集成

10.1.2.1 确认父 POM

xml

<parent>
    <groupId>cn.com.digitalhainan</groupId>
    <artifactId>digitalhainan-pom</artifactId>
    <version>3.1.0-SNAPSHOT</version>
</parent>

10.1.2.2 添加依赖

xml

<dependencies>
    <dependency>
        <groupId>cn.com.digitalhainan</groupId>
        <artifactId>elasticsearch-spring-boot-starter</artifactId>
    </dependency>
</dependencies>

10.1.2.3 配置 ES 连接（application.yml）

yaml

digitalhainan:
  component:
    elasticsearch:
      enable: true
      schema: http
      cluster-nodes:
        - 192.168.1.100:9200
      connect-timeout: 5000
      socket-timeout: 30000
      connection-request-timeout: 5000
      max-conn-total: 100
      max-conn-per-route: 50
      keep-alive-millis: 30000
      # user-name: elastic       # 如需认证
      # password: your_password

10.1.2.4 验证清单

[ ] Spring Boot 启动成功，RestHighLevelClient Bean 已注册
[ ] ES 节点连通性正常
[ ] IElasticsearchDocManager 可注入

10.1.3 配置属性参考

配置键	类型	默认值	说明
`digitalhainan.component.elasticsearch.enable`	Boolean	—	是否启用 ES
`digitalhainan.component.elasticsearch.schema`	String	http	协议（http/https）
`digitalhainan.component.elasticsearch.cluster-nodes`	List<String>	—	ES 节点地址列表（host:port）
`digitalhainan.component.elasticsearch.connect-timeout`	Integer	—	连接超时（毫秒）
`digitalhainan.component.elasticsearch.socket-timeout`	Integer	—	Socket 超时（毫秒）
`digitalhainan.component.elasticsearch.connection-request-timeout`	Integer	—	连接请求超时（毫秒）
`digitalhainan.component.elasticsearch.user-name`	String	—	ES 用户名（可选）
`digitalhainan.component.elasticsearch.password`	String	—	ES 密码（可选）
`digitalhainan.component.elasticsearch.max-conn-total`	Integer	—	最大连接数
`digitalhainan.component.elasticsearch.max-conn-per-route`	Integer	—	每路由最大连接数
`digitalhainan.component.elasticsearch.keep-alive-millis`	Integer	30000	心跳间隔（毫秒）

10.1.4 核心功能使用

功能集成决策索引

需求场景	参考章节
ES 文档分页查询	4.1 IElasticsearchDocManager
自定义查询构建	4.2 ElasticUtils

10.1.4.1 IElasticsearchDocManager — 文档分页查询

java

package com.example.service;

import cn.com.digitalhainan.common.common.dto.PaginationInfoResDTO;
import cn.com.digitalhainan.elasticsearch.common.SearchPage;
import cn.com.digitalhainan.elasticsearch.common.constants.SortOrderEnum;
import cn.com.digitalhainan.elasticsearch.common.doc.IElasticsearchDocManager;
import org.elasticsearch.search.SearchHit;
import org.springframework.stereotype.Service;

import java.util.HashMap;
import java.util.Map;

/**
 * ES 文档分页查询示例
 */
@Service
public class EsSearchService {

    private final IElasticsearchDocManager docManager;

    public EsSearchService(IElasticsearchDocManager docManager) {
        this.docManager = docManager;
    }

    public PaginationInfoResDTO<SearchHit> search(String keyword, int pageNum, int pageSize) throws Exception {
        SearchPage searchPage = new SearchPage();
        searchPage.setIndexName("your_index_name");
        searchPage.setPageNum((long) pageNum);
        searchPage.setPageSize((long) pageSize);
        searchPage.setSortField("createTime");
        searchPage.setSortOrder(SortOrderEnum.DESC);

        // 构建查询条件（ES Query DSL 的 JSON 格式）
        Map<String, Object> queryMap = new HashMap<>();
        Map<String, Object> matchQuery = new HashMap<>();
        matchQuery.put("content", keyword);
        queryMap.put("query", Map.of("match", matchQuery));

        searchPage.setQueryMap(queryMap);

        return docManager.pageQuery(searchPage);
    }
}

10.1.4.2 ElasticUtils — 自定义查询

java

package com.example.service;

import cn.com.digitalhainan.elasticsearch.utils.ElasticUtils;
import cn.com.digitalhainan.elasticsearch.common.constants.SortOrderEnum;
import org.elasticsearch.search.builder.SearchSourceBuilder;

import java.util.Map;

/**
 * ElasticUtils 工具使用示例
 */
public class ElasticUtilsDemo {

    public void buildQuery() throws Exception {
        // 将查询 Map 转为 XContentParser
        Map<String, Object> queryMap = Map.of(
            "query", Map.of("bool", Map.of(
                "must", Map.of("match", Map.of("title", "关键词"))
            ))
        );
        var parser = ElasticUtils.queryMap2XContentParser(queryMap);

        // 排序工具
        SearchSourceBuilder builder = new SearchSourceBuilder();
        ElasticUtils.sort(SortOrderEnum.DESC, "createTime", builder);
    }
}

10.1.5 版本变更记录

v3.1.0（当前版本）

初始化 3.1.0 版本

v3.0.1

初始化 3.0.1

v3.0.0

修改配置适配 Spring Boot 3.x

v2.0.0

初始版本

10.1.6 常见问题

Q1：启动报错 "Connection refused"？

原因： ES 节点地址配置错误或 ES 服务未启动。 解决： 检查 cluster-nodes 配置，确认 ES 服务可访问。

Q2：IElasticsearchDocManager 无法注入？

原因： digitalhainan.component.elasticsearch.enable 未设置为 true。 解决： 在 application.yml 中设置 enable: true。

Q3：查询返回空结果？

原因： queryMap 格式不符合 ES Query DSL。 解决： 确保 queryMap 是合法的 ES Query DSL JSON 结构。

10.1.7 版本兼容性矩阵

elasticsearch-spring-boot-starter	Spring Boot	JDK	ES 版本	说明
3.1.0-SNAPSHOT	3.x	21	7.x	当前版本
3.0.0	3.x	21	7.x	Spring Boot 3.x 适配
2.0.0	2.x	8/11	7.x	javax 命名空间

digitalhainan-elasticsearch ​

10.1.1 模块简介 ​

10.1.2 快速集成 ​

10.1.2.1 确认父 POM ​

10.1.2.2 添加依赖 ​

10.1.2.3 配置 ES 连接（application.yml） ​

10.1.2.4 验证清单 ​

10.1.3 配置属性参考 ​

10.1.4 核心功能使用 ​

功能集成决策索引 ​

10.1.4.1 IElasticsearchDocManager — 文档分页查询 ​

10.1.4.2 ElasticUtils — 自定义查询 ​

10.1.5 版本变更记录 ​

v3.1.0（当前版本） ​

v3.0.1 ​

v3.0.0 ​

v2.0.0 ​

10.1.6 常见问题 ​

Q1：启动报错 "Connection refused"？ ​

Q2：IElasticsearchDocManager 无法注入？ ​

Q3：查询返回空结果？ ​

10.1.7 版本兼容性矩阵 ​