字典模块使用指南
一、快速开始
1.1 新增一个系统枚举字典
假设需要为"消息通知"模块新增一个系统字典分类，包含通知类型和通知渠道。
步骤 1：在 SysSysEnum 中注册新的子分类
// 文件：sys-api/.../common/enums/SysSysEnum.java
public enum SysSysEnum implements SystemEnum {
// ... 已有内容 ...
MsgEnum("msg", "消息通知"); // ← 新增这行
}
步骤 2：创建中间枚举（分类节点）
// 文件：sys-biz/.../msg/enums/MsgEnum.java
@DictParent(parent = SysSysEnum.class)
public enum MsgEnum implements SystemEnum {
MsgTypeEnum("msgType", "通知类型"),
MsgChannelEnum("msgChannel", "通知渠道");
}
步骤 3：创建叶子枚举（具体值）
// 文件：sys-biz/.../msg/enums/MsgTypeEnum.java
@DictParent(parent = MsgEnum.class)
public enum MsgTypeEnum implements SystemEnum {
SYSTEM_NOTICE("systemNotice", "系统通知"),
TASK_REMIND("taskRemind", "任务提醒"),
APPROVAL_NOTIFY("approvalNotify", "审批通知");
}
// 文件：sys-biz/.../msg/enums/MsgChannelEnum.java
@DictParent(parent = MsgEnum.class)
public enum MsgChannelEnum implements SystemEnum {
IN_APP("inApp", "站内信"),
EMAIL("email", "邮件"),
SMS("sms", "短信");
}
无需任何额外配置，启动后 EnumCollector 自动扫描并构建树，/sys/v1/dict/tree/system 即可返回包含新枚举的完整树。
1.2 生成效果
系统 (sysSys)
└── 消息通知 (sysSys.msg)
├── 通知类型 (sysSys.msg.msgType)
│ ├── 系统通知 (sysSys.msg.msgType.systemNotice)
│ ├── 任务提醒 (sysSys.msg.msgType.taskRemind)
│ └── 审批通知 (sysSys.msg.msgType.approvalNotify)
└── 通知渠道 (sysSys.msg.msgChannel)
├── 站内信 (sysSys.msg.msgChannel.inApp)
├── 邮件 (sysSys.msg.msgChannel.email)
└── 短信 (sysSys.msg.msgChannel.sms)
二、API 接口说明
所有接口前缀：/sys/v1/dict
2.1 查询接口
| 接口 | 方法 | 说明 |
|---|---|---|
/search-all |
GET | 获取所有字典（系统+业务合并） |
/search-system |
GET | 仅获取系统字典 |
/tree/system |
GET | 获取系统字典树形结构 |
/tree/business |
GET | 获取业务字典树形结构 |
/all-tree |
GET | 获取完整的业务字典树（仅数据库） |
/searchByParentPath |
GET | 按 parentPath 筛选子节点 |
/searchByParentPathList |
POST | 按 parentPath 批量筛选子节点 |
/searchByParentId |
GET | 按父 ID 查询子节点 |
/page |
POST | 分页查询业务字典 |
/detail/{id} |
GET | 查询单个字典详情 |
2.2 常用查询示例
获取系统字典树：
GET /sys/v1/dict/tree/system
返回树形结构，每个节点包含 dictCode、dictName、path、children。
按路径获取子节点（常用于级联选择器）：
GET /sys/v1/dict/searchByParentPath?parentPath=sysSys.task
返回 parentPath 为 sysSys.task 的所有子字典（如 taskStatus、taskTag）。
获取所有可用字典（下拉框数据源）：
GET /sys/v1/dict/search-all
返回扁平列表，包含系统枚举和业务字典的并集。
2.3 业务字典 CRUD
| 接口 | 方法 | 说明 |
|---|---|---|
/create |
POST | 创建业务字典 |
/update |
PUT | 更新业务字典 |
/delete/{id} |
DELETE | 删除单个字典 |
/batch-delete |
DELETE | 批量删除字典 |
创建业务字典示例：
POST /sys/v1/dict/create
{
"parentId": "1",
"dictCode": "urgent",
"dictName": "紧急",
"category": "BIZ",
"sortCode": 1,
"isEnabled": "1"
}
系统会自动生成 parentPath 和 path 字段。
三、核心注解说明
3.1 @DictParent
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface DictParent {
Class<? extends Enum<?>> parent() default EmptyEnum.class;
}
| 参数 | 说明 |
|---|---|
parent() |
父枚举类。不传（默认 EmptyEnum）表示当前枚举是根节点下的第一层 |
3.2 SystemEnum 接口
public interface SystemEnum {
String getCode(); // 字典编码，作为 path 的一段
String getName(); // 字典名称，前端展示用
}
四、配置项
# application.yml
dict:
type: mysql # 字典存储类型，目前仅支持 mysql
mom:
print:
enable: true # 是否启用打印模块
async: true # 是否异步初始化（true 可不阻塞启动）
stop-start: false # 初始化失败是否终止启动
五、发布业务字典
当在代码中新增了 BusinessEnum 实现的枚举类后，需要将其发布到数据库：
POST /sys/v1/dict-meta/publish
发布流程：
- 从 init cache 获取所有业务字典枚举
- 与
sys_dict_meta表对比差异并同步 - 将未发布的 DictMeta 记录写入
sys_dict - 自动解析父节点，按 path 长度升序保证顺序正确
六、常见问题
Q1：多个枚举中有相同的 code 值会冲突吗？
不会。模块使用 "ClassName:code" 作为精确 key 进行路径匹配（如 PrintEnum:type vs BusinessTypeConfigEnum:type），不会产生歧义。
Q2：系统字典可以修改或删除吗？
不可以。category=SYS 的字典受保护，CRUD 接口会校验并拒绝操作。要修改系统字典，需修改对应的 Java 枚举源码并重新部署。
Q3：接口响应慢怎么办？
系统字典的树形结构在启动时已构建并缓存（DICT_TREE_CACHE），请求应返回毫秒级。如果变慢，检查是否有缓存被意外清除。
Q4：如何验证新增的枚举是否被正确扫描？
启动日志中会输出扫描到的枚举类数量和处理结果，确认新增枚举出现在日志中即可。也可直接调用 /tree/system 接口验证。