# Dynamic Configuration Development

System configuration is defined using DynamicConfig. The following is an explanation of custom configurations in the system.

# Target Audience

The target audience for this document is: developers, implementers, operations personnel of this system, or advanced users who need to configure the system.

# Configuration Definition

Creating a new DynamicConfig object creates a new configuration. The relevant fields are described as follows:

Field	Description
name	The name of this configuration, for reference by developers and configuration personnel
key	The configuration key used to retrieve the configuration in front-end and back-end APIs
value	The value of the configuration
attachment	An optional attachment can be uploaded to store the configuration value
parent	The parent configuration directory to which the configuration belongs
description	Configuration description
modifyRemark	Remarks for configuration modifications
allowPublicAccess	Whether to allow anonymous users to access this configuration and obtain its value
icon	The icon displayed on the front-end configuration tree when maintaining configurations
isSystem	Whether it is a system built-in configuration, which cannot be deleted

# Front-end Configuration Retrieval API

The front-end defines a useConfig React Hook for retrieving configurations. Here's an example of its usage:

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

# Back-end Configuration Retrieval API

The back-end defines a Spring Bean DynamicConfigService service for retrieving configurations.

The available methods are as follows:

/**
 * 获取 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

Example of usage in code:

# Dynamic Configuration and Environment Variables

If the API fails to retrieve a DynamicConfig for the corresponding Key when fetching a configuration, the system will fall back to using operating system environment variables to get the configuration value. If the corresponding operating system environment variable is also empty, it will return the default value specified in the call.

When a DynamicConfig Key falls back to using environment variables, the key mapping relationship is as follows:

Capitalize all letters in the configuration Key
Replace all . in the configuration Key with _

For example, if the configuration Key is mail.frontend_url, when falling back to using environment variables, it will attempt to get the value of the environment variable MAIL_FRONTEND_URL.

← 🕹️ Dynamic Actions 🔑 Dynamic Permission Control →