本文将介绍 Easy-Es 注解包相关类详解（更多详细描述可点击查看源码注释）

注解类包源码：👉 easy-es-annotation (opens new window)

@EsMapperScan (opens new window)

• 描述：mapper扫描注解,功能与MP的@MapperScan一致

• 使用位置：Springboot启动类

@EsMapperScan("cn.easy-es-mapper")
public class Application{
    // 省略其它...
}

属性	类型	必须指定	默认值	描述
value	String	是	""	自定义mapper所在包全路径

温馨提示

由于EE和MP对Mapper的扫描都是采用Springboot的doScan，而且两套系统互相独立，所以在扫描的时候没有办法互相隔离,因此如果您的项目同时有用到EE和MP，您需要将EE的Mapper和MP的Mapper放在不同的包下，否则项目将无法正常启动。

@IndexName (opens new window)

• 描述：索引名注解，标识实体类对应的索引 对应MP的@TableName注解,在v0.9.40之前此注解为@TableName.

• 使用位置：实体类

@IndexName
public class Document {
    // 省略其它字段
}

属性	类型	必须指定	默认值	描述
value	String	否	""	索引名，可简单理解为MySQL表名
shardsNum	int	否	1	索引分片数
replicasNum	int	否	1	索引副本数
aliasName	String	否	""	索引别名
keepGlobalPrefix	boolean	否	false	是否保持使用全局的 tablePrefix 的值，与MP用法一致
child	boolean	否	false	是否子文档
childClass	Class	否	DefaultChildClass.class	父子文档-子文档类
maxResultWindow	int	否	10000	分页返回的最大数据量,默认值为1万条,超出推荐使用searchAfter或滚动查询等方式,详见拓展功能章节. 当此值调整至大于1W后,需要重建索引并同步开启配置文件中的enable-track-total-hits=true方可生效

动态索引名称支持 如果你的索引名称是不固定的,我们提供了两种方式可修改CRUD时的索引名称

• 调用mapper.setCurrentActiveIndex(String indexName)方法,此处的mapper为你自定义的mapper,如documentMapper,通过此API修改索引名称后,全局生效.
• 在对应的参数中指定当前操作作用的索引,例如 wrapper.index(String indexName),通过此API修改索引名称后,仅作用于该wrapper对应的操作,粒度最细.

温馨提示

• 当您想直接把类名当作索引名，且并不需要对索引进行其它配置时，可省略此注解
• 通过注解指定的索引名称优先级最高,指定了注解索引,则全局配置和自动生成索引不生效,采用注解中指定的索引名称. 优先级排序: 注解索引>全局配置索引前缀>自动生成
• keepGlobalPrefix选项,(0.9.4+版本才支持)默认值为false,是否保持使用全局的 tablePrefix 的值:
  • 既配置了全局tablePrefix,@TableName注解又指定了value值时,此注解选项才会生效,如果其值为true,则框架最终使用的索引名称为:全局tablePrefix+此注解的value,例如:dev_document.
  • 此注解选项用法和MP中保持一致.
• 其中shardNum为分片数,replicasNum为副本数,如果不指定,默认值均为1

@IndexId (opens new window)

• 描述：ES主键注解,在v0.9.40之前此注解为@TableId.
• 使用位置：实体类中被作为ES主键的字段, 对应MP的@TableId注解

public class Document {
    @IndexId
    private String id;
    // 省略其它字段
}

属性	类型	必须指定	默认值	描述
value	String	否	"_id"	主键字段名
type	Enum	否	IdType.NONE	指定主键类型

温馨提示

• 当您字段命名为id且类型为String时，且不需要采用UUID及自定义ID类型时，可省略此注解
• 由于es对id的默认名称做了处理(下划线+id):_id,所以EE已为您屏蔽这步操作,您无需在注解中指定,框架也会自动帮您完成映射.
• Id的生成类型支持以下几种:
  • IdType.NONE: 由ES自动生成,是默认缺省时的配置,无需您额外配置 推荐
  • IdType.UUID: 系统生成UUID,然后插入ES (不推荐)
  • IdType.CUSTOMIZE: 由用户自定义,用户自己对id值进行set,如果用户指定的id在es中不存在,则在insert时就会新增一条记录,如果用户指定的id在es中已存在记录,则自动更新该id对应的记录.

