3. 参数配置基础：参数的类型、命名规范与默认值

告警路由模板的核心是参数。参数定义了路由规则的行为边界，决定了告警如何被匹配、转换和分发。本章将系统讲解参数的四种基础类型、命名规范以及默认值设计原则，为后续编写标准模板打下坚实基础。

3.1 参数类型

告警路由模板支持四种基础参数类型，每种类型对应不同的数据结构和校验规则：

3.2 参数命名规范

良好的命名规范能提升模板的可读性和可维护性。告警路由模板采用 snake_case（小写字母 + 下划线）作为统一命名风格：

• 全小写：避免大小写敏感带来的歧义，如 alert_source 而非 alertSource。
• 下划线分隔：单词之间使用单下划线，如 escalation_policy。
• 前缀分组：相关参数使用相同前缀，如 filter_severity、filter_environment。
• 避免缩写：除非是业界公认缩写（如 id、url），否则使用完整单词。

3.3 参数的默认值

默认值是参数在用户未显式赋值时使用的回退值。合理的默认值能降低模板使用门槛，同时保证安全性。

默认值设计原则：

• 安全优先：默认值应选择最保守的选项。例如，布尔参数 enable_notification 默认设为 false，避免误开启通知风暴。
• 可预测性：默认值应让模板行为可预期。例如，列表参数默认设为空列表 [] 而非 null，避免空指针异常。
• 文档化：每个默认值必须在参数描述中明确标注，并在模板注释中说明选择理由。

# 参数定义示例（YAML 格式）
parameters:
  - name: alert_severity
    type: string
    default: "warning"
    description: "告警严重级别，可选值：critical, warning, info"
  - name: timeout_seconds
    type: number
    default: 300
    description: "路由等待超时时间，单位秒，默认 5 分钟"
  - name: enable_silence
    type: boolean
    default: false
    description: "是否启用静默模式，默认关闭"
  - name: target_channels
    type: list
    default: []
    description: "通知渠道列表，默认不发送任何通知"

3.4 参数类型与默认值的关系

下图展示了参数类型、命名规范与默认值之间的协作关系，以及它们在告警路由模板中的位置：

3.5 常见配置错误与避坑

3.6 参数配置清单

编写告警路由模板时，请按以下清单逐项检查参数配置：

1. 每个参数是否已明确指定类型（string/number/boolean/list）？
2. 参数名是否符合 snake_case 规范？
3. 布尔参数是否使用 enable/has/is 前缀？
4. 数字参数是否包含单位后缀（如 _seconds、_bytes）？
5. 列表参数默认值是否为空列表 [] 而非 null？
6. 默认值是否选择了最安全的选项？
7. 每个参数是否有清晰的 description 字段？