跳到主要内容

config

简介​

用于读取和管理应用程序的配置参数。该模块支持从 JSON 文件加载配置、验证配置的合法性，以及在运行时动态管理配置项。

config.gs 配置管理模块说明文档

概述​

config.gs 是一个功能强大的配置管理模块，用于读取和管理应用程序的配置参数。该模块支持从 JSON 文件加载配置、验证配置的合法性，以及在运行时动态管理配置项。

主要特性​

  • JSON 配置文件支持：从指定的 JSON 文件读取配置
  • JSON Schema 验证：使用 JSON Schema 验证配置的合法性
  • 本地配置覆盖：支持本地配置文件覆盖全局配置
  • 启动参数支持：通过命令行参数 --script-args 传递配置
  • 配置合并：智能合并多个配置源，支持深度合并
  • 动态配置管理：运行时增删改查配置项

API 档​

初始化函数​

create()​

模块初始化函数，自动执行以下操作：

  • 读取启动参数中的配置文件路径
  • 加载全局配置文件
  • 加载本地配置文件（如果存在）
  • 执行 JSON Schema 验证

配置文件查找顺序：

  1. 启动参数 --global 指定的路径
  2. 宏定义 __CONFIG__ 指定的路径
  3. 默认路径 /config.json

配置加载函数​

load(val, schema = nil)​

add_global_opts 的别名函数。

参数：

  • val: 配置数据（map 对象或文件路径）
  • schema: JSON Schema 验证文件路径（可选）

add_global_opts(val, schema = nil)​

批量添加全局配置参数。

参数：

  • val: 配置数据，可以是：
    • map 对象：直接添加到全局配置
    • 文件路径：从文件读取配置
  • schema: JSON Schema 验证文件路径（可选）

示例：

// 从文件加载配置
add_global_opts("/path/to/config.json", "/path/to/schema.json");

// 直接添加配置
add_global_opts({"database": {"host": "localhost", "port": 3306}});

add_global_opt(name, val)​

添加单个全局配置参数。

参数：

  • name: 参数名称
  • val: 参数值

示例：

add_global_opt("debug", true);
add_global_opt("timeout", 30);

配置读取函数​

boot_opt(name)​

获取启动参数（通过 --script-args 指定）。

参数：

  • name: 参数名称（自动添加 -- 前缀）

返回值： 参数值（字符串），不存在返回 nil

global_opt(name)​

获取全局配置参数。

参数：

  • name: 参数名称

返回值： 参数值，不存在返回 nil

opt(name)​

智能获取配置参数，优先返回启动参数，其次返回全局配置。

参数：

  • name: 参数名称

返回值： 参数值，不存在返回 nil

query(name)​

通过路径表达式获取嵌套的配置项。

参数：

  • name: 路径表达式（如 "database.host"）

返回值： 配置值

示例：

// 假设配置为 {"database": {"host": "localhost", "port": 3306}}
string host = query("database.host");  // 返回 "localhost"

get_global_config()​

获取全部的全局配置。

返回值： 包含所有配置的 map 对象

配置修改函数​

set(name, val)​

通过路径表达式设置配置项。

参数：

  • name: 路径表达式
  • val: 新的值

示例：

set("database.host", "192.168.1.100");
set("debug", false);

工具函数​

merge_opts(opts1, opts2)​

深度合并两个配置 map。

参数：

  • opts1: 基础配置
  • opts2: 要合并的配置

返回值： 合并后的新配置

合并规则：

  • 相同 key 的 map 值会递归合并
  • 其他类型的值会被 opts2 覆盖

is_valid(opts, schema)​

验证配置是否符合 JSON Schema。

参数：

  • opts: 要验证的配置
  • schema: JSON Schema 文件路径或内容

返回值： 验证是否通过（boolean）

get_by_class_map(a, key = nil)​

通过 class_map 模板读取配置。

参数：

  • a: class_map 实例
  • key: 配置中的键名（可选）

返回值： 填充了配置值的 class_map 实例

特性：

  • 自动匹配 class_map 中的字段名
  • 如果 class_map 包含 valid() 方法，会调用进行验证

使用示例​

基本使用​

import src.config;

// 获取配置值
string db_host = config.opt("db_host");
int timeout = config.global_opt("timeout");

// 设置配置值
config.add_global_opt("api_key", "your-api-key");
config.set("server.port", 8080);

配置文件示例​

config.json:

{
  "server": {
    "host": "0.0.0.0",
    "port": 8080,
    "ssl": false
  },
  "database": {
    "type": "mysql",
    "host": "localhost",
    "port": 3306,
    "name": "myapp"
  },
  "logging": {
    "level": "info",
    "file": "/var/log/app.log"
  }
}

config.local.json:

{
  "server": {
    "port": 8081
  },
  "database": {
    "host": "192.168.1.100"
  },
  "logging": {
    "level": "debug"
  }
}

JSON Schema 验证示例​

schema.json:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "server": {
      "type": "object",
      "properties": {
        "host": {"type": "string"},
        "port": {"type": "integer", "minimum": 1, "maximum": 65535}
      },
      "required": ["host", "port"]
    }
  }
}

启动参数使用​

# 指定配置文件
./bin/gs --global=/path/to/config.json --schema=/path/to/schema.json

# 传递额外参数
./bin/gs --script-args "--debug=true --timeout=60"

Class Map 使用示例​

class DatabaseConfig {
    string type = nil;
    string host = nil;
    int port = 0;
    string name = nil;

    bool valid() {
        return port > 0 && port < 65536;
    }
}

// 读取数据库配置
DatabaseConfig db_config = config.get_by_class_map(DatabaseConfig, "database");
if (db_config != nil) {
    println("Database: " + db_config.type + "://" + db_config.host + ":" + db_config.port);
}

组件接口​

config.gs​

函数原型函数作用
void load(mixed val, mixed schema = nil)add_global_opts 的别名
void add_global_opts(mixed val, mixed schema = nil)通过文件或者map, 批量增加 global 参数
map merge_opts(map opts1, map opts2)合并两个 map,
bool is_valid(mixed opts, mixed schema)验证参数是否符合 schema
void add_global_opt(string name, mixed val)添加单个全局参数
string boot_opt(string name)获取启动参数, 在启动命令行通过 --script-args 指定
mixed global_opt(string name)获取全局参数
mixed opt(string name)优先获取启动参数, 如果启动参数不存在, 获取全局设置
mixed query(string name)通过路径获取配置项
void set(string name, mixed val)通过路径设置配置项
class_map get_by_class_map(class_map a, string key = nil)通过 class map 里面已有的项 读取配置
map get_global_config()获取全部的配置项