項目簡介

Easy-Es（簡稱EE） 是一款基于ElasticSearch(簡稱Es)官方提供的RestHighLevelClient打造的ORM開發(fā)框架，在RestHighLevelClient的基礎(chǔ)上，只做增強不做改變，為簡化開發(fā)、提高效率而生，您如果有用過MyBatis-Plus(簡稱MP)，那么您基本可以零學(xué)習(xí)成本直接上手EE,EE是MP的Es平替版，在有些方面甚至比MP更簡單，同時也融入了更多Es獨有的功能，助力您快速實現(xiàn)各種場景的開發(fā)。

項目地址

• Easy-Es Gitee：gitee.com/dromara/eas…
• Elasticsearch Download：www.elastic.co/cn/download…

Easy-Es自身優(yōu)勢

• 全自動索引托管: 全球開源首創(chuàng)的索引托管模式,開發(fā)者無需關(guān)心索引的創(chuàng)建更新及數(shù)據(jù)遷移等繁瑣步驟,索引全生命周期皆可托管給框架,由框架自動完成,過程零停機,用戶無感知,徹底解放開發(fā)者；
• 屏蔽語言差異: 開發(fā)者只需要會MySQL語法即可使用Es,真正做到一通百通,無需學(xué)習(xí)枯燥易忘的Es語法,Es使用相對MySQL較低頻,學(xué)了長期不用也會忘,沒必要浪費這時間.開發(fā)就應(yīng)該專注于業(yè)務(wù),省下的時間去擼鐵,去陪女朋友陪家人,不做資本家的韭菜；
• 代碼量極少: 與直接使用RestHighLevelClient相比,相同的查詢平均可以節(jié)省3-5倍左右的代碼量
• 零魔法值: 字段名稱直接從實體中獲取,無需輸入字段名稱字符串這種魔法值,提高代碼可讀性,杜絕因字段名稱修改而代碼漏改帶來的Bug；
• 零額外學(xué)習(xí)成本: 開發(fā)者只要會國內(nèi)最受歡迎的Mybatis-Plus語法,即可無縫遷移至EE,EE采用和前者相同的語法,消除使用者額外學(xué)習(xí)成本,直接上手；
• 降低開發(fā)者門檻: Es通常需要中高級開發(fā)者才能駕馭,但通過接入EE,即便是只了解ES基礎(chǔ)的初學(xué)者也可以輕松駕馭ES完成絕大多數(shù)需求的開發(fā),可以提高人員利用率,降低企業(yè)成本。

特性

• 無侵入：只做增強不做改變，引入它不會對現(xiàn)有工程產(chǎn)生影響，如絲般順滑；
• 損耗小：啟動即會自動注入基本CURD，性能基本無損耗，直接面向?qū)ο蟛僮鳎?/li>
• 強大的 CRUD 操作：內(nèi)置通用Mapper，僅僅通過少量配置即可實現(xiàn)大部分CRUD操作，更有強大的條件構(gòu)造器，滿足各類使用需；
• 支持 Lambda 形式調(diào)用：通過Lambda表達式，方便的編寫各類查詢條件，無需再擔(dān)心字段寫錯段；
• 支持主鍵自動生成：支持 2 種主鍵策略，可自由配置，完美解決主鍵問題；
• 支持 ActiveRecord 模式：支持ActiveRecord形式調(diào)用，實體類只需繼承Model類即可進行強大的 CRUD操作；
• 支持自定義全局通用操作：支持全局通用方法注入（ Write once, use anywhere ）；
• 內(nèi)置分頁插件：基于RestHighLevelClient物理分頁，開發(fā)者無需關(guān)心具體操作，且無需額外配置插件，寫分頁等同于普通List查詢,且保持和PageHelper插件同樣的分頁返回字段，無需擔(dān)心命名影響；
• MySQL功能全覆蓋：MySQL中支持的功能通過EE都可以輕松實現(xiàn)；
• 支持ES高階語法：支持高亮搜索,分詞查詢,權(quán)重查詢, Geo地理位置查詢、IP查詢、聚合查詢等高階語法；
• 良好的拓展性：底層仍使用RestHighLevelClient,可保持其拓展性,開發(fā)者在使用EE的同時,仍可使用RestHighLevelClient的功能。

