# 动态配置 开发
系统配置使用 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`。
// Example: Get the configuration value of the key register.self_register in the system configuration
// Note: For system built-in configurations, the frontend will automatically convert the type of the configuration value,
// as shown in the above code call
// The type of the registerEnable variable returned by `useConfig` is `boolean`.
const { value: registerEnable } = useConfig('register.self_register');1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
# 后台获取配置 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
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
在代码中使用示例如下:
在后台 Service 或 Controller 中，可直接注入 Bean
DynamicConfigService, 或者调用ConfigHelper.getDynamicConfigService(grailsApplication)获取该 Bean。在客制化代码中，可以通过如下方式获取系统配置中的值
import tech.muyan.ConfigHelper
String frontendUrl = ConfigHelper.getDynamicConfigService(grailsApplication)
.getConfig("mail.frontend_url", String.class, "https://muyan.muyan.cloud")
1
2
3
2
3
# 动态配置与环境变量
如果使用 API 获取配置时，没有获取到对应 Key 的 DynamicConfig，系统则会回退到使
用操作系统环境变量获取配置值，如果对应的操作系统环境变量也为空，则会返回调用时指
定的默认值。
具体 DynamicConfig 的 Key 回退(fallback) 到使用环境变量时，key 的映射关系为:
- 将配置 Key 中的所有字母大写
- 将配置 Key 中的所有
.替换为_
如，配置 Key 为 mail.frontend_url，则回退到使用环境变量时，会尝试获取环境变量
MAIL_FRONTEND_URL 的值。