DDNS 配置系统开发文档

本文档面向开发者，详细说明如何扩展和修改 DDNS 配置系统。

系统架构

DDNS 配置系统采用分层架构，支持多种配置源：

text

┌─────────────────────────────────────────────┐
│               配置源（优先级）                │
├─────────────────────────────────────────────┤
│ CLI 参数 > JSON 文件 > 环境变量 > 默认值      │
├─────────────────────────────────────────────┤
│                Config 类                     │
│            统一配置访问接口                   │
├─────────────────────────────────────────────┤
│            Provider 和应用模块               │
└─────────────────────────────────────────────┘

核心模块：

ddns/config/cli.py - 命令行参数解析
ddns/config/json.py - JSON 配置文件处理
ddns/config/env.py - 环境变量解析
ddns/config/config.py - Config 类实现

Config 类核心实现

Config 类是配置系统的核心，负责合并多个配置源：

python

class Config(object):
    def __init__(self, cli_config=None, json_config=None, env_config=None):
        self._cli_config = cli_config or {}
        self._json_config = json_config or {}  
        self._env_config = env_config or {}
        
        # 配置属性初始化
        self.dns = self._get("dns", "debug")
        self.endpoint = self._get("endpoint")  # 新增的端点配置
        
    def _get(self, key, default=None):
        """按优先级获取配置值：CLI > JSON > ENV > default"""
        return (
            self._cli_config.get(key) or 
            self._json_config.get(key) or 
            self._env_config.get(key) or 
            default
        )

配置参数概览

必需参数

id - DNS 服务商认证 ID
token - DNS 服务商 API Token

主要参数

dns - DNS 服务商标识 (默认: "debug")
endpoint - 自定义 API 端点 (覆盖默认端点)
ipv4/ipv6 - 域名列表
ttl - DNS TTL 值
proxy - HTTP 代理设置
log_level - 日志级别

支持的 DNS 服务商

python

SUPPORTED_PROVIDERS = [
    "alidns", "callback", "cloudflare", "debug", "dnscom", 
    "dnspod_com", "dnspod", "he", "huaweidns", "noip", "tencentcloud"
]

开发指南：添加新配置参数

完整开发流程

添加新配置参数需要修改 4 个文件：

1. 更新 JSON Schema (`schema/v4.0.json`)

json

{
  "properties": {
    "my_param": {
      "type": "string",
      "title": "My Parameter", 
      "description": "Description of my parameter",
      "default": "default_value"
    }
  }
}

2. 添加 CLI 参数 (`ddns/config/cli.py`)

python

def create_parser(description, doc, version, date):
    # ...existing code...
    parser.add_argument(
        "--my-param",
        help="Description of my parameter",
        default=None
    )

3. 更新 Config 类 (`ddns/config/config.py`)

python

class Config(object):
    def __init__(self, cli_config=None, json_config=None, env_config=None):
        # ...existing code...
        self.my_param = self._get("my_param", "default_value")
        
    def dict(self):
        return {
            # ...existing fields...
            "my_param": self.my_param,
        }

4. 添加单元测试 (`tests/test_config_config.py`)

python

def test_my_param_configuration(self):
    """Test my_param configuration from different sources"""
    # CLI 配置测试
    config = Config(cli_config={"my_param": "cli_value"})
    self.assertEqual(config.my_param, "cli_value")
    
    # JSON 配置测试
    config = Config(json_config={"my_param": "json_value"})
    self.assertEqual(config.my_param, "json_value")
    
    # 优先级测试
    config = Config(
        cli_config={"my_param": "cli_value"},
        json_config={"my_param": "json_value"}
    )
    self.assertEqual(config.my_param, "cli_value")  # CLI 优先

环境变量支持

新参数自动支持环境变量，命名规则：DDNS_PARAM_NAME

bash

export DDNS_MY_PARAM=value

特殊类型处理

数组参数

需要在 SIMPLE_ARRAY_PARAMS 中注册：

python

# config.py
SIMPLE_ARRAY_PARAMS = ["ipv4", "ipv6", "proxy", "my_array_param"]

def split_array_string(value):
    """支持多种分隔符：逗号、分号"""
    if isinstance(value, list):
        return value
    # 支持 "a,b" 或 "a;b" 格式
    if "," in str(value):
        return [item.strip() for item in value.split(",")]
    elif ";" in str(value):
        return [item.strip() for item in value.split(";")]
    return [value]

布尔值处理

使用 str_bool() 函数：

python

def str_bool(value):
    """将字符串转换为布尔值"""
    if isinstance(value, bool):
        return value
    if str(value).lower() in ["true", "yes", "1", "on"]:
        return True
    if str(value).lower() in ["false", "no", "0", "off"]:
        return False
    return bool(value)

类型转换示例

python

