跳到主要内容

Nebula Dict 模块总览

1. 模块定位​

nebula-dict 是 Nebula 中台里的统一数据字典模块,负责把“可配置、可维护、可分页、可缓存、可按字典编码读取”的字典数据收敛到一个标准能力中。

从当前代码可以确认,它以字典类型 + 树形字典项结构为统一模型,字典项天然支持 parentId 和 path 层级信息。

因此它适合承载的场景包括:

  • 订单状态、用户状态、证件类型等稳定枚举
  • 分类编码、标签类型、业务分组等可配置项
  • 前端下拉选项、单选项、枚举展示名称
  • 带层级关系的区域、部门类别、业务分类树
  • 需要颜色、默认值、扩展 JSON 的富字典模型

2. 模块结构​

当前 nebula-dict 采用 Nebula 标准五段式结构:

nebula-dict/
├── nebula-dict-api # 契约层:接口、DTO、Command、Query、常量
├── nebula-dict-core # 核心实现:service、dao、entity、缓存定义
├── nebula-dict-local # 本地接入层:Controller + 请求/响应模型
├── nebula-dict-remote # 远程接入层:Feign Client + 远程代理实现
└── nebula-dict-service # 独立服务启动模块

各子模块职责如下:

  • nebula-dict-api
    • 放 IDictService
    • 放字典类型、字典项相关的命令、查询、DTO
    • 放写操作扩展点 DictOperationHook 与领域事件 DictType*Event / DictItem*Event
    • 放错误码、缓存常量等稳定契约
  • nebula-dict-core
    • 放真正的业务实现,如 DictServiceImpl
    • 放 DAO / Entity / 分页查询参数对象
    • 放缓存定义、DictHookConfiguration 以及 Hook 默认空实现装配
  • nebula-dict-local
    • 放 REST Controller
    • 适合单体应用直接接入
  • nebula-dict-remote
    • 放 Feign Client 与远程代理实现
    • 适合字典中心独立部署后由其他服务远程消费
  • nebula-dict-service
    • 放独立服务启动入口
    • 默认端口 17779

3. 当前已确认的核心能力​

根据 IDictService、DictController 与 DictServiceImpl,当前模块对外提供的能力包括:

3.1 字典类型能力​

  • 创建字典类型
  • 更新字典类型
  • 删除字典类型
  • 查询字典类型详情
  • 分页查询字典类型

3.2 字典项能力​

  • 创建字典项
  • 更新字典项
  • 删除字典项
  • 查询字典项详情
  • 分页查询字典项
  • 按字典编码查询字典项(返回树形结构)

3.3 层级与约束能力​

当前字典项除了基础字段外,还支持:

  • dictCode:所属字典编码
  • name:字典项名称
  • parentId:父级字典项 ID
  • path:树路径
  • itemValue:字典项值
  • defaultFlag:是否默认值
  • tagColor:标签颜色
  • extraJson:扩展属性 JSON

同时服务层包含以下业务约束:

  • 父节点必须存在
  • 父节点必须与当前字典项属于同一个 dictCode
  • 不允许把节点挂到自己或自己的后代下面
  • 有子节点的字典项不允许直接删除
  • 有字典项的字典类型不允许直接删除

3.4 写操作 Hook 与领域事件​

字典写路径现在额外提供两类扩展:

  • 同步 Hook:DictOperationHook,在写库前后拦截字典类型 / 字典项操作,适合同事务联动、删除前清理依赖
  • 领域事件:DictTypeCreatedEvent / DictTypeUpdatedEvent / DictTypeDeletedEvent 与 DictItemCreatedEvent / DictItemUpdatedEvent / DictItemDeletedEvent,写成功后通过 NebulaEventPublisher 发布

两者都定义在 nebula-dict-api。事件载荷自包含,监听器通常不需要再回查数据库。


4. 当前接口边界​

当前本地控制器入口统一挂在:

/api/dict

主要包括以下接口分组:

4.1 字典类型​

  • POST /api/dict/types
  • PUT /api/dict/types/{id}
  • DELETE /api/dict/types/{id}
  • GET /api/dict/types/{id}
  • POST /api/dict/types/page

4.2 字典项​

  • POST /api/dict/items
  • PUT /api/dict/items/{id}
  • DELETE /api/dict/items/{id}
  • GET /api/dict/items/{id}
  • POST /api/dict/items/page
  • GET /api/dict/items/dict/{dictCode}

其中:

  • /items/dict/{dictCode} 返回树结构 List<DictItemTreeDto>

5. 当前缓存边界​

nebula-dict 当前不仅支持查询,还内置了字典读取缓存。

根据 DictCacheDefinitionConfiguration 与 DictServiceImpl 上的缓存注解,可以确认当前存在两类按编码读取缓存:

  • dictItemByType:按字典编码缓存字典项平铺列表
  • dictItemTreeByType:按字典编码缓存字典项树

缓存键会区分:

  • dictCode
  • onlyEnabled=true/false

也就是说,同一个字典编码至少会对应以下两个常见缓存视图:

  • 只看启用项
  • 看全部项

当字典类型或字典项发生新增、更新、删除时,服务层会自动清理对应字典编码的平铺缓存和树缓存。


6. 本地模式与远程模式​

nebula-dict 支持两种主要接入方式。

6.1 单体 / 本地模式​

直接引入 nebula-dict-local 时:

  • 当前应用直接暴露 /api/dict/*
  • IDictService 由本地实现提供
  • 适合单体项目或 app-starter 直接集成

6.2 远程模式​

独立部署 nebula-dict-service 后,业务服务只依赖 nebula-dict-remote:

  • 当前服务不直接实现字典逻辑
  • 通过 DictFeignClient 转调远程字典服务
  • 适合多个业务系统共享一套字典中心

7. 文档阅读建议​

建议按下面顺序阅读:

  1. 设计与实现
    • 先理解字典项树、路径字段、缓存、写操作 Hook、领域事件和 remote 模式
  2. 业务功能
    • 再理解字典类型、字典项、树形读取、Hook/事件分别解决什么问题
  3. 使用方式
    • 最后看如何单体接入、拆服务、远程消费,以及如何实现 Hook 和监听事件
  4. 建表语句
    • 若要真正落库,再查看表结构和字段约束

8. 推荐阅读源码入口​

如果你要继续深入源码,建议优先阅读这些文件:

  • nebula-dict/nebula-dict-api/src/main/java/cn/cloudomni/nebula/dict/service/IDictService.java
  • nebula-dict/nebula-dict-api/src/main/java/cn/cloudomni/nebula/dict/hook/DictOperationHook.java
  • nebula-dict/nebula-dict-api/src/main/java/cn/cloudomni/nebula/dict/event/DictItemDeletedEvent.java
  • nebula-dict/nebula-dict-local/src/main/java/cn/cloudomni/nebula/dict/controller/DictController.java
  • nebula-dict/nebula-dict-core/src/main/java/cn/cloudomni/nebula/dict/service/impl/DictServiceImpl.java
  • nebula-dict/nebula-dict-core/src/main/java/cn/cloudomni/nebula/dict/config/DictCacheDefinitionConfiguration.java
  • nebula-dict/nebula-dict-core/src/main/java/cn/cloudomni/nebula/dict/config/DictHookConfiguration.java
  • nebula-dict/nebula-dict-service/src/test/resources/db/test/dict-schema-mysql.sql