跳到主要内容

Nebula Param 业务功能

1. 功能概览​

从当前代码与 README 可以确认,nebula-param 对业务系统提供的能力主要包括七类:

  • 系统参数管理
  • 按参数键读取
  • 按模块加载参数
  • 批量更新参数值
  • 参数值校验与治理
  • 写操作 Hook
  • 领域事件通知

这些能力围绕“统一维护运行期配置,并保证配置值可控、可读、可按页面组织”展开,而不是孤立的几条 CRUD 接口。


2. 系统参数管理​

2.1 创建系统参数​

适用场景:

  • 为某个业务模块新增一项运行期配置
  • 给后台设置页增加可维护项
  • 统一沉淀项目里的硬编码配置

典型例子:

  • auth.login.username.login-fail-max-count
  • frontend.project-name
  • notify.mail.default-from-name
  • storage.signed-download.default-expire-seconds

业务价值:

  • 把散落在代码和配置文件里的可变参数收口到统一模型里
  • 让前端和后端围绕统一 paramKey 协作
  • 为动态配置、统一设置页和远程配置中心打基础

2.2 更新系统参数​

适用场景:

  • 调整阈值、默认值和提示文案
  • 修改参数类型约束
  • 调整展示位置和模块归属
  • 调整敏感性、可见性和可编辑性

2.3 删除系统参数​

当前规则:

  • 参数采用软删除
  • 参数删除后,对应按 key 缓存会被清理

业务价值:

  • 避免直接物理删除导致审计和数据恢复困难
  • 保证删除后不会继续读到旧缓存值

3. 按参数键读取​

3.1 读取字符串值​

当前接口:

GET /api/param/key/{paramKey}

它适合以下场景:

  • 前端初始化读取平台标题、默认配置
  • 后端读取 JSON 文本配置
  • 业务逻辑读取普通字符串型参数

3.2 读取布尔值​

当前接口:

GET /api/param/key/{paramKey}/boolean

适合场景:

  • 是否启用注册
  • 是否开启验证码
  • 是否允许分享下载
  • 是否启用某实验功能

业务价值:

  • 让开关类配置直接以布尔语义读取
  • 避免业务方自己重复写 "true".equalsIgnoreCase(...)

3.3 读取整数值​

当前接口:

GET /api/param/key/{paramKey}/integer

适合场景:

  • 最大失败次数
  • 默认分页大小
  • 导出条数限制
  • 默认超时时长

业务价值:

  • 把常见数值配置读取集中在参数模块处理
  • 非法值会统一抛出参数错误,而不是悄悄返回错误结果

4. 按模块加载参数​

4.1 按模块编码查询参数列表​

当前接口:

GET /api/param/module/{moduleCode}

它适合以下场景:

  • 前端设置页按模块分组展示参数
  • 后台“系统设置”页面一次加载某一组配置
  • 模块管理页按顺序渲染一批系统参数

4.2 当前返回边界​

从服务层实现可以确认,按模块加载当前只会返回:

  • moduleCode 匹配的数据
  • visibleFlag = true 的数据
  • 按 displayOrder 排序后的结果

这意味着:

  • 它不是全量审计接口
  • 更适合拿来构建“模块设置页”
  • 页面可以直接按返回顺序渲染,而不需要前端自己再排序

5. 批量更新参数值​

5.1 一次保存多个设置项​

当前接口:

POST /api/param/batch-update-values

请求体为一个列表,每项包括:

  • paramKey
  • paramValue

它适合以下场景:

  • 页面点击“保存全部设置”
  • 一次修改一组模块参数
  • 表单型设置页的集中提交

5.2 当前批量更新规则​

服务层当前逐项执行以下逻辑:

  • 参数键不能为空
  • 参数必须存在
  • 参数必须允许编辑
  • 参数值必须通过类型和约束校验
  • 每项都单独返回成功或失败结果

业务价值:

  • 不会因为一项失败而失去对其他项结果的可见性
  • 前端可以精准提示哪些配置保存失败
  • editableFlag 为后台设置页提供了治理开关

6. 参数值校验能力​

6.1 字符串配置校验​

当前支持:

  • 最小长度
  • 最大长度
  • 正则表达式

适用场景:

  • URL 前缀
  • 编码规则
  • 手机号、邮箱、域名格式
  • 需要限制长度的展示文案

