SpringCloud微服务实战——搭建企业级开发框架（四十九）：数据字典注解的设计与实现

  数据字典是系统中基本的必不可少的功能，在多种多样的系统中，数据字典表的设计都大同小异。但是使用方式确是多种多样，设计好一套易用的数据字典功能模块，可以使开发事半功倍。

常用的数据字典使用方式：

• 直接在SQL语句中LEFT JOIN （当然是不推荐这样用的）
• 查询出原始数据，然后再根据原始数据需要的字典编码，批量查询字典表，并赋值到原始数据的字典值字段。
• 后台提供通用数据字典接口，前端根据需求统一查询数据字典数据并缓存在前台。当业务返回后台原始数据时，前台通过类似于Filter（VUE）功能，进行字典值对应。
• 自定义数据字典注解，当接口返回原始数据时，通过切面分析返回对象中的数据字典字段，并将数据字典赋值到数据字典值字段。
• 提供数据字典通用工具，手动处理单个或批量需要进行数据字典转换的数据。

  我们为了更好的满足多样的业务需求，那么我们肯定是需要支持多种多样的方式，来实现数据字典转换的功能，接下来，我们以1注解+2工具+3前端转换的方式来支持数据字典转换。三种方式相辅相成、可以单独使用，也可以结合起来使用。

• 可注解在Controller
• 可注解在Service
• 支持的集合类型：List、Set、Queue ，引用类型：Array一维数组
• 单独的bean支持递归赋值，不支持复杂数据递归
• 后台提供通用数据字典接口，前端页面提供通用转换方法。
• 只注解在普通字段上，不要注解到复杂对象上

数据字典转换流程：

1、在Service或者Controller添加@DictAuto注解，用于切面判断此方法是需要进行数据字典转换的方法。
2、切面发现此方法是需要数据字典转换的方法之后，那么解析方法的返回参数，返回参数有多种数据类型，这里只处理集合类型：List、Set、Queue ，引用类型：Array一维数组还有普通对象类型（自定义实体bean）。
3、无论是集合类型还是普通对象类型都需要进行遍历、递归等操作，因为List里面是普通对象，对象中也有可能是集合类型。（此处需要注意，请不要在对象中的字段嵌套自己，这样会造成死循环。当然，对象中可以嵌套自己的对象类型，可以引用非自己的对象实例，因为递归操作中，我们会判断如果是null，那么终止递归）
4、对返回类型进行递归时，通过注解获取到数据字典类型（system、business等）、数据字典CODE（一级数据字典CODE，作为数据字典的分类），通过此条件去Redis数据库查询数据字典列表。将查询的数据字典列表存储在Map中。在循环遍历过程中，增加判断，如果Map中有了，那么不再查询Redis数据库，而是直接从Map中取。
5、在遍历递归对象的同时，根据数据字典注解，获取本对象中用于映射数据字典的字段值作为数据字典的CODE值（二级数据字典CODE，对应具体的数据字典），然后赋值到数据字典值上。

一、通过注解实现数据字典转换功能

1、新增数据字典注解定义

package com.gitegg.platform.base.annotation.dict;import java.lang.annotation.*;/*** 数据字典注解，注解在方法上，自动设置返回参数的字典数据* 1、可以注解在 service和 controller上，只注解返回值，支持引用类型和常用的集合类型* 2、具体的实体类中，如果是引用类型，那么递归赋值* 3、支持的集合类型：List Set Queue ，引用类型：Array一维数组，普通对象类型（自定义实体bean）。* @author GitEgg*/
@Target({ ElementType.METHOD })
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface DictAuto {
}

package com.gitegg.platform.base.annotation.dict;import java.lang.annotation.*;/*** 数据字典注解，注解在字段上* 如果dictCode为空，且此字段是对象类型，那么表示此字段对象中拥有字典类型，* 也就是只有注解了此字段的数据才会去递归设置字典值，不去随便做无所谓的遍历** @author GitEgg*/
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface DictField {/*** 数据字典类型 ：系统字典 system 业务字典 business  地区字典 areas  其他字典：直接表名,例： t_sys_role* 1、确定选择哪种类型的数据字典*/String dictType() default "business";/*** 数据字典编码，就是取哪些数据字典的值* 2、确定需要匹配数据字典的集合*/String dictCode() default "";/*** 要最终转换最终数据字典的键，是实体类中的一个字段，通常配置为此字段的定义名称，通过此字段作为key来转换数据字典的值* 3、确定需要把实体中哪个字段转换为字典值*/String dictKey() default "";/*** 如果是自定义表数据时，此字段作为字典code，对应数据表的字段* 4、表中作为数据字典的键*/String dictFiled() default "";/*** 如果是自定义表数据时，此字段作为字典value，对应数据表的字段* 5、表中作为数据字典的值*/String dictValue() default "";
}

