4. 参数化配置基础：变量定义、默认值、必填参数、可选参数的设计方法

在标准模板驱动的 SLO 作业框架中，参数化配置是连接“通用模板”与“具体环境”的核心桥梁。本章将系统讲解参数变量的定义规范、默认值策略、必填与可选参数的划分原则，以及如何通过合理的参数设计实现跨环境（开发、测试、预发、生产）的无缝复用。

4.1 参数变量的定义与命名规范

参数变量是模板中可被外部赋值的占位符。一个良好的变量定义应包含：变量名、数据类型、描述、默认值、必填/可选标记。以下为推荐的定义结构：

4.2 默认值的设计策略

默认值是参数化配置的“安”。合理的默认值可以降低配置复杂度，同时避免因遗漏参数导致的作业失败。默认值设计应遵循以下原则：

• 安全优先：默认值应选择最保守、最安全的取值，避免因默认值过大或过小引发生产事故。例如 SLO 目标默认值设为 0.999 而非 1.0。
• 环境感知：不同环境应有不同的默认值。开发环境可放宽阈值，生产环境应收紧。
• 可覆盖性：默认值必须能被显式传入的参数覆盖，且覆盖行为应明确记录在日志中。
• 类型一致：默认值的数据类型必须与变量定义的类型严格一致，避免隐式类型转换带来的风险。

# 示例：YAML 格式的参数定义
parameters:
  - name: slo_target
    type: number
    description: "SLO 目标值，0.0 ~ 1.0"
    default: 0.999
    required: false
  - name: evaluation_window
    type: string
    description: "评估时间窗口，如 1h, 5m, 24h"
    default: "5m"
    required: false
  - name: service_name
    type: string
    description: "目标服务名称"
    default: null
    required: true

4.3 必填参数与可选参数的划分

必填参数与可选参数的划分直接影响模板的易用性与安全性。划分原则如下：

4.4 参数化配置的完整流程

下图展示了从模板定义到环境实例化的完整参数化配置流程：

4.5 参数作用域与覆盖优先级

在多环境、多层级配置场景中，参数的作用域和覆盖优先级决定了最终生效的值。推荐采用以下优先级规则（从高到低）：

1. 运行时显式传入参数（最高优先级，如 CLI 参数、API 请求体）
2. 环境变量（如 ENV=production 时加载对应配置）
3. 环境专属配置文件（如 config.prod.yaml）
4. 模板默认值（最低优先级）

4.6 参数化配置的常见模式对比

4.7 参数校验与错误处理

参数校验是防止配置错误进入生产环境的第一道防线。推荐在模板引擎中内置以下校验规则：

• 必填检查：所有标记为 required 的参数必须非空。
• 类型检查：传入值的数据类型必须与定义一致。
• 范围检查：数值型参数应在指定范围内（如 0.0 ≤ slo_target ≤ 1.0）。
• 格式检查：字符串参数应符合正则模式（如 ^[a-z0-9-]+$）。
• 依赖检查：条件必填参数在条件成立时必须赋值。

# 参数校验伪代码示例
def validate_parameters(params, template_schema):
    for param in template_schema:
        if param.required and param.name not in params:
            raise ConfigError(f"Missing required parameter: {param.name}")
        if param.name in params:
            value = params[param.name]
            if not isinstance(value, param.type):
                raise TypeError(f"Parameter {param.name} expects {param.type}, got {type(value)}")
            if hasattr(param, 'range') and not (param.range[0] <= value <= param.range[1]):
                raise ValueError(f"Parameter {param.name} out of range: {value}")

4.8 参数化配置的版本管理

参数定义与模板本身一样，需要纳入版本管理。建议将参数 schema 文件与模板文件一同存储在 Git 仓库中，并在每次修改时更新版本号。以下为推荐的版本管理策略：

4.9 本章小结