資料字典是系統中基本的必不可少的功能，在多種多樣的系統中，資料字典表的設計都大同小異。但是使用方式確是多種多樣，設計好一套易用的資料字典功能模組，可以使開發事半功倍。
常用的資料字典使用方式：
- 直接在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) {
// 臨時儲存資料字典map
Map<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、Object
if (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;
}
// 獲取當前物件所有的field
Field[] 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結果，則這裡返回null
Class 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屬性或者欄位名稱，獲取字典編碼code
String 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>處理
*/
@FunctionalInterface
public 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 {
// dictCode
dictCode: string;
// dictList
dictList?: [];
// filterMap
filterMap?: {};
}
// DictMap
export interface DictMap {
// dictList
dictMap: {};
}
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 label
labelField: 'dictName',
// use id as value
valueField: 'dictCode',
},
},
......
資料字典在系統中的使用非常頻繁，所以在設計和使用時，既要保證實時更新獲取最新配置，又要保證不能引發系統效能問題。在系統設計的時候，既要考慮到後臺資料字典轉換，還需要考慮到前端資料字典轉換，這兩種轉換方式在使用過程中，我們根據具體業務需求和使用條件具體選擇其中一種即可。