2、新增切面，处理数据字典注解

package com.gitegg.platform.boot.aspect;import cn.hutool.core.util.ArrayUtil;
import com.baomidou.mybatisplus.core.metadata.IPage;
import com.gitegg.platform.base.annotation.dict.DictAuto;
import com.gitegg.platform.base.annotation.dict.DictField;
import com.gitegg.platform.base.constant.DictConstant;
import com.gitegg.platform.base.constant.GitEggConstant;
import com.gitegg.platform.base.result.Result;
import com.gitegg.platform.boot.util.GitEggAuthUtils;
import com.gitegg.platform.redis.lock.IDistributedLockService;
import com.google.common.base.Strings;
import com.google.common.collect.Lists;
import jodd.util.StringPool;
import lombok.RequiredArgsConstructor;
import lombok.extern.log4j.Log4j2;
import org.aspectj.lang.annotation.AfterReturning;
import org.aspectj.lang.annotation.Aspect;
import org.springframework.beans.BeanWrapperImpl;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.data.redis.core.RedisTemplate;
import org.springframework.lang.NonNull;
import org.springframework.stereotype.Component;import java.lang.reflect.Field;
import java.lang.reflect.ParameterizedType;
import java.lang.reflect.Type;
import java.math.BigDecimal;
import java.util.*;
import java.util.function.Consumer;/*** 数据字典切面* @author GitEgg* @date 2022-4-10*/
@Log4j2
@Component
@Aspect
@RequiredArgsConstructor(onConstructor_ = @Autowired)
@ConditionalOnProperty(name = "enabled", prefix = "dict", havingValue = "true", matchIfMissing = true)
public class DictAspect {/*** 是否开启租户模式*/@Value("${tenant.enable}")private Boolean enable;private final RedisTemplate redisTemplate;/*** 后置通知 解析返回参数，进行字典设置* @AfterReturning 只有存在返回值时才会执行 @After 无论有没有返回值都会执行  所以这里使用 @AfterReturning 只有存在返回值时才执行字典值注入操作* @param dictAuto 注解配置*/@AfterReturning(pointcut = "@annotation(dictAuto)", returning = "returnObj")public void doAfterReturning( DictAuto dictAuto, Object returnObj){// 返回不为null时，进行数据字典处理if (null != returnObj) {doDictAuto(dictAuto, returnObj);}}/*** key的组成为: dict:userId:sessionId:uri:method:(根据spring EL表达式对参数进行拼接)* 此处要考虑多种返回类型，集合类型、引用类型、对象类型和基本数据类型，这里只处理 集合类型：List Set Queue ，引用类型：Array数组，Array只支持一维数组。* 对于对象中的子对象，为了提升性能，同样需要加@DictField注解才去填充，否则每个子对象都去递归判断，影响性能* 我们要考虑此处的逻辑：* 1、判断返回数据类型，如果是集合类型，那么取出包含实体对象的集合类，然后进行对象解析* 2、如果是对象类型，那么直接进行对象解析* 3、如果是IPage类型，那么取出其中的list数据，判断是否为空，不为空，执行 1 步骤* 4、如果是Result类型，判断Result的data是IPage还是集合类型，分别执行对应的 1 步骤 或 3 步骤，如果不是IPage也不是集合类型，直接执行第 2 步骤* @param dictAuto 注解* @param objectReturn 方法返回值*/private void doDictAuto(@NonNull DictAuto dictAuto, Object objectReturn) {// 临时存储数据字典mapMap<String, Map<Object, Object>> dictMap = new HashMap<>();this.translationObjectDict(objectReturn, dictMap);}/*** 找到实际的对象或对象列表* 此处要考虑多种返回类型，集合类型、引用类型、对象类型和基本数据类型，这里只处理 集合类型：List Set Queue ，引用类型：Array一维数组。* @param objectReturn* @param dictMap* @return*/private void translationObjectDict(Object objectReturn, Map<String, Map<Object, Object>> dictMap) {if (Objects.isNull(objectReturn)){return;}// 判断返回值类型是Result、IPage、List、Objectif (objectReturn instanceof Result) {Object objectTarget = ((Result) objectReturn).getData();translationObjectDict(objectTarget, dictMap);} else if (objectReturn instanceof IPage) {List<Object> objectTargetList = ((IPage) objectReturn).getRecords();translationObjectDict(objectTargetList, dictMap);} else if (objectReturn instanceof Collection) {((Collection) objectReturn).forEach(object-> translationObjectDict(object, dictMap));} else if (ArrayUtil.isArray(objectReturn)) {// 数组这里需要处理((Collection) objectReturn).forEach(object-> translationObjectDict(object, dictMap));} else {parseObjectFieldCodeValue(objectReturn, dictMap);}}/*** 取出对象中需要进行字典转换的字段** @param targetObj   : 取字段的对象* @param dictMap     : 存储数据字典* @author liam*/private void parseObjectFieldCodeValue(Object targetObj, Map<String, Map<Object, Object>> dictMap) {if (Objects.isNull(targetObj)){return;}// 获取当前对象所有的fieldField[] declaredFields = targetObj.getClass().getDeclaredFields();// 构造填充映射关系Arrays.stream(declaredFields).forEach(field ->// 递归处理parseFieldObjDict(field, targetObj,fieldObj -> parseObjectFieldCodeValue(fieldObj, dictMap),// 解析注解字段信息() -> parseDictAnnotation(targetObj, field, dictMap)));}/*** 解析field对象，对基本数据类型和复杂类型直接根据注解赋值，对于对象或集合类型，继续进行递归遍历** @param field          : 字段对象* @param obj            : 字段所属的obj对象* @param recursiveFunc  : 递归处理方法* @author liam*/private static void parseFieldObjDict(Field field, Object obj, Consumer<Object> recursiveFunc,NestedFunction parseAnnotationFunc) {Class cls = field.getType();// 不处理map数据if (Map.class.isAssignableFrom(cls)) {return;}// 需要数据字典转换的属性：有Dict注解， @DictField只注解在普通字段上，不要注解到复杂对象上if (field.isAnnotationPresent(DictField.class)) {// 分析注解并转换数据字典值parseAnnotationFunc.run();}// 没有注解的属性判断else {try {// 获取字段值且非空处理field.setAccessible(true);Optional.ofNullable(field.get(obj)).ifPresent(fieldValue -> {// 集合类型，如果泛型的类型是JavaBean，继续递归处理if (Collection.class.isAssignableFrom(cls)) {// 如果是list-map结果，则这里返回nullClass generic = getGeneric(obj.getClass(), field.getName());if (null != generic && notInFilterClass(generic)) {// 循环递归处理((Collection) fieldValue).forEach(recursiveFunc::accept);}}// 非基本数据类型else if (notInFilterClass(cls)) {recursiveFunc.accept(fieldValue);}});} catch (Exception e) {log.error(e.getMessage(), e);}}}/*** 获取一个类的属性的泛型；如果没有泛型，则返回null；* P.s 如果有多个，取第一个；如果有多层泛型，也返回null，比如List<Map>** @param cls      :* @param property : 属性名* @author liam*/public static Class getGeneric(Class cls, String property) {try {Type genericType = cls.getDeclaredField(property).getGenericType();// 如果是泛型参数的类型if (null != genericType && genericType instanceof ParameterizedType) {ParameterizedType pt = (ParameterizedType) genericType;Type type = pt.getActualTypeArguments()[GitEggConstant.Number.ZERO];// 这里，type也可能是 ParameterizedType， 直接不考虑if (type instanceof Class) {return (Class) type;}}} catch (Exception e) {log.error(e.getMessage(), e);}return null;}/*** 解析含有注解@DictField并赋值** @param obj         : 对象* @param field       : 字段* @param dictMap     : 数据字典* @author liam*/private void parseDictAnnotation(Object obj, Field field, Map<String, Map<Object, Object>> dictMap) {// 读取注解信息，获取编码类型DictField dictField = field.getAnnotation(DictField.class);String fieldName = field.getName();// 根据Dict的codeName属性或者字段名称，获取字典编码codeString code = getFieldValue(obj, dictField, fieldName);if (!Strings.isNullOrEmpty(code)) {String dictType = dictField.dictType();String dictCode = dictField.dictCode();String dictKey = dictType + StringPool.COLON + dictCode;// 首先判断是否开启多租户String redisDictKey = DictConstant.DICT_TENANT_MAP_PREFIX;if (enable) {redisDictKey += GitEggAuthUtils.getTenantId() + StringPool.COLON + dictKey;} else {redisDictKey = DictConstant.DICT_MAP_PREFIX + dictKey;}Map<Object, Object> dictKeyValue = dictMap.get(redisDictKey);// 首先从dictMap中获取值，如果没有，再从Redis数据库中获取值if (null == dictKeyValue) {// 从Redis数据库获取值Map<Object, Object> dictCodeMap = redisTemplate.opsForHash().entries(redisDictKey);dictMap.put(redisDictKey, dictCodeMap);}if (null != dictKeyValue.get(code)){try {// 给Field赋值最终的数据字典field.setAccessible(true);field.set(obj, dictKeyValue.get(code));} catch (Exception e) {log.error(e.getMessage(), e);}}}}/*** 根据Dict的codeName属性或者字段名称，获取字段值* 注意：如果当前字段没有以Name结尾，那就取当前字段的值；也就是根据当前字段的值转换。** @param obj            : 对象* @param dictField      : 字段注解对象* @param fieldName      : 字段名称* @return java.lang.String* @author liam*/private String getFieldValue(Object obj, DictField dictField, String fieldName) {String codeName = dictField.dictKey();if (Strings.isNullOrEmpty(codeName)) {// 如果当前字段是Name结尾，进行截取；否则取当前字段名称int endNameIndex = fieldName.lastIndexOf(DictConstant.NAME_SUFFIX);if (endNameIndex != -1) {codeName = fieldName.substring(0, endNameIndex);} else {codeName = fieldName;}}return getPropertyValue(obj, codeName);}/*** 获取对象里指定属性的值，并转化为字符串** @param obj          : 对象* @param propertyName : 对象里面的属性名称* @author liam*/private String getPropertyValue(Object obj, String propertyName) {BeanWrapperImpl beanWrapper = new BeanWrapperImpl(obj);if (beanWrapper.isReadableProperty(propertyName)) {Object propertyValue = beanWrapper.getPropertyValue(propertyName);if (null != propertyValue) {return propertyValue.toString();}}return "";}/*** 判断不在过滤类(常用基本数据类型)中*/private static boolean notInFilterClass(Class cls) {return !DictConstant.baseTypeList.contains(cls);}/*** 函数式接口：类似freemarker中的<#nested>处理*/@FunctionalInterfacepublic interface NestedFunction {/*** 无参无返回值的方法运行*/void run();}}

二、实现自定义工具，手动进行数据字典转换

比较灵活，选择需要转换的数据即可

三、前端转换数据字典

定义通用接口，首先从缓存查，缓存没有再查询数据库，在登录后重置数据字典。

1、前端新增dictUtils，用于dictCode的查询、缓存等操作

import { getAuthCache, setAuthCache } from '/@/utils/auth';
import { DICT_SYSTEM_CACHE_KEY, DICT_BUSSINESS_CACHE_KEY } from '/@/enums/cacheEnum';
import { listDict, batchListDict } from '/@/api/system/base/dict';
import { listDictBusiness, batchListDictBusiness } from '/@/api/system/base/dictBusiness';// System default cache time
export const DICT_CACHE_TIME = 60 * 60 * 2 * 1000;// Dict
export interface Dict {// dictCodedictCode: string;// dictListdictList?: [];// filterMapfilterMap?: {};
}// DictMap
export interface DictMap {// dictListdictMap: {};
}export function getDictCacheOnly(dict: Dict) {let dictMap = getAuthCache(DICT_SYSTEM_CACHE_KEY) as any;if (!dictMap) {dictMap = {};}if (dictMap[dict.dictCode]) {return dictMap[dict.dictCode] as Dict;} else {getDict(dict).then(function (dictReturn) {dictMap[dict.dictCode] = dictReturn;// 数据字典默认缓存2小时，重新登陆后失效setAuthCache(DICT_SYSTEM_CACHE_KEY, dictMap);});return dict;}
}export function getDictBusinessCacheOnly(dict: Dict) {let dictBusinessMap = getAuthCache(DICT_BUSSINESS_CACHE_KEY) as any;if (!dictBusinessMap) {dictBusinessMap = {};}if (dictBusinessMap[dict.dictCode]) {return dictBusinessMap[dict.dictCode] as Dict;} else {getDictBusiness(dict).then(function (dictReturn) {dictBusinessMap[dict.dictCode] = dictReturn;// 数据字典默认缓存2小时，重新登陆后失效setAuthCache(DICT_BUSSINESS_CACHE_KEY, dictBusinessMap);});return dict;}
}export async function getDictCache(dict: Dict) {let dictMap = getAuthCache(DICT_SYSTEM_CACHE_KEY) as any;if (!dictMap) {dictMap = {};}if (dictMap[dict.dictCode]) {return dictMap[dict.dictCode] as Dict;} else {const dictReturn = await getDict(dict);dictMap[dict.dictCode] = dictReturn;// 数据字典默认缓存2小时，重新登陆后失效setAuthCache(DICT_SYSTEM_CACHE_KEY, dictMap);return dictReturn;}
}export async function getDictBusinessCache(dict: Dict) {let dictBusinessMap = getAuthCache(DICT_BUSSINESS_CACHE_KEY) as any;if (!dictBusinessMap) {dictBusinessMap = {};}if (dictBusinessMap[dict.dictCode]) {return dictBusinessMap[dict.dictCode] as Dict;} else {const dictReturn = await getDictBusiness(dict);dictBusinessMap[dict.dictCode] = dictReturn;// 数据字典默认缓存2小时，重新登陆后失效setAuthCache(DICT_BUSSINESS_CACHE_KEY, dictBusinessMap);return dictReturn;}
}// 批量初始化系统字典
export async function initDictCache(dictCodeList: string[]) {let dictMap = getAuthCache(DICT_SYSTEM_CACHE_KEY) as any;if (!dictMap) {dictMap = {};}const dictResultMap = await batchListDict(dictCodeList);if (dictResultMap) {dictCodeList.forEach(function (dictCode) {if (dictResultMap[dictCode]) {const dict = {} as Dict;dict.dictList = dictResultMap[dictCode];dict.filterMap = {};dict.dictList.forEach((item) => {const itemDict = item as any;dict.filterMap[itemDict.dictCode] = itemDict.dictName;});dictMap[dictCode] = dict;}});// 数据字典默认缓存2小时，重新登陆后失效setAuthCache(DICT_SYSTEM_CACHE_KEY, dictMap);}
}// 批量初始化业务字典
export async function initDictBusinessCache(dictCodeList: string[]) {let dictMap = getAuthCache(DICT_BUSSINESS_CACHE_KEY) as any;if (!dictMap) {dictMap = {};}const dictResultMap = await batchListDictBusiness(dictCodeList);if (dictResultMap) {dictCodeList.forEach(function (dictCode) {if (dictResultMap[dictCode]) {const dict = {} as Dict;dict.dictList = dictResultMap[dictCode];dict.filterMap = {};dict.dictList.forEach((item) => {const itemDict = item as any;dict.filterMap[itemDict.dictCode] = itemDict.dictName;});dictMap[dictCode] = dict;}});// 数据字典默认缓存2小时，重新登陆后失效setAuthCache(DICT_BUSSINESS_CACHE_KEY, dictMap);}
}export async function getDict(dict: Dict) {const dictList = await listDict(dict.dictCode);if (dictList && dictList.length > 0) {dict.dictList = dictList;dict.filterMap = {};dictList.forEach((item) => {dict.filterMap[item.dictCode] = item.dictName;});}return dict;
}export async function getDictBusiness(dict: Dict) {const dictBusinessList = await listDictBusiness(dict.dictCode);if (dictBusinessList && dictBusinessList.length > 0) {dict.dictList = dictBusinessList;dict.filterMap = {};dictBusinessList.forEach((item) => {dict.filterMap[item.dictCode] = item.dictName;});}return dict;
}

2、登录成功后重新数据字典缓存，也就是每次在后台数据字典修改之后，前端需要重新登录才能刷新数据字典缓存。

      // 重新初始化系统数据字典setAuthCache(DICT_SYSTEM_CACHE_KEY, {});// 重新初始化业务数据字典setAuthCache(DICT_BUSSINESS_CACHE_KEY, {});

3、在需要用到数据字典时，直接调用即可，根据utils的实现，首先会从缓存查询，如果缓存中没有，才会从后台查询。

import { getDictBusinessCache } from '/@/utils/gitegg/dictUtils';
......{label: '状态',field: 'status',component: 'ApiRadioGroup',required: true,defaultValue: '2',componentProps: {api: getDictBusinessCache,params: { dictCode: 'USER_STATUS' },resultField: 'dictList',// use name as labellabelField: 'dictName',// use id as valuevalueField: 'dictCode',},},
......

  数据字典在系统中的使用非常频繁，所以在设计和使用时，既要保证实时更新获取最新配置，又要保证不能引发系统性能问题。在系统设计的时候，既要考虑到后台数据字典转换，还需要考虑到前端数据字典转换，这两种转换方式在使用过程中，我们根据具体业务需求和使用条件具体选择其中一种即可。

GitEgg-Cloud是一款基于SpringCloud整合搭建的企业级微服务应用开发框架，开源项目地址:

Gitee: https://gitee.com/wmz1930/GitEgg

GitHub: https://github.com/wmz1930/GitEgg

欢迎感兴趣的小伙伴Star支持一下。