概念

BeanUtils

核心工具,提供实体拷贝的相关方法,支持属性映射、类型转换和批量拷贝等功能。

拷贝过程可能抛出BeanPropertyCopyException

BeanUtils.ConcurrencyManager

提供开启和关闭多线程处理模式和获取当前处理模式的方法:

  • public static boolean isMultiThreadProcessing():获取当前处理模式

  • public static void setMultiThreadProcessing(boolean value):设置处理模式

BeanPropertyCopyException

属性拷贝过程中发生的异常。

属性说明:

  • propertyName:发生异常的属性名

  • sourceObject:源对象

@Mapping

核心注解,配置字段的映射关系、转换器等内容。

属性说明:

  • targetClass:映射目标类类型,用于指定此注解的作用目标,详见配置说明

  • targetClassName:映射目标类全路径名,详见配置说明

  • field:映射的字段名,支持嵌套的属性,默认为该字段名。

  • ignore:是否忽略该字段,默认为false

  • oneway:是否为单向绑定,配置为true时,配置只在其他对象拷贝到本对象时生效,默认为false

  • datePattern:日期格式,字符串和日期字段映射时需要配置。

  • converter:转换器的类型,在其他对象拷贝到本对象时生效,可以配置多个转换器。

  • converterClassName:转换器类的全路径名,详见配置说明

  • inverseConverter:反向转换器的类型,在本对象拷贝到其他对象时生效,可以配置多个转换器。

  • inverseConverterClassName:反向转换器类的全路径名,详见配置说明

@Nested

标记字段为嵌套的对象,需要指定嵌套对象以及对应映射对象的类型。

属性说明:

  • targetClass:映射目标类类型,用于指定此注解的作用目标,详见配置说明

  • targetClassName:映射目标类全路径名,详见配置说明

  • thisClass:本字段的类型,作用于集合时,应为集合中元素的类型

  • thisClassName:本字段类的全路径名,详见配置说明

  • thatClass:映射字段的类型,作用于集合时,应为集合中元素的类型

  • thatClassName:映射字段类的全路径名,详见配置说明

@DictMapping

字典类映射使用的注解,用于代替原有的AbstractDictionaryConverter的方案。

属性说明:

  • targetClass:映射目标类类型,用于指定此注解的作用目标,详见配置说明

  • targetClassName:映射目标类全路径名,详见配置说明

  • key:数据处理类参数(字典分类或者其他)

  • resolver:数据处理类类型

  • resolverClassName:数据处理类全路径名,详见配置说明

  • mode:数据加载模式(批量/单条),默认为FetchMode.BATCH(批量)

  • cacheable:是否启用数据缓存,默认为true

  • async:是否异步更新缓存数据(加载仍然为同步),默认为true

  • ttl:缓存的存活时间(秒),正整数,默认为60

    • 如果async=true

      • 缓存写入超过ttl则标记为待刷新(下次拷贝时使用旧数据,并异步加载新的字典数据)

      • 缓存写入超过ttl两倍则标记为已过期(下次拷贝时需要先同步加载字典数据)

    • 如果async=false

      • 缓存写入超过ttl则标记为已过期(下次拷贝时需要先同步加载字典数据)

  • bidirectional:是否是双向查找(双向查找提供从value查找key的能力,如果key和value可能重复则建议配置为false),默认为true

数据加载模式(DictMapping.FetchMode):

  • SINGLE: 单条,根据源值直接查找映射结果,业务映射(如用户→部门)可采用此模式

  • BATCH: 批量(默认),加载所有映射数据然后从中查找结果,字典表数据建议采用此模式

两种模式的对比:

  • 时效性:批量模式所有数据缓存生命周期相同;单条模式每条数据有独立的生命周期。

  • 一致性:在默认的批量模式下,如果映射数据有新增,则必须等待缓存失效之后才能加载新增数据(在此期间新增的数据映射结果均为null);单条模式下,如果映射数据有新增,缓存中查找不到结果会触发一次接口调用获取新的映射数据。

  • 性能:批量模式一次加载所有数据,因此一般来说性能优于单条模式;但是在存在热点数据的场景下(个别数据访问频率明显高于其他同类数据),单条模式效率更高(传输量小)。

需要配合DictDataResolver的实现类使用,参见下面的DictDataResolver接口说明。

DictDataResolver

字典表数据加载适配器,一般来说依赖于某个服务,负责获取数据并转换为字典数据。

  1. @DictMapping配置mode=FetchMode.BATCH时,使用Map resolve(String key);方法,参数是@DictMapping中配置的key属性,返回字典映射所有数据的Map<Object, Object>

  2. @DictMapping配置mode=FetchMode.SINGLE时,使用Object resolveSingle(String key, Object source);方法,参数是@DictMapping中配置的key属性以及映射源属性的值,返回映射结果。

resolveSingle方法提供默认实现:调用resolve方法获取所有字典信息,然后遍历获取映射结果。如果@DictMapping(mode=FetchMode.SINGLE),建议覆盖默认的实现以优化性能。

TypeConverter

类型转换器接口,自定义的转换器需要实现此接口。使用者需要自行处理空值和异常(统一捕获异常并转换为TypeConvertException)。

AbstractTypeConverter

类型转换器的抽象类,封装了空值判断和异常处理逻辑。默认对于空值会直接返回,使用者如果对空值有特殊的转换需求,可以覆盖convertNull()方法返回期望的值。

AbstractToStringConverter

对象/集合转换为单个字符串的转换器抽象类,作用于集合时,转换器会将每个元素的处理结果用getDelimiter()方法返回的分隔符分隔(默认分隔符为",")。

使用者需要实现itemToString(Object item)方法,实现对象/集合元素转换为字符串的逻辑。可以根据需要重写getDelimiter()方法。

AbstractListConverter

集合转换为List的转换器抽象类,针对一个给定的集合,遍历其中的元素进行转换,然后返回一个目标对象的List(使用ArrayList实现)。

使用者需要实现convertItem(Object item)方法,实现集合中单个元素的转换逻辑。

AbstractSetConverter

集合转换为Set的转换器抽象类,针对一个给定的集合,遍历其中的元素进行转换,然后返回一个目标对象的Set(使用HashSet实现)。

使用者需要实现convertItem(Object item)方法,实现集合中单个元素的转换逻辑。

AbstractDictionaryConverter

字典表数据的转换器抽象类,提供字典类数据的双向转换功能。

使用者需要实现getDictionary()方法,返回Map<Object, Object>类型的字典数据。

从1.7.0版本开始标记为@Deprecated,字典映射请使用@DictMappingDictDataResolver

Last updated