Easy-ES项目避坑指南：从版本兼容到字段类型的最佳实践

Easy-ES项目避坑指南：从版本兼容到字段类型的最佳实践

【免费下载链接】easy-es 项目地址: https://gitcode.com/gh_mirrors/eas/easy-es

前言

在使用任何技术框架时，了解其最佳实践和常见陷阱都是至关重要的。本文将深入探讨Easy-ES（一个简化Elasticsearch操作的开源框架）在使用过程中需要注意的关键点，帮助开发者避免常见错误，提高开发效率。

一、版本兼容性问题

1.1 Elasticsearch版本选择

Easy-ES底层基于Elasticsearch官方RestHighLevelClient 7.10版本开发，因此对ES版本的兼容性有特定要求：

• 最佳兼容版本：ES 7.10.x
• 兼容范围：整个ES 7.x系列版本都能良好运行
• 注意事项：虽然7.x系列都能兼容，但建议尽量使用7.10.x版本以获得最佳稳定性

1.2 Spring Boot版本选择

Easy-ES内置的Spring Boot版本为2.5.4，建议开发者遵循以下版本策略：

• 推荐版本：Spring Boot 2.5.4（与框架内置版本一致）
• 兼容范围：2.3.x至2.6.x版本测试通过
• 注意事项：
  • 低于2.3.x或高于2.6.x的版本未经全面测试
  • 框架对Spring Boot的依赖较少，但版本一致性可以避免潜在的类冲突问题

二、ES字段类型深度解析

2.1 Keyword类型 vs Text类型

Keyword类型特点：

• 类比MySQL中的普通字段
• 适用场景：
  • 精确匹配（eq查询）
  • 模糊查询（左模糊、右模糊、全模糊）
  • 排序和聚合操作
• EE API对应：eq(), like(), distinct()等

Text类型特点：

• 支持分词查询
• 必须指定分词器（否则使用ES默认分词器，效果通常不理想）
• EE API对应：match()等

常见问题排查：

1. 查询无结果时，首先检查字段类型是否匹配
2. 使用match查询时，检查分词器是否能正确分出目标词汇

2.2 双类型字段（KEYWORD_TEXT）

当字段需要同时支持keyword和text类型操作时：

@TableField(fieldType = FieldType.KEYWORD_TEXT)
private String combinedField;

查询方式差异：

• 作为keyword查询：字段名.keyword
• 作为text查询：直接使用原字段名

2.3 替代方案：字段冗余

对于需要两种查询方式的字段，可以采用冗余策略：

• 创建两个字段，值相同
• 分别标注为keyword和text类型
• 查询时根据需要选择对应字段

三、ID字段的特殊处理

3.1 ID字段的必要性

Easy-ES中ID字段是强制要求的，因为：

• 框架核心功能（如selectById, update, deleteById等）依赖ID字段
• ES本身也要求每个文档必须有唯一ID

3.2 ID字段的配置方式

public class Document {
    @TableId(type = IdType.CUSTOMIZE)
    private String id; // 支持任意数据类型
}

注意事项：

1. 不加@TableId注解：使用ES自动生成的ID
2. insert操作的幂等性：当ID已存在时，insert实际执行更新操作

四、与MyBatis-Plus的共存策略

4.1 隔离扫描路径

关键配置原则：

• 将MP的Mapper和EE的Mapper放在不同包路径下
• 在配置中分别指定各自的扫描路径

4.2 配置示例

mybatis-plus:
  mapper-locations: classpath:com/yourpackage/mapper/mp/*.xml
  
easy-es:
  mapper-locations: classpath:com/yourpackage/mapper/ee/*.xml

冲突原理：两者尝试注册同名Bean但底层实现不同，导致启动失败

五、查询条件构建的注意事项

5.1 AND/OR操作的特殊性

与MySQL/MP的平铺式条件不同，ES使用树形查询结构：

• AND条件：默认情况下多个条件会以AND连接
• OR条件：需要显式使用or()方法构建
• 复杂嵌套：支持条件组的嵌套组合

最佳实践：先构建简单查询，逐步复杂化，利用IDE的代码提示功能

六、其他实用建议

1. 索引管理：首次启动时建议开启自动创建索引功能，但生产环境应预先设计好mapping
2. 分页查询：深度分页避免使用from/size，考虑使用search_after
3. 性能优化：合理使用索引别名和模板，便于后续索引变更

结语

掌握这些避坑指南后，开发者可以更加高效地使用Easy-ES框架。建议在实际项目中先进行小规模验证，再逐步扩大使用范围。随着对框架理解的深入，可以进一步探索其高级特性，如自定义拦截器、扩展插件等功能。

【免费下载链接】easy-es 项目地址: https://gitcode.com/gh_mirrors/eas/easy-es