数据字典管理
本文档介绍了 open-admin 系统中的数据字典管理功能。
功能概述
数据字典管理是 open-admin 系统的核心功能之一，提供了统一的数据字典维护和使用机制，确保系统中数据的一致性和规范性。
核心概念
1. 字典类型
字典类型是数据字典的分类，如性别、状态、行业等，每个字典类型包含多个字典项。
2. 字典项
字典项是具体的字典值，如性别中的男、女，状态中的启用、禁用等。
功能详解
1. 字典类型管理
1.1 字典类型列表
- 功能：展示系统中的所有字典类型，支持分页、筛选、搜索
- 操作：查看、编辑、删除、查看字典项
1.2 字典类型创建
- 功能：创建新字典类型
- 字段：字典名称、字典编码、描述、状态
1.3 字典类型编辑
- 功能：修改字典类型信息
- 字段：字典名称、描述、状态
2. 字典项管理
2.1 字典项列表
- 功能：展示指定字典类型的所有字典项，支持分页、筛选、搜索
- 操作：查看、编辑、删除、排序
2.2 字典项创建
- 功能：创建新字典项
- 字段：字典标签、字典值、排序、状态、描述
2.3 字典项编辑
- 功能：修改字典项信息
- 字段：字典标签、字典值、排序、状态、描述
2.4 字典项排序
- 功能：调整字典项的显示顺序
- 操作：通过拖拽调整顺序
数据字典定义
配置文件定义
数据字典可以通过配置文件 application-data.yml 进行定义，这种方式适用于系统初始化时需要预设的字典数据。
配置格式
data:
dicts:
- name: 字典名称
code: 字典编码
group-name: 字典分组
items:
- name: 字典项名称
code: 字典项值
color: 状态颜色（可选）
enabled: 是否启用（可选，默认true）
seq: 排序（可选）
配置示例
data:
dicts:
- name: 性别
code: gender
items:
- name: 男
code: MALE
- name: 女
code: FEMALE
- name: 保密
code: UNKNOWN
- name: 审核状态
code: approveStatus
group-name: 系统管理
items:
- name: 待提交
code: DRAFT
color: default
- name: 审核中
code: PENDING
color: warning
- name: 审核通过
code: APPROVED
color: success
- name: 审核未通过
code: REJECTED
color: error
配置与数据库的关系
- 配置文件定义：系统初始化时加载，用于预设字典数据
- 数据库存储：字典数据会存储到数据库中，支持后续的增删改查
- 优先级：配置文件定义的数据会在系统启动时初始化到数据库，后续通过管理界面的修改会覆盖配置文件的定义
字典定义最佳实践
- 字典编码：使用小写字母和下划线组合，如
user_status、order_type - 字典分组：合理使用
group-name进行字典分类，便于管理 - 状态颜色：为不同状态的字典项设置合适的颜色，提升前端展示效果
- 字典项值：使用有意义的枚举值或数字编码，如
ACTIVE、INACTIVE或1、2 - 排序设置：通过
seq属性设置字典项的显示顺序，确保前端展示的一致性 - 模块化配置：不同模块的字典定义可以分散到多个配置文件中，系统会自动合并
配置文件与管理界面的区别
| 特性 | 配置文件定义 | 管理界面操作 |
|---|---|---|
| 适用场景 | 系统初始化预设 | 运行时动态管理 |
| 操作方式 | 编辑配置文件，重启系统 | 网页界面操作，实时生效 |
| 优先级 | 初始化时使用，后续会被界面操作覆盖 | 实时修改，优先级高于配置文件 |
| 版本控制 | 可通过代码版本控制 | 存储在数据库中，需单独备份 |
使用示例
2. 前端使用
2.1 字典选择器
import {FieldDictSelect} from "@jiangood/open-admin";
<Form.Item label="性别" name="gender" rules={[{required: true}]}>
<FieldDictSelect typeCode="gender" placeholder="请选择性别"/>
</Form.Item>
2.2 字典工具
import {DictUtils} from "@jiangood/open-admin";
// 获取字典列表
const genderList = DictUtils.dictList("gender");
// 获取字典标签
const genderLabel = DictUtils.dictLabel("gender", "MALE");
// 将字典列表转换为 Ant Design Select/Options 格式
const genderOptions = DictUtils.dictOptions("gender");
// 获取字典标签并包装为 Tag 组件
const genderTag = DictUtils.dictTag("gender", "MALE");
最佳实践
- 字典设计：合理设计字典类型，避免过多或过少的字典类型
- 字典编码：使用简洁明了的字典编码，如
gender、status - 字典值：使用有意义的字典值，如 0 表示禁用，1 表示启用
- 排序管理：根据业务需求合理设置字典项的排序
- 缓存使用：优先使用前端字典工具获取字典数据，减少后端请求
常见问题
1. 字典数据不更新
- 原因：前端缓存未刷新，后端缓存未更新
- 解决方法：刷新页面，或等待缓存自动过期
2. 字典选择器无数据
- 原因：字典类型不存在，或字典类型下无字典项
- 解决方法：检查字典类型是否正确，确保字典类型下有字典项
3. 字典值重复
- 原因：同一字典类型下存在相同的字典值
- 解决方法：修改字典项，确保同一字典类型下字典值唯一