# 在 Config.__init__ 中
self.ttl = int(self._get("ttl")) if self._get("ttl") else None
self.cache = str_bool(self._get("cache", True))
self.proxy = self._get("proxy", [])  # 自动处理数组

配置使用示例

CLI 基本用法

bash

python -m ddns --dns=cloudflare --endpoint=https://api.custom.com/v4/

JSON 配置

jsonc

{
  "dns": "cloudflare",
  "endpoint": "https://api.custom.com/v4/",
  "ipv4": ["example.com"]
}

环境变量

bash

export DDNS_DNS=cloudflare
export DDNS_ENDPOINT=https://api.custom.com/v4/

开发和调试

配置验证

python

def validate_config(config):
    """验证配置完整性"""
    errors = []
    
    if not config.id or not config.token:
        errors.append("id and token are required")
        
    if config.dns not in SUPPORTED_DNS_PROVIDERS:
        errors.append("Unsupported DNS provider: {}".format(config.dns))
    
    if config.ttl and (config.ttl < 1 or config.ttl > 86400):
        errors.append("TTL must be between 1 and 86400 seconds")
            
    return errors

配置调试

python

def debug_config(config):
    """输出配置信息（隐藏敏感数据）"""
    config_dict = config.dict()
    for key, value in config_dict.items():
        if key == "token" and value:
            value = value[:2] + "***" + value[-2:]
        print("{}: {}".format(key, value))

开发测试

bash

# 运行配置相关测试
python -m unittest discover tests -k "test_config" -v

# 测试特定功能
python -m unittest tests.test_config_config.TestConfigPriority -v

测试工具

python

def create_test_config(**overrides):
    """创建测试配置"""
    default_config = {
        "dns": "debug",
        "id": "test_id", 
        "token": "test_token"
    }
    default_config.update(overrides)
    return Config(json_config=default_config)

# 使用
config = create_test_config(dns="cloudflare", endpoint="https://api.test.com")

开发最佳实践

添加新参数的检查清单

✅ JSON Schema - 在 schema/v4.0.json 中定义
✅ CLI 参数 - 在 cli.py 中添加 --param-name
✅ Config 类 - 在 config.py 中添加属性和 dict() 方法
✅ 单元测试 - 测试配置优先级和类型转换
✅ 向后兼容 - 提供合理的默认值

代码规范

类型安全：使用 str_bool(), int() 等转换函数
默认值：所有新参数必须有默认值
命名规范：参数名使用下划线，CLI 使用连字符
文档同步：更新 JSON Schema 和相关文档

endpoint 参数特性

endpoint 参数是 v4.0 新增功能，主要用于：

覆盖 DNS Provider 的默认 API 端点
支持测试环境和自定义域名
在 Provider 初始化时优先于类的 API 属性

配置系统架构优势

多源融合：CLI、JSON、环境变量无缝合并
优先级明确：CLI > JSON > ENV > 默认值
类型安全：自动类型转换和验证
易于扩展：添加新参数只需 4 步
向后兼容：新参数不影响现有功能

通过这个配置系统，开发者可以快速添加新功能参数，保持代码的一致性和可维护性。

DDNS 配置系统开发文档 ​

系统架构 ​

Config 类核心实现 ​

配置参数概览 ​

必需参数 ​

主要参数 ​

支持的 DNS 服务商 ​

开发指南：添加新配置参数 ​

完整开发流程 ​

1. 更新 JSON Schema (schema/v4.0.json) ​

2. 添加 CLI 参数 (ddns/config/cli.py) ​

3. 更新 Config 类 (ddns/config/config.py) ​

4. 添加单元测试 (tests/test_config_config.py) ​

环境变量支持 ​

特殊类型处理 ​

数组参数 ​

布尔值处理 ​

类型转换示例 ​

配置使用示例 ​

CLI 基本用法 ​

JSON 配置 ​

环境变量 ​

开发和调试 ​

配置验证 ​

配置调试 ​

开发测试 ​

测试工具 ​

开发最佳实践 ​

添加新参数的检查清单 ​

代码规范 ​

endpoint 参数特性 ​

配置系统架构优势 ​

DDNS 配置系统开发文档

系统架构

Config 类核心实现

配置参数概览

必需参数

主要参数

支持的 DNS 服务商

开发指南：添加新配置参数

完整开发流程

1. 更新 JSON Schema (`schema/v4.0.json`)

2. 添加 CLI 参数 (`ddns/config/cli.py`)

3. 更新 Config 类 (`ddns/config/config.py`)

4. 添加单元测试 (`tests/test_config_config.py`)

环境变量支持

特殊类型处理

数组参数

布尔值处理

类型转换示例

配置使用示例

CLI 基本用法

JSON 配置

环境变量

开发和调试

配置验证

配置调试

开发测试

测试工具

开发最佳实践

添加新参数的检查清单

代码规范

endpoint 参数特性

配置系统架构优势