优先级: 注解配置的Id生成策略>全局配置的Id生成策略

@IndexField (opens new window)

• 描述：ES字段注解, 对应MP的@TableField注解,在v0.9.40之前此注解为@TableField
• 使用位置：实体类中被作为ES索引字段的字段
• 使用场景举例：

1. 实体类中的字段并非ES中实际的字段,比如把实体类直接当DTO用了,加了一些ES中并不存在的无关字段,此时可以标记此字段,以便让EE框架跳过此字段,对此字段不处理.
2. 字段的更新策略,比如在调用更新接口时,实体类的字段非Null或者非空字符串时才更新,此时可以加字段注解,对指定字段标记更新策略.
3. 需要对类型为text或keyword_tex字段聚合时,可指定其fieldData=true,否则es会报错.
4. 对指定字段进行自定义命名,比如该字段在es中叫wu-la,但在实体model中叫ula,此时可以在value中指定value="wu-la".
5. 在自动托管索引模式下,可指定索引分词器及索引字段类型.
6. 在自动托管索引模式下,可指定索引中日期的format格式.
7. ...

使用示例:

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;
}

属性	类型	必须指定	默认值	描述
value	String	否	""	字段名
exist	boolean	否	true	字段是否存在
fieldType	Enum	否	FieldType.NONE	字段在es索引中的类型
fieldData	boolean	否	false	text类型字段是否支持聚合
analyzer	String	否	Analyzer.NONE	索引文档时用的分词器
searchAnalyzer	String	否	Analyzer.NONE	查询分词器
strategy	Enum	否	FieldStrategy.DEFAULT	字段验证策略
dateFormat	String	否	""	es索引中的日期格式,如yyyy-MM-dd
nestedClass	Class	否	DefaultNestedClass.class	嵌套类
parentName	String	否	""	父子文档-父名称
childName	String	否	""	父子文档-子名称
joinFieldClass	Class	否	JoinField.class	父子文档-父子类型关系字段类

温馨提示

• 更新策略一共有3种:
  • NOT_NULL: 非Null判断,字段值为非Null时,才会被更新
  • NOT_EMPTY: 非空判断,字段值为非空字符串时才会被更新
  • IGNORE: 忽略判断,无论字段值为什么,都会被更新

其中场景四和场景五仅在索引自动托管模式下生效,如果开启了手动处理索引模式,则需要用户通过手动调用我提供的API传入相应的分词器及日期格式化参数进行索引的创建/更新.

@Score (opens new window)

• 描述：得分注解
• 使用位置：实体类中被作为ES查询得分返回的字段
• 使用场景举例：比如需要知道本次匹配查询得分有多少时,可以在实体类中添加一个类型为Float/float的字段,并在该字段上添加@Score注解,在后续查询中,若es有返回当次查询的得分,则此得分会自动映射至此字段上

属性	类型	必须指定	默认值	描述
decimalPlaces	int	否	0	得分保留小数位,默认不处理,保持es返回的得分值

@Distance (opens new window)

• 描述：距离注解
• 使用位置：实体类中被作为ES地理位置排序距离值的返回字段
• 使用场景举例：比如需要知道按距离由近及远查询后的数据,实际距离某一坐标有多远,可以在实体类中添加一个类型为Double/double的字段,并在该字段上添加@Distance注解,在后续查询中,若es有返回距离,则此距离会自动映射至此字段上

属性	类型	必须指定	默认值	描述
decimalPlaces	int	否	0	距离保留小数位,默认不处理,保持es返回的距离值
sortBuilderIndex	int	否	0	排序字段在sortBuilders中的位置, 默认为0,若有多个排序器,则指定为其所在位置

其它注解

除了上面这几个高频注解，项目中偶尔还会用到一些其它注解，比如高亮注解@HighLight，比如拦截器注解@Intercepts等注解，我们会在后面具体的章节详细介绍，此处仅列出几个必须掌握的注解，其它注解按需学习即可。