# 动态配置 开发

系统配置使用 DynamicConfig 进行定义,以下是在系统中,自定义配置的相关说明。

# 目标读者

本文档的目标读者为:本系统的开发、实施、运维人员,或需要进行系统配置的高级用户。

# 配置定义

新建 DynamicConfig 对象即可创建新的配置,其中相关字段描述如下:

字段 描述
name 本配置的名称,供开发及配置人员参考
key 用于在前后端 API 中获取配置的配置键
value 配置的值
attachment 可以上传一个可选的附件用于保存配置值
parent 配置所属的上级配置目录,可用于组织一组关联的配置
description 配置描述
modifyRemark 配置修改的备注
allowPublicAccess 是否允许匿名用户访问该配置并获取值
icon 维护配置时,在前端配置树上显示的图标
isSystem 是否为系统内置配置,系统内置配置定义不允许删除

# 前台获取配置 API

前台定义了 useConfig React Hook,用于获取配置。具体用法示例如下:

import { useConfig } from "@utils/hooks";
// 举例如下: 获取系统配置中,key 为 register.self_register 的配置值
// 备注: 对于系统内置配置,前台会自动转换配置值的类型,如上述代码调用
// `useConfig` 返回的 `registerEnable` 变量,其类型为 `boolean`。
const { value: registerEnable } = useConfig('register.self_register');
1
2
3
4

# 后台获取配置 API

后台定义了 Spring Bean DynamicConfigService 服务,用于获取配置。

具体可用方法如下:

/**
 * 获取 DynamicConfig 中配置的值,当前支持的配置类型包括
 * <ul>
 *   <li> String
 *   <li> Integer
 *   <li> Long
 *   <li> Decimal
 *   <li> Datetime
 *   <li> Date
 *   <li> Boolean
 *   <li> java.lang.Enum
 *   <li> Object (须在配置时,填写 id )
 * </ul>
 * @param configKey 配置的 Key
 * @param valueClazz 配置值的类型
 * @param defaultValue 默认值
 * @return config value 配置的值,已经转化为 valueClazz 指定的类型
 */
 <T> T getConfig(String configKey, Class<T> valueClazz, T defaultValue);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

在代码中使用示例如下:

  1. 在后台 Service 或 Controller 中,可直接注入 Bean DynamicConfigService, 或者调用 ConfigHelper.getDynamicConfigService(grailsApplication) 获取该 Bean。

  2. 在客制化代码中,可以通过如下方式获取系统配置中的值

 import tech.muyan.ConfigHelper
 String frontendUrl = ConfigHelper.getDynamicConfigService(grailsApplication)
                                  .getConfig("mail.frontend_url", String.class, "https://muyan.muyan.cloud")   
1
2
3

# 动态配置与环境变量

如果使用 API 获取配置时,没有获取到对应 Key 的 DynamicConfig,系统则会回退到使 用操作系统环境变量获取配置值,如果对应的操作系统环境变量也为空,则会返回调用时指 定的默认值。

具体 DynamicConfig 的 Key 回退(fallback) 到使用环境变量时,key 的映射关系为:

  1. 将配置 Key 中的所有字母大写
  2. 将配置 Key 中的所有 . 替换为 _

如,配置 Key 为 mail.frontend_url,则回退到使用环境变量时,会尝试获取环境变量 MAIL_FRONTEND_URL 的值。

最后更新: 2024/5/26 15:43:38