跳到主要内容

Nebula Param 业务功能

1. 功能概览​

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

  • 系统参数管理
  • 按参数键读取
  • 按模块加载参数
  • 批量更新参数值
  • 参数值校验与治理

这些能力围绕“统一维护运行期配置，并保证配置值可控、可读、可按页面组织”展开，而不是孤立的几条 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/system-params/key/{paramKey}

它适合以下场景：

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

3.2 读取布尔值​

当前接口：

GET /api/param/system-params/key/{paramKey}/boolean

适合场景：

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

业务价值：

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

3.3 读取整数值​

当前接口：

GET /api/param/system-params/key/{paramKey}/integer

适合场景：

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

业务价值：

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

4. 按模块加载参数​

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

当前接口：

GET /api/param/system-params/module/{moduleCode}

它适合以下场景：

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

4.2 当前返回边界​

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

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

这意味着：

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

5. 批量更新参数值​

5.1 一次保存多个设置项​

当前接口：

POST /api/param/system-params/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 受控选项型参数​

例如：

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

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

8. 业务落地建议​

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

推荐放入：

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

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

不建议放入：

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

8.3 参数键设计建议​

建议：

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

这样做有利于：

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