?最新版本 Latest Version: v.1.1.1

Maven：

xml復(fù)制代碼<dependency> <groupId>cn.easy-es</groupId> <artifactId>easy-es-boot-starter</artifactId> <version>${Latest Version}</version></dependency>

Gradle：

csharp復(fù)制代碼compile group: 'cn.easy-es', name: 'easy-es-boot-starter', version: 'Latest Version'

Easy-Es適用場景

1?? 檢索類服務(wù)

• 搜索文庫
• 電商商品搜索
• 海量系統(tǒng)日志搜索

2?? 問答類服務(wù)

• 在線智能客服
• 機器人

3?? 地圖類服務(wù)

• 打車APP
• 外賣APP
• 社區(qū)團購配送
• 社交APP

注解

EsMapperScan

• 描述：mapper掃描注解,功能與Mybatis Plus的@MapperScan一致
• 使用位置：Spring Boot啟動類

kotlin復(fù)制代碼@EsMapperScan("cn.easy-es-mapper")public class Application{ // 省略其它...}

@IndexName

• 描述：索引名注解，標識實體類對應(yīng)的索引 對應(yīng)Mybatis Plus的@TableName注解,在v0.9.40之前此注解為@TableName；
• 使用位置：實體類

kotlin復(fù)制代碼@IndexNamepublic class Document { // 省略其它字段}

@IndexId

• 描述：Easy-Es主鍵注解,在v0.9.40之前此注解為@TableId；
• 使用位置：實體類中被作為Easy-Es主鍵的字段, 對應(yīng)MyBatis-Plus的@TableId注解。

kotlin復(fù)制代碼public class Document { @IndexId private String id; // 省略其它字段}

@IndexField

• 描述：ES字段注解, 對應(yīng)MP的@TableField注解,在v0.9.40之前此注解為@TableField；
• 使用位置：實體類中被作為ES索引字段的字段；
• 使用場景舉例：

1. 實體類中的字段并非ES中實際的字段,比如把實體類直接當DTO用了,加了一些ES中并不存在的無關(guān)字段,此時可以標記此字段,以便讓EE框架跳過此字段,對此字段不處理；
2. 字段的更新策略,比如在調(diào)用更新接口時,實體類的字段非Null或者非空字符串時才更新,此時可以加字段注解,對指定字段標記更新策略；
3. 需要對類型為text或keyword_text字段聚合時,可指定其fieldData=true，否則es會報錯；
4. 對指定字段進行自定義命名,比如該字段在es中叫wu-la,但在實體model中叫ula，此時可以在value中指定value="wu-la"；
5. 在自動托管索引模式下，可指定索引分詞器及索引字段類型；
6. 在自動托管索引模式下，可指定索引中日期的format格式。

使用示例:

typescript復(fù)制代碼public class Document { // 此處省略其它字段... // 場景一:標記es中不存在的字段 @IndexField(exist = false) private String notExistsField; // 場景二:更新時,此字段非空字符串才會被更新 @IndexField(strategy = FieldStrategy.NOT_EMPTY) private String creator; // 場景三: 指定fieldData @IndexField(fieldType = FieldType.text, fieldData = true) private String filedData; // 場景四:自定義字段名 @IndexField("wu-la") private String ula; // 場景五:支持日期字段在es索引中的format類型 @IndexField(fieldType = FieldType.DATE, dateFormat = "yyyy-MM-dd HH:mm:ss||yyyy-MM-dd||epoch_millis") private String gmtCreate; // 場景六:支持指定字段在es索引中的分詞器類型 @IndexField(fieldType = FieldType.TEXT, analyzer = Analyzer.IK_SMART, searchAnalyzer = Analyzer.IK_MAX_WORD) private String content;}

@Score

• 描述：得分注解
• 使用位置：實體類中被作為ES查詢得分返回的字段
• 使用場景舉例：比如需要知道本次匹配查詢得分有多少時,可以在實體類中添加一個類型為Float/float的字段,并在該字段上添加@Score注解,在后續(xù)查詢中,若es有返回當次查詢的得分,則此得分會自動映射至此字段上

@Distance

• 描述：距離注解
• 使用位置：實體類中被作為ES地理位置排序距離值的返回字段
• 使用場景舉例：比如需要知道按距離由近及遠查詢后的數(shù)據(jù),實際距離某一坐標有多遠,可以在實體類中添加一個類型為Double/double的字段,并在該字段上添加@Distance注解,在后續(xù)查詢中，若es有返回距離,則此距離會自動映射至此字段上

ES版本和Spring Boot版本

xml復(fù)制代碼<properties> <java.version>1.8</java.version> <easy-es.version>1.1.1</easy-es.version> <elasticsearch.version>7.14.0</elasticsearch.version></properties><!-- easy-es --><dependency> <groupId>cn.easy-es</groupId> <artifactId>easy-es-boot-starter</artifactId> <version>${easy-es.version}</version> <exclusions> <exclusion> <groupId>org.elasticsearch.client</groupId> <artifactId>elasticsearch-rest-high-level-client</artifactId> </exclusion> <exclusion> <groupId>org.elasticsearch</groupId> <artifactId>elasticsearch</artifactId> </exclusion> </exclusions></dependency><!-- elasticsearch --><dependency> <groupId>org.elasticsearch</groupId> <artifactId>elasticsearch</artifactId> <version>${elasticsearch.version}</version></dependency><dependency> <groupId>org.elasticsearch.client</groupId> <artifactId>elasticsearch-rest-high-level-client</artifactId> <version>${elasticsearch.version}</version></dependency>

Spring Boot配置

在 application.yml 配置文件中添加EasyEs必須的相關(guān)配置：

yaml復(fù)制代碼easy-es: enable: true #默認為true,若為false則認為不啟用本框架 address : 127.0.0.1:9200 # es的連接地址,必須含端口 若為集群,則可以用逗號隔開 例如:127.0.0.1:9200,127.0.0.2:9200 username: elastic #若無 則可省略此行配置 password: WG7WVmuNMtM4GwNYkyWH #若無 則可省略此行配置

BaseEsMapper CRUD接口

Easy-Es封裝了基本的CRUD操作API，通過繼承BaseEsMapper<T>賦予相關(guān)能力，比如：

csharp復(fù)制代碼public interface DocumentMapper extends BaseEsMapper<Document> {}

相關(guān)操作API

php復(fù)制代碼public interface BaseEsMapper<T> { /** * 是否存在索引 * * @param indexName 索引名稱 * @return 返回是否存在的布爾值 */ Boolean existsIndex(String indexName); /** * 獲取當前索引信息 * * @return 當前索引信息 */ GetIndexResponse getIndex(); /** * 獲取指定索引信息 * * @param indexName 指定索引名 * @return 指定索引信息 */ GetIndexResponse getIndex(String indexName); /** * 創(chuàng)建索引,根據(jù)當前mapper對應(yīng)實體類信息及其注解配置生成索引信息 * * @return 是否創(chuàng)建成功 */ Boolean createIndex(); /** * 創(chuàng)建索引,根據(jù)當前mapper對應(yīng)實體類信息及其注解配置生成索引信息 可指定索引名進行創(chuàng)建 適用于定時任務(wù)按日期創(chuàng)建索引場景 * * @param indexName 指定的索引名,會覆蓋注解上指定的索引名 * @return 是否創(chuàng)建成功 */ Boolean createIndex(String indexName); /** * 創(chuàng)建索引 * * @param wrapper 條件 * @return 是否成功 */ Boolean createIndex(LambdaEsIndexWrapper<T> wrapper); /** * 更新索引 * * @param wrapper 條件 * @return 是否成功 */ Boolean updateIndex(LambdaEsIndexWrapper<T> wrapper); /** * 刪除指定索引 * * @param indexNames 索引名稱數(shù)組 * @return 是否成功 */ Boolean deleteIndex(String... indexNames); /** * 標準查詢 * * @param wrapper 條件 * @return es標準結(jié)果 */ SearchResponse search(LambdaEsQueryWrapper<T> wrapper); /** * 獲取SearchSourceBuilder,可用于本框架生成基礎(chǔ)查詢條件,不支持的高階語法用戶可通過SearchSourceBuilder 進一步封裝 * * @param wrapper 條件 * @return 查詢參數(shù) */ SearchSourceBuilder getSearchSourceBuilder(LambdaEsQueryWrapper<T> wrapper); /** * es原生查詢 * * @param searchrequest 查詢請求參數(shù) * @param requestOptions 類型 * @return es原生返回結(jié)果 * @throws IOException IO異常 */ SearchResponse search(SearchRequest searchRequest, RequestOptions requestOptions) throws IOException; /** * es原生滾動查詢 * * @param searchScrollRequest 查詢請求參數(shù) * @param requestOptions 類型 * @return es原生返回結(jié)果 * @throws IOException IO異常 */ SearchResponse scroll(SearchScrollRequest searchScrollRequest, RequestOptions requestOptions) throws IOException; /** * 獲取通過本框架生成的查詢參數(shù),可用于檢驗本框架生成的查詢參數(shù)是否正確 * * @param wrapper 條件 * @return 查詢JSON格式參數(shù) */ String getSource(LambdaEsQueryWrapper<T> wrapper); /** * 指定返回類型及分頁參數(shù) * * @param wrapper 條件 * @param pageNum 當前頁 * @param pageSize 每頁條數(shù) * @return 指定的返回類型 */ EsPageInfo<T> pageQuery(LambdaEsQueryWrapper<T> wrapper, Integer pageNum, Integer pageSize); /** * searchAfter類型分頁 * * @param wrapper 條件 * @param searchAfter 當前頁 第一頁時為null * @param pageSize 每頁條數(shù) * @return 指定的返回類型 */ SAPageInfo<T> searchAfterPage(LambdaEsQueryWrapper<T> wrapper, List<Object> searchAfter, Integer pageSize); /** * 獲取總數(shù)(智能推斷:若wrapper中指定了去重字段則去重,若未指定則不去重 推薦使用) * * @param wrapper 條件 * @return 總數(shù) */ Long selectCount(LambdaEsQueryWrapper<T> wrapper); /** * 無論wrapper中是否指定去重字段,都以用戶傳入的distinct布爾值作為是否去重的條件 * * @param wrapper 條件 * @param distinct 是否去重 * @return 總數(shù) */ Long selectCount(LambdaEsQueryWrapper<T> wrapper, boolean distinct); /** * 插入一條記錄 * * @param entity 插入的數(shù)據(jù)對象 * @return 成功條數(shù) */ Integer insert(T entity); /** * 插入一條記錄,可指定多索引插入 * * @param entity 插入的數(shù)據(jù)對象 * @param indexNames 指定插入的索引名數(shù)組 * @return 總成功條數(shù) */ Integer insert(T entity, String... indexNames); /** * 批量插入 * * @param entityList 插入的數(shù)據(jù)對象列表 * @return 總成功條數(shù) */ Integer insertBatch(Collection<T> entityList); /** * 批量插入 * * @param entityList 插入的數(shù)據(jù)對象列表 * @param indexNames 指定插入的索引名數(shù)組 * @return 總成功條數(shù) */ Integer insertBatch(Collection<T> entityList, String... indexNames); /** * 根據(jù) ID 刪除 * * @param id 主鍵 * @return 成功條數(shù) */ Integer deleteById(Serializable id); /** * 根據(jù) ID 刪除 * * @param id 主鍵 * @param indexNames 指定刪除的索引名數(shù)組 * @return 總成功條數(shù) */ Integer deleteById(Serializable id, String... indexNames); /** * 刪除（根據(jù)ID 批量刪除） * * @param idList 主鍵列表 * @return 總成功條數(shù) */ Integer deleteBatchIds(Collection<? extends Serializable> idList); /** * 刪除（根據(jù)ID 批量刪除） * * @param idList 主鍵列表 * @param indexNames 指定刪除的索引名數(shù)組 * @return 總成功條數(shù) */ Integer deleteBatchIds(Collection<? extends Serializable> idList, String... indexNames); /** * 根據(jù) entity 條件，刪除記錄 * * @param wrapper 條件 * @return 總成功條數(shù) */ Integer delete(LambdaEsQueryWrapper<T> wrapper); /** * 根據(jù) ID 更新 * * @param entity 更新對象 * @return 總成功條數(shù) */ Integer updateById(T entity); /** * 根據(jù) ID 更新 * * @param entity 更新對象 * @param indexNames 指定更新的索引名稱數(shù)組 * @return 總成功條數(shù) */ Integer updateById(T entity, String... indexNames); /** * 根據(jù)ID 批量更新 * * @param entityList 更新對象列表 * @return 總成功條數(shù) */ Integer updateBatchByIds(Collection<T> entityList); /** * 根據(jù)ID 批量更新 * * @param entityList 更新對象列表 * @param indexNames 指定更新的索引名稱數(shù)組 * @return 總成功條數(shù) */ Integer updateBatchByIds(Collection<T> entityList, String... indexNames); /** * 根據(jù) whereEntity 條件，更新記錄 * * @param entity 更新對象 * @param updateWrapper 條件 * @return 成功條數(shù) */ Integer update(T entity, LambdaEsUpdateWrapper<T> updateWrapper); /** * 根據(jù) ID 查詢 * * @param id 主鍵 * @return 指定的返回對象 */ T selectById(Serializable id); /** * 根據(jù) ID 查詢 * * @param id 主鍵 * @param indexNames 指定查詢的索引名數(shù)組 * @return 指定的返回對象 */ T selectById(Serializable id, String... indexNames); /** * 查詢（根據(jù)ID 批量查詢） * * @param idList 主鍵列表 * @return 指定的返回對象列表 */ List<T> selectBatchIds(Collection<? extends Serializable> idList); /** * 查詢（根據(jù)ID 批量查詢） * * @param idList 主鍵列表 * @param indexNames 指定查詢的索引名數(shù)組 * @return 指定的返回對象列表 */ List<T> selectBatchIds(Collection<? extends Serializable> idList, String... indexNames); /** * 根據(jù) entity 條件，查詢一條記錄 * * @param wrapper 條件 * @return 指定的返回對象 */ T selectOne(LambdaEsQueryWrapper<T> wrapper); /** * 根據(jù) entity 條件，查詢?nèi)坑涗? * * @param wrapper 條件 * @return 指定的返回對象列表 */ List<T> selectList(LambdaEsQueryWrapper<T> wrapper); /** * 設(shè)置當前Mapper默認激活的全局索引名稱 務(wù)必謹慎操作,設(shè)置后全局生效,永駐jvm,除非項目重啟 * * @param indexName 索引名稱 * @return 是否成功 */ Boolean setCurrentActiveIndex(String indexName);}

Tips提示：

CRUD接口用法基本與MyBatis-Plus一致；

用戶需要繼承的Mapper為BaseEsMapper，而非BaseMapper；

EE沒有提供Service層,而是把MyBatis-Plus中一些Service層的方法直接下沉到Mapper層了,用戶用起來會更方便。

Easy-ES整合實踐

• 第一步：確保你的環(huán)境已經(jīng)安裝ElasticSearch，博主這里的演示版本為7.14.0，運行ElasticSearch；
• 第二步：創(chuàng)建Maven Project，引入Easy-Es依賴；
• 第三步：定義文檔類Document，測試Easy-Es的CRUD基本操作。

1?? 運行ElasticSearch

訪問：http://localhost:9200/，查看節(jié)點信息。

bash復(fù)制代碼{ "name": "LAPTOP-8G2EVQFP", # 默認節(jié)點名稱 "cluster_name": "elasticsearch", "cluster_uuid": "nnFJExSMRj-gy09OeHRk5A", "version": { # ES版本 "number": "7.3.2", "build_flavor": "default", "build_type": "zip", "build_hash": "1c1faf1", "build_date": "2019-09-06T14:40:30.409026Z", "build_snapshot": false, "lucene_version": "8.1.0", "minimum_wire_compatibility_version": "6.8.0", "minimum_index_compatibility_version": "6.0.0-beta1" }, "tagline": "You Know, for Search"}

2?? 創(chuàng)建Spring Boot項目，添加依賴

添加POM依賴：

xml復(fù)制代碼<properties> <java.version>1.8</java.version> <easy-es.version>1.1.1</easy-es.version> <elasticsearch.version>7.14.0</elasticsearch.version> <spring-boot-data-elasticsearch.version>3.0.4</spring-boot-data-elasticsearch.version></properties><dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter</artifactId> </dependency> <!-- easy-es --> <dependency> <groupId>cn.easy-es</groupId> <artifactId>easy-es-boot-starter</artifactId> <version>${easy-es.version}</version> <exclusions> <exclusion> <groupId>org.elasticsearch.client</groupId> <artifactId>elasticsearch-rest-high-level-client</artifactId> </exclusion> <exclusion> <groupId>org.elasticsearch</groupId> <artifactId>elasticsearch</artifactId> </exclusion> </exclusions> </dependency> <!-- elasticsearch --> <dependency> <groupId>org.elasticsearch</groupId> <artifactId>elasticsearch</artifactId> <version>${elasticsearch.version}</version> </dependency> <dependency> <groupId>org.elasticsearch.client</groupId> <artifactId>elasticsearch-rest-high-level-client</artifactId> <version>${elasticsearch.version}</version> </dependency></dependencies>

文檔類Document

arduino復(fù)制代碼@Datapublic class Document { /** * es中的唯一id */ private String id; /** * 文檔標題 */ private String title; /** * 文檔內(nèi)容 */ private String content;}

DocumentMapper

csharp復(fù)制代碼public interface DocumentMapper extends BaseEsMapper<Document> {}

EsDocumentController

typescript復(fù)制代碼@RestController@RequiredArgsConstructor(onConstructor = @__(@Autowired))public class EsDocumentController { private final DocumentMapper documentMapper; @GetMapping("/insert") public Integer insert() { // 初始化-> 新增數(shù)據(jù) Document document = new Document(); document.setId("1"); document.setTitle("austin"); document.setContent("austin-framework-elasticsearch"); return documentMapper.insert(document); } @RequestMapping("/update") public Integer update() { // 更新 Document document = new Document(); document.setId("1"); document.setContent("updated content!"); return documentMapper.updateById(document); } @GetMapping("/search") public List<Document> search() { // 查詢出所有標題為austin的文檔列表 LambdaEsQueryWrapper<Document> wrapper = new LambdaEsQueryWrapper<>(); wrapper.eq(Document::getTitle, "austin"); return documentMapper.selectList(wrapper); } @DeleteMapping("/delete") public Integer delete() { // 根據(jù)ID刪除 LambdaEsQueryWrapper<Document> esQueryWrapper = new LambdaEsQueryWrapper<>(); esQueryWrapper.eq(Document::getId, "1"); return documentMapper.delete(esQueryWrapper); }}

applcation.properties

ini復(fù)制代碼server.port=26686spring.application.name=framework-elasticsearchspring.datasource.url=jdbc:mysql://127.0.0.1:3306/jeecg-boot?characterEncoding=UTF-8&useUnicode=true&useSSL=false&tinyInt1isBit=false&allowPublicKeyRetrieval=true&serverTimezone=Asia/Shanghaispring.datasource.username=rootspring.datasource.password=rootspring.datasource.driver-class-name=com.mysql.cj.jdbc.Drivereasy-es.address=127.0.0.1:9200easy-es.enable=trueeasy-es.username=elasticeasy-es.password=

3?? 執(zhí)行CRUD操作

訪問：http://localhost:26686/insert 插入條數(shù)據(jù)，接著訪問：http://localhost:26686/search 根據(jù)title 字段查詢文檔信息。

總結(jié)

實際上，Easy-Es還有很多拓展功能，比如：混合查詢、原生查詢、分頁查詢、嵌套查詢、Join父子類型、獲取DSL語句，同時也包含很多高階語法：查詢字段過濾、排序、聚合查詢、分詞查詢、權(quán)重、高亮查詢、GEO地理位置查詢等等功能。

鏈接：https://juejin.cn/post/7207410405785337916