【JEECG Boot】 JEECG Boot 数据字典管理——六大核心功能（内含：《JEECG Boot 数据字典开发速查清单》）

文章目录JEECG Boot 数据字典管理——核心功能一、核心功能总览二、六大核心功能一可视化字典配置与管理后台核心1. 字典主表管理sys_dict2. 字典项明细管理sys_dict_item3. 字典导入导出Excel二后端自动字典翻译核心能力Dict注解1. Dict注解核心翻译功能2. 翻译切面DictAspect核心机制3. 字典值合法性校验DictVerify三前端字典组件渲染JDictSelectTag核心组件1. 核心渲染能力2. 核心用法覆盖所有场景3. 配套工具函数JDictSelectUtil四多层级缓存管控高性能保障1. 后端Redis缓存核心2. 前端本地缓存五安全与权限管控防风险1. 字典管理权限2. 表字典安全防护防SQL注入六高级扩展功能适配复杂业务1. 多级联动字典2. 字典状态联动与颜色高亮3. 代码生成器集成4. 多语言/国际化支持三、核心功能边界与适用场景✅ 适用场景❌ 不适用场景四、核心功能价值总结JEECG Boot 数据字典——开发速查清单一、核心基础信息速览1. 核心存储表开发必知2. 核心能力链路二、后端核心注解速查全参数可复制示例1. Dict 自动翻译注解核心全参数明细可直接复制的3大核心场景示例场景1普通固定字典最常用场景2表字典动态业务数据无需后台配置场景3跨数据源表字典2. DictVerify 入参合法性校验注解全参数明细可复制示例三、前端JDictSelectTag组件速查全参数可复制示例1. 核心属性全表2. 渲染类型说明3. 可直接复制的高频场景示例示例1普通字典下拉框最常用示例2数值类型回显修复必用场景示例3表字典动态业务数据示例4带过滤条件的表字典示例5单选按钮/按钮式单选4. 配套工具函数JDictSelectUtil表格列翻译示例可直接复制四、核心API接口速查1. 字典查询类接口2. 缓存管理类接口五、开发规范与最佳实践1. 字典设计规范2. 性能优化规范3. 安全规范六、高频问题排查速查表JEECG Boot 数据字典管理——核心功能JEECG Boot 数据字典管理的核心功能围绕可视化配置、自动翻译、前端组件化渲染、缓存管控、安全校验、高级扩展六大核心模块实现静态业务数据全生命周期统一管控下面从核心功能定义、完整能力拆解、关键实现机制、功能边界与适用场景四个维度做详细介绍。一、核心功能总览JEECG Boot 数据字典核心功能本质是解决系统内枚举/状态/常量数据的“统一配置、自动翻译、全局复用、动态维护”问题无需硬编码、一处修改全系统生效覆盖后端翻译、前端渲染、数据安全、缓存优化、多场景扩展全链路。核心定位可视化配置中心 后端自动翻译引擎 前端组件化渲染器 缓存与安全管控层。二、六大核心功能一可视化字典配置与管理后台核心这是字典数据的源头管控功能提供Web可视化界面无需写SQL/代码即可完成字典全生命周期维护是所有字典能力的基础。1. 字典主表管理sys_dict新增/编辑/删除/查询字典配置字典名称、唯一字典编码全局调用标识、描述、租户/低代码应用归属支持逻辑删除del_flag1不物理删除保障历史数据兼容字典分类/分组按业务模块系统、用户、订单、设备归类支持搜索、分页、状态筛选启用/禁用多租户/低代码隔离通过tenant_id、low_app_id字段实现不同租户/应用字典数据完全隔离互不干扰2. 字典项明细管理sys_dict_item字典项增删改配置item_value存储值如1/2、item_text展示文本如男/女、排序号、状态启用/禁用、颜色标识用于标签/状态高亮批量操作批量新增、批量导入导出Excel、批量启用/禁用、批量排序字典项校验同一字典下item_value唯一避免重复值禁用项不参与前端渲染与后端翻译颜色配置支持为字典项配置颜色如success/error/warning用于表格状态列、标签组件高亮展示3. 字典导入导出Excel导出自动将字典值翻译为文本导出完整字典结构主表明细支持按字典编码筛选导出导入支持Excel批量导入字典/字典项自动校验编码唯一性、值合法性覆盖批量初始化场景二后端自动字典翻译核心能力Dict注解这是JEECG Boot 字典最核心的自动化能力通过AOP切面注解实现数据库存储值 ↔ 前端展示文本的双向自动转换彻底消除手动翻译代码。1. Dict注解核心翻译功能普通字典翻译最常用标注在实体字段指定dicCode字典编码接口返回时自动生成字段名_dictText翻译字段如sex → sex_dictText男Dict(dicCodeuser_status)// 对应字典编码user_statusprivateIntegerstatus;// 数据库存1/2/3返回自动加status_dictText正常/禁用/锁定表字典翻译动态业务字典无需在字典界面配置直接关联业务表指定dictTable表名、dicText展示字段、dicCode存储字段动态从业务表加载数据并翻译Dict(dictTablesys_user,dicTextrealname,dicCodeid)privateStringcreateBy;// 存储用户ID自动翻译为用户真实姓名createBy_dictText多数据源/跨库翻译通过ds参数指定数据源支持跨库表字典翻译Dict(dictTablebiz_order,dicTextorder_name,dicCodeorder_id,dsbiz_db)2. 翻译切面DictAspect核心机制拦截范围自动拦截Controller返回的Result、IPage、List、实体对象等类型覆盖所有业务接口批量查询优化一次性加载所有待翻译字典避免N1查询大幅提升性能缓存优先优先从Redis缓存读取字典数据不重复查库自动注入翻译结果自动注入到返回对象的_dictText扩展字段前端直接使用无需额外处理3. 字典值合法性校验DictVerify配套校验注解用于入参/表单数据校验自动校验提交值是否在字典有效值范围内拦截非法数据入库DictVerify(dictCodeuser_status,message用户状态值无效请传入有效值)privateIntegerstatus;三前端字典组件渲染JDictSelectTag核心组件基于Ant Design Vue封装的专用字典渲染组件一行代码实现字典下拉/单选/按钮单选自动加载数据、双向绑定、缓存复用是前端使用字典的唯一标准组件。1. 核心渲染能力多类型渲染支持3种核心渲染模式type参数select下拉选择框默认最常用radio单选框组radioButton按钮式单选自动数据加载传入dictCode组件自动调用/sys/dict/getDictItems/{dictCode}接口加载字典数据无需手动写请求双向绑定v-model:value直接绑定字典item_value提交时自动传存储值回显时自动匹配展示文本基础增强支持placeholder、禁用、默认“请选择”选项、数值类型自动转换stringToNumber、滚动定位getPopupContainer2. 核心用法覆盖所有场景普通字典下拉JDictSelectTag v-model:valueform.sex dictCodesex placeholder请选择性别 /表字典动态业务数据JDictSelectTag v-model:valueform.userId dictCodesys_user,realname,id placeholder请选择用户 /带过滤的表字典JDictSelectTag v-model:valueform.userId dictCodesys_user,realname,id,sex2 placeholder请选择女性用户 /按钮单选/普通单选JDictSelectTag v-model:valueform.status dictCodeorder_status typeradioButton / JDictSelectTag v-model:valueform.type dictCodepay_type typeradio /3. 配套工具函数JDictSelectUtil提供手动加载、翻译工具适配表格自定义渲染、非组件场景initDictOptions(dictCode)手动加载字典数据filterDictText(options, value)手动将字典值翻译为文本用于表格列渲染四多层级缓存管控高性能保障针对字典读多写少特性设计后端Redis缓存 前端本地缓存双层架构兼顾性能与一致性是高并发场景的核心保障。1. 后端Redis缓存核心普通字典缓存keysys:dict:cache字典新增/编辑/删除时主动清空CacheEvict实时一致表字典缓存keysys:table:dict:cache:*定时过期默认5分钟避免业务表变更导致不一致缓存预热支持系统启动时预热高频字典减少首次访问延迟2. 前端本地缓存缓存载体Pinia localStorage加密存储懒加载同一dictCode多次使用仅首次请求接口后续从缓存读取缓存刷新后台修改字典后自动推送刷新事件前端清空缓存并重新加载支持手动点击“刷新缓存”按钮五安全与权限管控防风险1. 字典管理权限菜单/按钮权限仅管理员角色可访问字典管理、增删改字典普通用户仅可读数据权限多租户下仅能管理本租户字典禁止跨租户操作2. 表字典安全防护防SQL注入白名单机制仅允许查询平台配置的白名单表/字段禁止非法表/字段过滤条件限制仅支持简单字段值格式禁止子查询、函数、OR/AND复杂语法SQL注入拦截内置拦截器自动检测并阻断恶意SQL六高级扩展功能适配复杂业务1. 多级联动字典支持父子级字典如省市区、分类-子类通过字典编码关联实现一级选择后自动加载二级选项适配树形/级联选择场景2. 字典状态联动与颜色高亮字典项配置颜色后前端表格/表单可自动渲染为带颜色的标签如正常绿色、禁用红色提升界面可读性3. 代码生成器集成JEECG 代码生成器可自动识别字段并匹配字典生成实体时自动添加Dict注解、前端页面自动生成JDictSelectTag组件零代码完成字典集成4. 多语言/国际化支持支持字典项配置多语言文本根据前端语言环境自动切换展示文本适配国际化系统三、核心功能边界与适用场景✅ 适用场景系统通用枚举性别、状态、类型、开关、订单状态等固定枚举动态业务数据用户、部门、分类、产品等需从业务表动态加载的选项表单/表格渲染所有需要下拉、单选、状态展示的页面数据校验入参/表单值合法性校验多租户/跨库多租户系统、多数据源业务场景❌ 不适用场景海量动态数据百万级字典适合静态/低频变更数据海量数据建议用分页查询实时性要求极高毫秒级表字典有缓存延迟不适合强实时场景复杂业务逻辑计算字典仅做数据映射不承载业务计算四、核心功能价值总结开发效率提升可视化配置自动翻译组件化减少80%以上枚举相关代码维护成本降低一处修改全系统生效无需改代码、发版数据一致性统一数据源避免多地方硬编码导致的不一致性能优化双层缓存读多写少场景下接口响应毫秒级安全可控权限防注入保障字典数据安全JEECG Boot 数据字典——开发速查清单适配JEECG Boot 3.x/4.x主流版本覆盖全流程开发场景所有代码/参数可直接复制使用按开发使用逻辑排序方便快速查阅。一、核心基础信息速览1. 核心存储表开发必知表名核心作用开发核心字段sys_dict字典主表存储字典元数据dict_code全局唯一字典编码开发核心调用标识、dict_name展示名称、tenant_id租户隔离sys_dict_item字典从表存储字典明细选项item_value数据库存储值、item_text前端展示文本、sort_order排序、status1启用/0禁用、dict_id关联主表2. 核心能力链路后台配置字典 → 实体加Dict注解 → 接口自动翻译生成xxx_dictText→ 前端用JDictSelectTag渲染 → 双层缓存保障性能二、后端核心注解速查全参数可复制示例1. Dict 自动翻译注解核心字典自动翻译的核心载体标注在实体类字段上AOP切面自动完成值→文本的翻译生成字段名_dictText扩展字段。全参数明细参数名类型必填适用场景参数说明dicCodeString是普通字典系统内置固定字典对应sys_dict表的唯一字典编码dictTableString是表字典动态业务表字典要关联的业务表名dicTextString是表字典动态业务表字典业务表中作为前端展示文本的字段名dicCodeString是表字典动态业务表字典业务表中作为数据库存储值的字段名dsString否多数据源/跨库场景表字典所在的数据源名称不填默认主数据源可直接复制的3大核心场景示例场景1普通固定字典最常用importorg.jeecg.common.aspect.annotation.Dict;/** * 用户状态对应字典编码user_status * 数据库存储值1正常 2禁用 3锁定 * 接口返回自动生成status_dictText 字段 */Dict(dicCodeuser_status)privateIntegerstatus;场景2表字典动态业务数据无需后台配置/** * 创建人ID关联用户表自动翻译为用户真实姓名 * 格式dictTable表名, dicText展示字段, dicCode存储字段 */Dict(dictTablesys_user,dicTextrealname,dicCodeid)privateStringcreateBy;场景3跨数据源表字典/** * 跨库关联业务订单表翻译订单名称 * ds参数指定配置文件中的数据源名称 */Dict(dictTablebiz_order,dicTextorder_name,dicCodeorder_id,dsbiz_db)privateStringorderId;2. DictVerify 入参合法性校验注解用于表单/接口入参校验自动校验提交值是否在字典有效值范围内拦截非法数据入库。全参数明细参数名类型必填参数说明dictCodeString是对应sys_dict表的字典编码messageString否校验失败的提示文案不填使用默认提示可复制示例importorg.jeecg.common.aspect.annotation.DictVerify;/** * 校验提交的性别值必须是字典sex中定义的有效值 */DictVerify(dictCodesex,message性别值无效请传入字典定义的有效值)privateIntegersex;三、前端JDictSelectTag组件速查全参数可复制示例基于Ant Design Vue封装的专用字典渲染组件一行代码实现字典渲染是前端使用字典的唯一标准组件。1. 核心属性全表属性名类型必填默认值说明dictCodeString是-核心配置1. 普通字典直接传字典编码如sex2. 表字典表名,展示字段,存储字段[,过滤条件]v-model:valueString/Number/Array是-双向绑定值对应字典item_valuetypeString否select渲染类型可选select/radio/radioButtonplaceholderString否-输入框占位提示文本stringToNumberBoolean否false自动将字典value从string转为number解决数值类型回显失败问题disabledBoolean否false禁用整个组件showChooseOptionBoolean否true是否显示【请选择】默认空选项getPopupContainerFunction否() document.body下拉菜单挂载节点解决滚动遮挡问题2. 渲染类型说明类型值渲染效果适用场景select下拉选择框默认表单常规选择、选项较多的场景radio单选框组选项较少≤3个、需要平铺展示的场景radioButton按钮式单选框状态切换、分类筛选等场景3. 可直接复制的高频场景示例示例1普通字典下拉框最常用JDictSelectTag v-model:valueform.sex dictCodesex placeholder请选择用户性别 /示例2数值类型回显修复必用场景!-- 数据库字段为int/number类型编辑页回显失败时添加 -- JDictSelectTag v-model:valueform.sex dictCodesex :stringToNumbertrue placeholder请选择用户性别 /示例3表字典动态业务数据!-- 从用户表获取数据展示realname存储id -- JDictSelectTag v-model:valueform.userId dictCodesys_user,realname,id placeholder请选择操作用户 /示例4带过滤条件的表字典!-- 只查询状态正常的用户过滤条件status1 -- JDictSelectTag v-model:valueform.userId dictCodesys_user,realname,id,status1 placeholder请选择正常用户 /示例5单选按钮/按钮式单选!-- 普通单选框组 -- JDictSelectTag v-model:valueform.orderStatus dictCodeorder_status typeradio / !-- 按钮式单选 -- JDictSelectTag v-model:valueform.auditStatus dictCodeaudit_status typeradioButton /4. 配套工具函数JDictSelectUtil用于非组件场景的字典手动加载、翻译适配表格自定义渲染、特殊逻辑处理。函数名入参返回值适用场景initDictOptions(dictCode)dictCode字典编码Promise返回字典项数组手动加载字典数据filterDictText(options, value)options字典项数组value要翻译的存储值翻译后的展示文本表格列、自定义场景的字典值手动翻译表格列翻译示例可直接复制template a-table :columnscolumns :data-sourcetableData row-keyid / /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, width: 120 }, { title: 性别, dataIndex: sex, align: center, width: 80, // 手动翻译字典值为文本 customRender: ({ text }) filterDictText(sexDictOptions.value, text) } ]; // 页面初始化加载字典 onMounted(async () { const res await initDictOptions(sex); sexDictOptions.value res.success ? res.result : []; }); /script四、核心API接口速查1. 字典查询类接口接口地址请求方式核心入参接口说明适用场景/sys/dict/getDictItems/{dictCode}GETdictCode字典编码路径参数根据字典编码获取启用的字典项列表前端组件自动调用、手动加载普通字典/sys/dict/queryTableDictItemsByCodeGETtable表名text展示字段code存储字段filterSql过滤条件获取表字典数据前端表字典组件自动调用、手动加载业务表字典/sys/dict/listGETdictName、dictCode、status查询参数字典主表分页列表字典管理页面、自定义字典管理功能2. 缓存管理类接口接口地址请求方式接口说明适用场景/sys/dict/refreshCacheDELETE清空字典全局Redis缓存触发前端缓存刷新事件字典修改后不生效、手动刷新缓存五、开发规范与最佳实践1. 字典设计规范编码规范字典编码使用下划线命名法语义清晰如user_status、order_type禁止使用拼音、无意义缩写值规范字典项值优先使用数字编码1/2/3避免使用中文同一系统内值类型保持统一生命周期规范废弃字典项优先禁用不直接物理删除避免历史数据翻译失败分类规范按业务模块对字典进行分类命名如sys_开头为系统通用字典biz_开头为业务字典2. 性能优化规范高频使用的字典在系统启动时做缓存预热减少首次访问延迟大批量数据翻译优先使用后端Dict注解避免前端循环翻译导致页面卡顿同一页面多次使用同一字典优先在页面初始化时一次性加载避免重复请求表字典尽量使用简单过滤条件避免复杂SQL导致的性能问题3. 安全规范表字典仅使用简单字段值过滤条件禁止拼接子查询、函数、OR/AND等复杂语法避免SQL注入敏感业务表禁止作为表字典使用避免数据泄露字典管理菜单仅开放给管理员角色严格控制增删改权限六、高频问题排查速查表问题现象核心根因一键解决方案Dict注解不生效接口无xxx_dictText字段1. 实体无getter/setter方法2. 接口返回类型不在切面拦截范围内3. 字典编码错误4. 字典项被禁用1. 实体添加lombok Data注解2. 确认返回类型为Result/IPage/List/实体对象3. 核对字典编码与后台一致4. 确认字典项状态为启用JDictSelectTag组件编辑页数值回显失败字典item_value为string类型表单绑定值为number类型类型不匹配组件添加:stringToNumbertrue属性字典修改后前端仍显示旧数据前后端缓存未刷新1. 后台字典管理页点击【刷新缓存】2. 前端页面手动刷新缓存3. 确认字典编辑接口添加了CacheEvict注解表字典使用时报SQL注入拦截错误1. 过滤条件使用了复杂SQL语法2. 表/字段不在白名单内1. 仅使用字段值的简单过滤条件2. 核对表名、字段名是否在平台字典白名单内同一字典多次使用重复发起接口请求前端缓存未生效1. 确认dictCode拼写完全一致2. 检查前端Pinia字典缓存是否正常初始化多租户场景下租户A能看到租户B的字典字典查询未加租户隔离条件1. 确认实体添加了Tenant注解2. 核对字典表tenant_id字段是否正确赋值