若依 (Ruoyi) 集成 Easy-Es 完整版教程

yyb1369584682

421人浏览 · 2026-05-22 11:35:59

yyb1369584682 · 2026-05-22 11:35:59 发布

若依 (Ruoyi) 集成 Easy-Es 完整版教程

前言

Easy-Es（简称EE）是一款基于ElasticSearch(简称Es)官方提供的RestHighLevelClient打造的ORM开发框架，在 RestHighLevelClient 的基础上,只做增强不做改变，为简化开发、提高效率而生,您如果有用过Mybatis-Plus(简称MP),那么您基本可以零学习成本直接上手EE,EE是MP的Es平替版,在有些方面甚至比MP更简单,同时也融入了更多Es独有的功能,助力您快速实现各种场景的开发.

一、整体流程概览

引入 Easy-Es 依赖
配置扫描路径（核心）
yml 配置 ES 连接
编写实体类（注解使用）
Docker 快速搭建 ES + IK 分词器
业务层 CRUD 演示

二、模块创建与依赖引入

新建模块

在common模块中新建ruoyi-common-elasticsearch模块
在这里插入图片描述
2. pom.xml 引入 Easy-Es

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns="http://maven.apache.org/POM/4.0.0"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <parent>
        <groupId>org.dromara</groupId>
        <artifactId>zxiat-common</artifactId>
        <version>${revision}</version>
    </parent>
    <modelVersion>4.0.0</modelVersion>

    <artifactId>ruoyi-common-elasticsearch</artifactId>

    <description>
        ruoyi-common-elasticsearch ES搜索引擎服务
    </description>

    <dependencies>
        <dependency>
            <groupId>org.dromara.easy-es</groupId>
            <artifactId>easy-es-boot-starter</artifactId>
            <version>2.0.0</version>
        </dependency>
    </dependencies>
</project>

三、核心配置：Mapper 扫描

新建配置类 `EasyEsConfiguration.java`

要注意EasyEsConfiguration中@EsMapperScan(“org.dromara.**.esmapper”)中扫描 Mapper 文件夹的路径
在这里插入图片描述

四、配置文件

配置文件中增加easy-es相关配置

--- # elasticsearch 功能配置
# 文档地址: https://www.easy-es.cn/
# 更改包名需要去 EasyEsConfiguration 修改包扫描(后续版本支持配置文件读取)
easy-es:
  compatible: true # 兼容模式开关,默认为false,若您的es客户端版本小于8.x,务必设置为true才可正常使用,8.x及以上则可忽略此项配置
  # 是否开启EE自动配置
  enable: true
  # es连接地址+端口 格式必须为ip:port,如果是集群则可用逗号隔开
  address : localhost:9200
  # 默认为http
  schema: http
  # 注意ES建议使用账号认证 不使用会报警告日志
  #如果无账号密码则可不配置此行
  #username:
  #如果无账号密码则可不配置此行
  #password:
  # 心跳策略时间 单位:ms
  keep-alive-millis: 18000
  # 连接超时时间 单位:ms
  connectTimeout: 5000
  # 通信超时时间 单位:ms
  socketTimeout: 5000
  # 连接请求超时时间 单位:ms
  connectionRequestTimeout: 5000
  # 最大连接数 单位:个
  maxConnTotal: 100
  # 最大连接路由数 单位:个
  maxConnPerRoute: 100
  global-config:
    # 开启控制台打印通过本框架生成的DSL语句,默认为开启,测试稳定后的生产环境建议关闭,以提升少量性能
    print-dsl: true
    # 异步处理索引是否阻塞主线程 默认阻塞 数据量过大时调整为非阻塞异步进行 项目启动更快
    asyncProcessIndexBlocking: true
    db-config:
      # 是否开启下划线转驼峰 默认为false
      map-underscore-to-camel-case: true
      # id生成策略 customize为自定义,id值由用户生成,比如取MySQL中的数据id,如缺省此项配置,则id默认策略为es自动生成
      id-type: customize
      # 字段更新策略 默认为not_null
      field-strategy: not_null
      # 默认开启,查询若指定了size超过1w条时也会自动开启,开启后查询所有匹配数据,若不开启,会导致无法获取数据总条数,其它功能不受影响.
      enable-track-total-hits: true
      # 数据刷新策略,默认为不刷新
      refresh-policy: immediate

五、实体类

package org.dromara.science.domain;

import lombok.Data;
import java.util.Date;
import org.dromara.easyes.annotation.IndexField;
import org.dromara.easyes.annotation.IndexId;
import org.dromara.easyes.annotation.IndexName;
import org.dromara.easyes.annotation.rely.FieldType;

import java.util.List;

/**
 * 对象 paper_info
 *
 */
@Data
@IndexName("paper_info")
public class PaperInfo {

    /**
     * ID
     */
    @IndexId
    private Long paperId;  // 映射到 ES 的 _id 字段
    
    /**
     * 中文名
     */
    private String zhName;

    /**
     * 作者名称
     */
    @IndexField(fieldType = FieldType.TEXT)
    private List<String> authors;

    /**
     * 作者名称列表
     */
    @IndexField(fieldType = FieldType.NESTED, nestedClass = Author.class)
    private List<Author> authorDetails;

    /**
     * 发表时间
     */
    @IndexField(fieldType = FieldType.DATE, dateFormat = "yyyy-MM-dd")
    private Date coverDateStart;
    
    @Data
    public class Author {
        private String name;
        private String nameZh;
    }
}

（1）注意Easy-ES中使用@IndexId标记Elasticsearch 文档的唯一标识字段（_id），而不是@Id，不标注@IndexId注解时在保存数据到Elasticsearch时可能会报错cn.easyes.common.exception.EasyEsException: no such method

（2）嵌套类需要使用@IndexField(fieldType = FieldType.NESTED, nestedClass = Author.class)，不使用的话有时候会报错Caused by: java.lang.NullPointerException: Cannot invoke “String.length()” because “name” is null
在这里插入图片描述

六、elasticsearch环境搭建

1、使用docker-compose安装elasticsearch

version: '3'

services:
  elasticsearch:
    image: docker.elastic.co/elasticsearch/elasticsearch:7.17.8
    container_name: elasticsearch
    ports:
      - "9200:9200"
      - "9300:9300"
    environment:
      # 设置集群名称
      cluster.name: elasticsearch
      # 以单一节点模式启动
      discovery.type: single-node
      ES_JAVA_OPTS: "-Xms512m -Xmx512m"
    volumes:
      - /docker/elasticsearch/plugins:/usr/share/elasticsearch/plugins
      - /docker/elasticsearch/data:/usr/share/elasticsearch/data
      - /docker/elasticsearch/logs:/usr/share/elasticsearch/logs
    network_mode: "host"

docker-compose up -d

2、按照ElasticSearch-analysis-ik中文分词器插件

进入容器

docker exec -it elasticsearch bash

安装插件，版本与ES保持一致

bin/elasticsearch-plugin install https://get.infini.cloud/elasticsearch/analysis-ik/7.17.8

插件卸载

bin/elasticsearch-plugin remove analysis-ik

安装后重启elasticsearch

docker restart elasticsearch

七、Mapper 编写

package org.dromara.science.esmapper;

import org.dromara.easyes.core.core.BaseEsMapper;
import org.dromara.science.domain.PaperInfo;
import org.springframework.stereotype.Repository;

@Repository
public interface PaperInfoMapper extends BaseEsMapper<PaperInfo> {

}