AUTO-MAS

Appearance

配置管理 ​

AUTO-MAS 的后端使用了一个特殊的配置管理模块，实现了配置字段自动矫正、配置自动同步保存到文件等功能。

相关代码 ​

配置基类 ​

  • 位置: app/models/ConfigBase.py
  • 用途：定义了配置管理模块的基础方法，提供多种配置自动校验器。

配置模板 ​

  • 位置: app/models/config.py
  • 用途：定义了程序实际使用的配置字段，确定了各种配置字段的名称、类型、默认值、校验器、描述等信息，确定了各种配置项的层级关系。

配置管理模块 ​

  • 位置: app/core/config.py
  • 用途：提供全局变量 Config 作为访问程序配置的入口。

配置字段 ​

配置字段 是 ConfigItem 的实例，定义了配置字段的分组、名称、默认值、校验方法。

定义配置字段 ​

python
Group_Name = ConfigItem("Group", "Name", "默认值", [Validator()])

含义： 定义了一个配置字段，字段名为 Name，字段所属分组为 Group，字段默认值为 "默认值"，字段使用 Validator() 进行校验与修正。

注意： 配置字段变量名与 ConfigItem 中的 Name、Group 参数必须严格对应，配置字段变量名必须符合 {Group}_{Name} 格式。

配置字段校验器 ​

定义配置字段校验器后，配置管理模块会自动调用该校验器对配置字段进行校验与修正，有时也被用来实现特殊的字段逻辑。

已有校验器：

  1. 基础配置验证器

    • 定义：ConfigValidator()
    • 作用：验证器基类，默认配置校验器，不对配置字段进行任何校验。

  2. 范围验证器

    • 定义：RangeValidator(min, max)
    • 作用：校验数值是否处于指定范围之间，否则修正为最小值或最大值。

  3. 选项验证器

    • 定义：OptionsValidator(options)
    • 作用：校验字段值是否在指定选项列表中，否则修正为选项列表中的第一个选项。

  4. UUID 格式验证器

    • 定义：UUIDValidator()
    • 作用：校验字段值是否符合 UUID 格式，否则修正为随机 UUID。

  5. 日期时间格式验证器

    • 定义：DateTimeValidator(date_format)
    • 作用：校验字段值是否符合指定日期时间格式，否则修正为默认时间对应的指定格式字符串。

  6. JSON 格式验证器

    • 定义：JSONValidator(type)
    • 作用：校验字段值是否能按 JSON 格式解析为字典或列表，否则修正为空字典或空列表。

  7. 加密数据验证器

    • 定义：EncryptValidator()
    • 作用：校验字段值是否能被 DPAPI 解密，否则修正为 "数据损坏, 请重新设置"。

  8. 虚拟配置字段验证器

    • 定义：VirtualConfigValidator(function)
    • 作用：用于定义一个虚拟配置字段。该配置字段的 value 实例属性将被视为配置字段的内部变量，可以被 function 使用。在保存内容到字段时，将会直接将内容保存到 value 变量中；在获取该字段的值时，将会调用 function 并返回该回调函数的返回值。这与 Python 装饰器 @property 的功能类似，目标是让程序能用调用配置项的方法获取一个 function 的返回值。

  9. 布尔值验证器

    • 定义：BoolValidator()
    • 作用：校验字段值是否为布尔值，否则修正为 True。

  10. 文件 / 文件夹路径验证器

    • 定义：FileValidator() / FolderValidator
    • 作用：校验字段值是否为合法的绝对路径且不是快捷方式，否则尝试修正为对应绝对路径，失败则重置为当前工作目录。

  11. 用户名验证器

    • 定义：UserNameValidator()
    • 作用：校验用户名是否合法。要求为非空字符串，不能包含非法字符，不能为保留名，长度不超过 255，且不能首尾有空格或点号。非法时修正为 "默认用户名"。

  12. 多配置管理类 UID 验证器

    • 定义：MultipleUIDValidator(default, related_config, config_name)
    • 作用：校验字段值是否是指定 多配置管理实例 中的一个配置的 UID，否则修正为默认值。

单配置模板 ​

单配置模板 是继承自 ConfigBase 的类，定义了一种配置变量下应该包含哪些 配置字段 与 多配置管理实例。实例化后即为 单配置管理实例，可用于实际的配置管理。

定义单配置模板 ​

python
class ConfigModel(ConfigBase):

    Group_Name = ConfigItem("Group", "Name", "默认值", [Validator()])
    MultiConfig = MultipleConfig([ConfigModel]) # 多配置管理实例
    ... # 类属性

    def __init__(self) -> None:
        super().__init__()

        self.Group_Name = ConfigItem("Group", "Name", "默认值", [Validator()])
        self.MultiConfig = MultipleConfig([ConfigModel]) # 多配置管理实例
        ... # 实例属性

关于类属性与实例属性

  • 若将配置项设为类属性, 则所有实例都会共享同一份配置项数据。
  • 若将配置项设为实例属性, 则每个实例都会有独立的配置项数据。

关于多配置管理实例的 if_save_needed 字段

  • True：单配置管理实例保存到配置文件时，该 多配置管理实例 也会被保存到同一个配置文件中；从该配置文件导入配置时，该 多配置管理实例 也会被一并导入。
  • False：该 多配置管理实例 仅是一个属性，可以通过成员运算符直接访问，但不会被保存到配置文件，也不能从对应配置文件中导入。

使用单配置管理实例 ​

自行阅读程序内相关函数定义与注释。

多配置管理实例 ​

多配置管理实例 是 MultipleConfig 的实例，同时具备了 字典、单配置管理实例 与 配置字段 的特性。可以像访问字典的一样，以 UID 作为键访问 单配置管理实例 值；也可以像使用 单配置管理实例 一样，将实例与配置文件绑定，将配置内容保存到配置文件；还可以像 配置字段 一样，成为 单配置管理实例 的属性。

定义多配置管理实例 ​

python
MultiConfig = MultipleConfig([ConfigModel_1, ConfigModel_2, ...])

与 List[type] 的作用类似，定义 多配置管理实例 时需要指定可能作为其值的 单配置管理实例 类型。

使用多配置管理实例 ​

自行阅读程序内相关函数定义与注释。