文章目录JEECG Boot——数据字典管理一、核心定位与设计理念1. 核心价值2. 整体架构分层二、底层数据模型与存储设计1. 字典主表sys_dict2. 字典项从表sys_dict_item三、后端核心能力体系1. 核心注解Dict 字典翻译注解1.1 注解核心参数1.2 两大核心用法1普通字典用法系统内置字典2表字典用法动态业务字典1.3 配套校验注解DictVerify2. 翻译核心DictAspect AOP切面2.1 核心工作机制2.2 关键特性3. 缓存机制3.1 后端Redis缓存3.2 前端本地缓存4. 核心API接口5. 高级扩展能力四、前端核心组件JDictSelectTag 全解析1. 组件核心定位2. 核心API参数3. 基础用法示例3.1 普通字典用法3.2 表字典用法动态业务表数据3.3 带过滤条件的表字典用法3.4 不同渲染类型用法4. 高级用法4.1 表单校验集成4.2 动态加载与手动获取字典数据4.3 表格列自定义渲染五、全链路工作流程六、最佳实践与规范1. 字典设计规范2. 性能优化最佳实践3. 安全规范七、常见问题与解决方案1. Dict注解翻译不生效2. 字典修改后前端显示旧数据3. JDictSelectTag组件数值回显失败4. 表字典查询报SQL注入错误JEECG Boot——数据字典管理JEECG Boot 数据字典管理是平台核心基础能力通过后端统一配置注解自动翻译前端组件化渲染的全链路设计解决企业级应用中枚举值、状态码、业务常量等静态数据的统一管理、动态更新、全局复用问题彻底消除代码硬编码实现一处配置、全系统生效。一、核心定位与设计理念1. 核心价值统一管控集中管理系统内所有静态枚举数据支持可视化增删改查无需修改代码即可调整业务选项自动翻译通过注解实现数据库存储值如1/2与前端展示文本男/女的自动双向转换无需手动写翻译逻辑组件化复用前端封装JDictSelectTag等专用组件一行代码实现字典下拉、单选等渲染大幅降低开发成本高性能保障多层级缓存机制针对读多写少的字典场景做深度优化减少数据库与接口请求压力扩展性极强支持普通字典、动态表字典、多租户、多数据源、多级联动等复杂场景适配各类业务需求2. 整体架构分层JEECG Boot 数据字典体系采用前后端分离的四层架构设计从上到下依次为架构层级核心载体核心能力前端渲染层JDictSelectTag组件、配套工具函数字典数据渲染、表单绑定、值转换、本地缓存接口服务层字典Controller、OpenAPI字典数据查询、管理、缓存刷新、权限控制核心能力层Dict注解、DictAspect切面、缓存服务自动翻译、动态解析、缓存管理、安全校验数据存储层sys_dict主表、sys_dict_item从表字典元数据与字典项数据的持久化存储二、底层数据模型与存储设计JEECG Boot 采用主从表结构实现字典数据的规范化存储两张核心表通过字典ID关联支持多租户、低代码应用隔离。1. 字典主表sys_dict存储字典的元数据信息一个字典编码对应一条主表记录是全局唯一标识。核心字段字段类型字段说明核心约束idvarchar(32)主键ID非空、主键dict_namevarchar(100)字典名称界面展示非空dict_codevarchar(100)字典编码全局唯一调用标识非空、唯一索引descriptionvarchar(500)字典描述-del_flagint(1)逻辑删除标志0未删除 1已删除默认0tenant_idint租户ID多租户隔离-low_app_idvarchar(32)低代码应用ID-2. 字典项从表sys_dict_item存储字典对应的具体选项数据一条主表记录对应多条从表记录支持排序、禁用、颜色标识等扩展能力。核心字段字段类型字段说明核心约束idvarchar(32)主键ID非空、主键dict_idvarchar(32)关联主表的字典ID非空、外键关联item_textvarchar(100)字典项文本前端展示值非空item_valuevarchar(100)字典项值数据库存储值非空sort_orderint排序号控制前端展示顺序默认0statusint(1)状态1启用 0禁用默认1item_colorvarchar(100)字典项颜色标识用于标签、状态展示-三、后端核心能力体系1. 核心注解Dict 字典翻译注解Dict是后端字典能力的核心载体标注在实体类字段上框架通过AOP自动完成字典值的翻译生成字段名_dictText格式的翻译字段。1.1 注解核心参数参数名适用场景说明示例dicCode普通字典对应sys_dict表中的字典编码必填Dict(dicCode sex)dictTable表字典动态从业务表获取字典数据的表名Dict(dictTable sys_user)dicText表字典业务表中作为展示文本的字段名Dict(dicText realname)dicCode表字典业务表中作为存储值的字段名Dict(dicCode id)ds多数据源场景指定表字典所在的数据源名称Dict(ds multi-datasource1)1.2 两大核心用法1普通字典用法系统内置字典适用于系统通用枚举值在字典管理界面配置完成后使用是最常用的场景。/** * 性别1男 2女 * 对应字典编码sex系统会自动翻译生成 sex_dictText 字段 */Dict(dicCodesex)privateIntegersex;2表字典用法动态业务字典适用于需要从业务表动态获取选项的场景无需在字典管理界面配置直接关联业务表数据。/** * 创建人ID关联用户表自动翻译为用户真实姓名 * 格式dictTable表名, dicText展示字段, dicCode存储字段 */Dict(dictTablesys_user,dicTextrealname,dicCodeid)privateStringcreateBy;1.3 配套校验注解DictVerify用于入参合法性校验自动校验前端传入的值是否在字典定义的有效值范围内避免非法数据入库。/** * 用户状态仅允许传入字典user_status中定义的有效值 */DictVerify(dictCodeuser_status,message用户状态值无效)privateIntegerstatus;2. 翻译核心DictAspect AOP切面字典自动翻译的底层实现基于Spring AOP环绕通知核心类为DictAspect部分版本为DictTransformAspect在接口响应数据返回给前端前自动扫描Dict注解并完成翻译注入。2.1 核心工作机制拦截Controller层返回的响应结果解析返回数据类型通过反射扫描实体类字段上的Dict注解收集需要翻译的字段批量查询字典数据普通字典查sys_dict表字典动态执行SQL查询将字典值翻译为对应的展示文本注入到返回对象的字段名_dictText属性中支持分页对象IPage、列表List、单个实体等多种返回类型2.2 关键特性批量查询优化避免N1查询问题一次性加载所有需要翻译的字典数据缓存优先优先从缓存中读取字典数据大幅提升翻译性能多数据源支持通过ds参数支持跨数据源的表字典翻译白名单防护表字典查询内置SQL注入防护仅允许查询白名单内的表与字段3. 缓存机制针对字典数据读多写少的特性JEECG Boot 设计了前后端双层缓存架构保障高性能访问同时提供完善的缓存一致性方案。3.1 后端Redis缓存缓存类型缓存key失效策略适用场景普通字典缓存sys:dict:cache字典新增/编辑/删除时通过CacheEvict全量清空主动失效系统内置的固定字典表字典缓存sys:table:dict:cache:*定时失效默认缓存5分钟避免业务表数据变更导致的不一致动态业务表字典3.2 前端本地缓存缓存载体Pinia/Vuex Store localStorage支持AES加密加载策略懒加载字典组件首次使用时才请求数据请求后缓存到Store中刷新机制支持手动触发全局缓存刷新字典管理界面修改数据后自动推送刷新事件4. 核心API接口平台提供了完善的RESTful API支持字典的管理、查询、缓存刷新等操作核心接口如下接口地址请求方式接口说明核心参数/sys/dict/listGET字典主表分页列表字典名称、编码、状态/sys/dict/getDictItems/{dictCode}GET根据字典编码获取字典项列表dictCode字典编码/sys/dict/queryTableDictItemsByCodeGET获取表字典数据table、text、code、filterSql/sys/dict/refreshCacheDELETE刷新字典全局缓存-5. 高级扩展能力多租户隔离通过tenant_id字段实现不同租户之间的字典数据完全隔离互不影响多数据源支持表字典支持指定数据源实现跨库的字典数据查询与翻译Excel导入导出适配导出时自动将字典值翻译为文本导入时自动将文本转换为字典存储值无需手动处理AI智能匹配代码生成器AI能力可根据字段名称、注释自动匹配对应的字典编码自动添加Dict注解四、前端核心组件JDictSelectTag 全解析JDictSelectTag是JEECG Boot 专为数据字典封装的前端组件基于Ant Design Vue二次封装实现了字典数据的一键渲染、双向绑定、自动加载是前端使用字典的核心载体。1. 组件核心定位一行代码实现字典下拉、单选框、按钮式单选的渲染自动根据dictCode加载字典数据无需手动调用接口与平台表单体系深度集成支持校验、双向绑定、联动等能力内置缓存机制同字典编码多次使用仅发起一次接口请求2. 核心API参数参数名类型必填默认值说明dictCodestring是-字典配置核心参数支持两种格式1. 普通字典字典编码如sex2. 表字典表名,文本字段,取值字段[,过滤条件]typestring否select组件渲染类型支持select下拉选择框radio单选框组radioButton按钮式单选框v-model:valuestring/number/array是-双向绑定的值对应字典项的itemValueplaceholderstring否-输入框占位提示文本stringToNumberboolean否false是否将字典value从string自动转为number解决数值类型回显失败问题disabledboolean否false是否禁用整个组件showChooseOptionboolean否true是否显示【请选择】默认选项getPopupContainerfunction否() document.body下拉菜单渲染父节点解决滚动定位问题3. 基础用法示例3.1 普通字典用法template !-- 性别字典下拉框对应字典编码sex -- JDictSelectTag v-model:valuequeryParam.sex placeholder请选择用户性别 dictCodesex / /template script setup import { ref } from vue; const queryParam ref({ sex: }); /script3.2 表字典用法动态业务表数据!-- 从用户表获取数据展示realname存储id -- JDictSelectTag v-model:valuequeryParam.userId placeholder请选择用户 dictCodesys_user,realname,id /3.3 带过滤条件的表字典用法!-- 只查询性别为女的用户过滤条件sex 2 -- JDictSelectTag v-model:valuequeryParam.userId placeholder请选择女性用户 dictCodesys_user,realname,id,sex 2 /3.4 不同渲染类型用法!-- 按钮式单选框 -- JDictSelectTag v-model:valueformData.status dictCodeorder_status typeradioButton / !-- 普通单选框组 -- JDictSelectTag v-model:valueformData.auditType dictCodeaudit_type typeradio /4. 高级用法4.1 表单校验集成template a-form :modelformData :rulesrules a-form-item label用户性别 namesex JDictSelectTag v-model:valueformData.sex dictCodesex placeholder请选择性别 / /a-form-item /a-form /template script setup import { reactive, ref } from vue; const formData reactive({ sex: }); const rules { sex: [{ required: true, message: 请选择性别, trigger: change }] }; /script4.2 动态加载与手动获取字典数据组件配套提供了工具函数支持手动加载字典数据、自定义翻译场景核心函数位于/components/dict/JDictSelectUtil.ts。script setup import { initDictOptions, filterDictText } from /components/dict/JDictSelectUtil; import { ref, onMounted } from vue; const sexDictOptions ref([]); // 手动加载字典数据 const loadDictData async () { const res await initDictOptions(sex); if (res.success) { sexDictOptions.value res.result; } }; // 手动翻译字典值 const getSexText (value) { return filterDictText(sexDictOptions.value, value); }; onMounted(() { loadDictData(); }); /script4.3 表格列自定义渲染template a-table :columnscolumns :data-sourcetableData / /template script setup import { ref, onMounted } from vue; import { initDictOptions, filterDictText } from /components/dict/JDictSelectUtil; const sexDictOptions ref([]); const tableData ref([]); const columns [ { title: 用户名, dataIndex: username, align: center }, { title: 性别, dataIndex: sex, align: center, customRender: ({ text }) { // 手动翻译字典值为文本 return filterDictText(sexDictOptions.value, text); } } ]; onMounted(async () { // 初始化字典数据 const res await initDictOptions(sex); sexDictOptions.value res.success ? res.result : []; }); /script五、全链路工作流程从字典配置到前端渲染的完整闭环流程如下后台配置管理员在系统管理-字典管理界面新增字典主表记录维护对应的字典项配置完成后保存后端实体配置在业务实体类的对应字段上添加Dict注解指定字典编码或表字典配置接口响应翻译前端请求业务接口时DictAspect切面自动拦截响应数据扫描Dict注解完成字典翻译注入_dictText字段返回给前端前端组件渲染前端页面使用JDictSelectTag组件通过dictCode指定字典编码组件自动加载字典数据渲染为下拉/单选组件实现双向绑定缓存更新当字典数据发生修改时系统自动清空后端Redis缓存同时推送事件通知前端刷新本地缓存保障前后端数据一致性数据入库校验前端提交表单时可通过DictVerify注解自动校验提交的值是否在字典有效值范围内拦截非法数据六、最佳实践与规范1. 字典设计规范编码规范字典编码使用下划线命名法语义清晰如user_status、order_type禁止使用拼音、无意义缩写值类型规范字典项值优先使用数字编码1/2/3避免使用中文特殊场景可使用字符串保持全系统统一分类规范按业务模块对字典进行分类如系统模块、订单模块、用户模块避免混乱禁用规范字典项废弃时优先禁用而非直接删除避免历史数据翻译失败2. 性能优化最佳实践高频使用的字典在系统启动时进行缓存预热减少首次访问延迟表字典尽量使用简单过滤条件避免复杂SQL导致的性能问题前端页面多个地方使用同一字典时优先在页面初始化时一次性加载而非每个组件单独加载大批量数据翻译时优先使用后端Dict注解自动翻译避免前端循环翻译导致的页面卡顿3. 安全规范表字典严格遵守平台白名单机制禁止在dictCode中拼接复杂SQL、子查询避免SQL注入风险敏感业务表禁止作为表字典使用避免数据泄露字典管理界面配置严格的权限控制仅允许管理员进行字典的增删改操作七、常见问题与解决方案1. Dict注解翻译不生效问题表现接口返回数据中没有生成_dictText字段核心原因与解决方案原因1接口返回类型不是IPage、ResultIPage等切面默认支持的类型解决方案扩展DictAspect切面增加对List、ResultT等类型的支持原因2实体类字段使用了private修饰且没有对应的getter方法解决方案为字段添加getter/setter方法或使用lombok的Data注解原因3字典编码配置错误或字典项被禁用解决方案检查字典管理界面确认字典编码正确、字典项状态为启用2. 字典修改后前端显示旧数据问题表现后台修改字典项后前端页面仍显示旧的字典数据刷新页面也不生效解决方案手动点击系统右上角的【刷新缓存】按钮清空前端本地缓存检查后端字典编辑接口是否添加了CacheEvict注解确保修改后清空Redis缓存表字典数据修改后等待缓存自动过期默认5分钟或手动调用缓存刷新接口3. JDictSelectTag组件数值回显失败问题表现编辑表单时数据库中的数值无法回显到组件中核心原因字典itemValue是string类型而表单绑定的值是number类型类型不匹配解决方案添加stringToNumber属性自动将字典value转为number类型JDictSelectTag v-model:valueformData.sex dictCodesex :stringToNumbertrue /4. 表字典查询报SQL注入错误问题表现使用表字典时控制台提示SQL注入拦截无法查询数据解决方案检查使用的表名、字段名是否在平台的字典表白名单中过滤条件仅支持简单的字段值格式禁止使用子查询、函数、OR等复杂语法避免在表名、字段名中使用关键字、特殊字符