6.2 数值配置校验​

当前支持:

  • 最小值
  • 最大值
  • 类型合法性

适用场景:

  • 登录失败次数上限
  • 任务超时阈值
  • 导出上限
  • 小数比例与数值阈值

6.3 布尔配置校验​

当前要求值必须可解析为:

  • true
  • false

适用场景:

  • 任何功能开关类配置

6.4 字典选项校验​

对于 SINGLE 和 MULTIPLE 类型,当前会结合 optionCode 调用字典模块校验参数值是否合法。

适用场景:

  • 默认主题必须来自预设主题集合
  • 默认语言必须来自可选语言集合
  • 模块默认状态必须来自统一状态字典

这使参数模块非常适合做“配置值必须在合法集合内”的治理。


7. 典型业务场景​

7.1 登录安全策略参数化​

例如:

  • 最大连续失败次数
  • 锁定时长
  • 是否允许用户名注册

这类配置经常要根据业务变化调整,适合沉淀在参数中心中,而不是写死在代码里。

7.2 前端平台配置中心​

例如:

  • 项目名称
  • 默认主题编码
  • 默认语言
  • 可选语言集合

frontend 模块当前就已经通过参数中心来维护这些平台级配置。

7.3 后台模块设置页​

例如:

  • 通知设置
  • 存储设置
  • 首页展示设置
  • 某业务模块的可视化系统参数

前端可以先按 moduleCode 加载,再通过批量更新接口统一保存。

7.4 受控选项型参数​

例如:

  • 默认审核模式
  • 默认业务类型
  • 页面默认状态标签

如果参数值必须来源于一套稳定的可选项,那么可以把可选项放进字典模块,再让参数模块引用它。

7.5 参数变更联动业务​

例如:

  • 调整会员等级上限后,同步刷新依赖该阈值的缓存
  • 关闭某个功能开关后,立刻停掉相关定时任务
  • 删除非内建参数前,先检查业务侧是否仍在引用该 paramKey

这类“必须和参数写入同事务成功或失败”的逻辑,适合实现 SystemParamOperationHook。

如果只是通知其他模块“某个参数变了”,例如刷新本地缓存、写审计、异步重算,则应监听 param-created / param-updated / param-deleted,而不是在 Hook 里做跨模块副作用。


8. 写操作 Hook 能解决什么​

业务实现一个 SystemParamOperationHook Bean 后,可以在参数创建、更新、按 key 保存、删除和批量改值时介入。

典型用途:

  • 在 beforeUpdateSystemParam 中根据 existing.getParamKey() 判断关联业务是否允许本次变更
  • 在 beforeDeleteSystemParam 中阻止仍被业务引用的参数被删掉
  • 在 afterSaveOrUpdateSystemParamByKey 中按 created 区分“首次补齐”和“覆盖已有值”
  • 在批量更新前后做一次模块级缓存失效或一致性检查

不适合放进 Hook 的事情:

  • 跨服务通知、发邮件、调外部系统
  • 依赖参数值的异步处理(事件负载本身不含 paramValue,需要值应事后按 key 读取)

9. 领域事件能解决什么​

参数写成功后会发布:

  • param-created
  • param-updated
  • param-deleted

业务价值:

  • 其他模块不必轮询参数表,也能感知配置变化
  • param-updated 带 valueChanged,监听器可以忽略“只改了名称/模块归属”的更新
  • 载荷不含参数值,适合进入 outbox 和事件日志

10. 业务落地建议​

10.1 什么配置适合放到 param 模块​

推荐放入:

  • 运行期可能会调整的业务参数
  • 需要后台页面维护的系统设置
  • 需要按 key 被程序读取的动态配置
  • 需要多服务共享的稳定配置项

10.2 什么配置不适合放到 param 模块​

不建议放入:

  • 仅部署期生效、且不会运行期调整的基础设施配置
  • 密钥、数据库密码这类敏感基础设施凭据
  • 大块结构化配置文件内容

10.3 参数键设计建议​

建议:

  • 用模块前缀组织参数键,如 auth.login.*、frontend.*
  • 保持业务语义清晰
  • 一组参数统一前缀,便于理解和治理

这样做有利于:

  • 按模块组织管理
  • 后续迁移到设置页时更容易分组
  • 避免参数键杂乱无章