跳到主要内容

Nebula Dict 业务功能

1. 功能概览​

从当前代码与 README 可以确认，nebula-dict 对业务系统提供的能力主要包括五类：

  • 字典类型管理
  • 字典项管理
  • 平铺字典读取
  • 树形字典读取
  • 缓存化字典查询

这些能力围绕“统一维护业务枚举与业务分类”展开，而不是孤立的几条 CRUD 接口。

2. 字典类型管理​

2.1 创建字典类型​

适用场景：

  • 新增一个全新的字典域
  • 为某类业务枚举建立统一编码入口
  • 给其他系统或前端约定一个稳定的 code

典型例子：

  • order_status
  • user_status
  • certificate_type
  • region

业务价值：

  • 把散落在代码里的枚举定义收口到可维护的数据模型里
  • 让前端和后端围绕统一编码协作
  • 为后续缓存、远程消费、统一字典中心打基础

2.2 更新字典类型​

适用场景：

  • 调整展示名称
  • 调整启停状态
  • 维护备注信息

2.3 删除字典类型​

当前规则：

  • 如果该字典下仍然存在字典项，则不允许删除

业务价值：

  • 防止误删导致字典项失去归属
  • 防止前端或下游系统按 code 查询时得到不可预期结果

3. 字典项管理​

3.1 创建字典项​

适用场景：

  • 新增一个状态值或分类节点
  • 给某个字典维护新的业务选项
  • 构建树形字典结构中的根节点或子节点

当前字典项除了基础值之外，还支持：

  • dictCode
  • name
  • itemValue
  • defaultFlag
  • tagColor
  • extraJson
  • parentId

这意味着它不只是“一个字符串映射”，而是一个可以承载展示属性和扩展属性的富模型。

3.2 更新字典项​

适用场景：

  • 修改展示名称
  • 修改实际值
  • 调整排序
  • 调整启停状态
  • 改变父子关系
  • 改变默认值、颜色、扩展属性

更新父子关系时，系统会自动刷新：

  • 当前节点路径
  • 后代节点路径

因此业务方不需要自己维护树路径。

3.3 删除字典项​

当前规则：

  • 如果当前节点仍有子节点，则不允许删除

业务价值：

  • 防止树结构断裂
  • 保证层级数据删除是显式且可控的

4. 平铺字典读取​

4.1 按字典编码查询平铺列表​

当前接口：

GET /api/dict/items/dict/{dictCode}

它适合以下场景：

  • 下拉框
  • 单选按钮组
  • 列表页状态映射
  • 表单里的稳定选项集

4.2 onlyEnabled 过滤​

当前查询支持 onlyEnabled 参数：

  • true：只返回启用项
  • false：返回全部项
  • null：默认按 true 处理

业务价值：

  • 前台页面默认只看到可用选项
  • 后台维护页面可以按需查看停用数据

5. 树形字典读取​

5.1 按字典编码查询树​

当前接口：

GET /api/dict/items/dict/{dictCode}/tree

它返回的是 DictItemTreeDto 列表，每个节点都带 children。

适用场景：

  • 省市区
  • 分类树
  • 多级级联选择器
  • 树形筛选菜单
  • 后台树结构展示

5.2 当前树结构能力​

当前模块已经支持：

  • 根节点
  • 多级子节点
  • 父子关系校验
  • 环形引用校验
  • 节点迁移后的路径刷新
  • 启用过滤下的树构建

5.3 过滤父节点缺失时的行为​

当前树查询还有一个很关键的行为：

  • 如果当前加载结果中某个节点的父节点不存在，那么该节点会被提升为根节点返回

这在 onlyEnabled=true 时尤其重要，因为：

  • 父节点可能已停用
  • 子节点仍然是启用的
  • 系统不会因为父节点被过滤掉而把这个子节点静默丢失

这使得树查询更稳健，更适合业务前台直接使用。

6. 缓存化字典查询​

6.1 平铺缓存​

当前模块会缓存按字典编码查询出来的平铺列表。

适用场景：

  • 高频读取状态枚举
  • 多页面共用同一批基础字典
  • 微服务场景下减少重复回源

6.2 树缓存​

当前模块还会缓存树查询结果。

适用场景：

  • 分类树读取频繁
  • 区域树频繁加载
  • 页面初始化需要快速返回整棵字典树

6.3 自动失效​

在以下情况发生时，系统会自动清理相关缓存：

  • 字典类型更新或删除
  • 字典项新增、更新、删除

因此业务方通常不需要自己额外处理字典缓存一致性。

7. 典型业务场景​

7.1 后台维护订单状态​

例如：

  • 新建
  • 待处理
  • 已支付
  • 已关闭

前端列表页展示名称，后端业务逻辑仍使用稳定的 itemValue。

7.2 维护区域树​

例如：

  • 中国
    • 上海
    • 北京
  • 美国
    • 加州

前端可以直接调用树接口构建级联选择器。

7.3 维护标签颜色与默认值​

例如一个“工单优先级”字典：

  • 高优先级：红色标签
  • 中优先级：橙色标签
  • 低优先级：蓝色标签

通过 tagColor 和 defaultFlag，可以直接给前端更多展示信息。

7.4 维护带扩展属性的业务分类​

例如：

  • 分类节点除名称外，还想附带 icon、description、permissionKey

此时可以通过 extraJson 承载扩展信息，而不必为每个业务再单独设计一套枚举表。