3. 模板化设计原则：DRY原则、单一职责原则、可复用性、可扩展性、版本控制

模板化设计是Runbook从“一次性脚本”进化为“可治理资产”的核心转折点。本节围绕五项工程原则展开，确保模板在跨环境、跨服务的复杂场景下保持低冗余、高内聚、易维护。

3.1 五项原则概览

3.2 DRY原则：消除重复，统一变更点

在未模板化前，运维团队常为每个服务单独编写自愈脚本，导致“检测磁盘”逻辑在20个脚本中重复出现。DRY原则要求将公共能力抽取为原子步骤，模板通过声明式引用来组装。

# 反例：每个服务脚本都重复写一遍检测逻辑
if [ $(df /data | awk 'NR==2 {print $5}' | sed 's/%//') -gt 85 ]; then
    echo "磁盘告警"
fi

# 正例：公共检测步骤定义为模板片段
# shared/check_disk_usage.yaml
steps:
  - name: check_disk
    command: "df {{ .MountPoint }} | awk 'NR==2 {print $5}' | sed 's/%//'"
    threshold: "{{ .Threshold }}"

# 服务模板中引用
# templates/disk_auto_recovery.yaml
import:
  - shared/check_disk_usage.yaml
steps:
  - ref: check_disk
  - name: cleanup_logs
    command: "find {{ .LogDir }} -mtime +{{ .RetentionDays }} -delete"

3.3 单一职责原则：一个模板只做一件事

单一职责原则要求每个Runbook模板只应对一种告警类型。例如“磁盘使用率超过85%”与“磁盘I/O等待时间超过500ms”应分属两个模板，即使它们都涉及磁盘子系统。

3.4 可复用性：通过变量与上下文实现一次编写多处运行

可复用性的核心是将环境差异、服务差异参数化。模板本身不包含任何硬编码值，所有可变信息通过上下文对象注入。

# 模板定义：service_restart.yaml
# 变量占位符使用 {{ .VariableName }}
steps:
  - name: health_check
    command: "curl -f http://{{ .ServiceHost }}:{{ .ServicePort }}/health"
    retry: 3
    interval: 5s
  - name: restart_service
    command: "systemctl restart {{ .ServiceName }}"
    timeout: 30s
  - name: verify_recovery
    command: "curl -f http://{{ .ServiceHost }}:{{ .ServicePort }}/health"
    retry: 5
    interval: 10s

# 不同环境的上下文实例
# context_prod.yaml
ServiceHost: "prod-app-01.internal"
ServicePort: 8080
ServiceName: "app-server"

# context_staging.yaml
ServiceHost: "stg-app-01.internal"
ServicePort: 8081
ServiceName: "app-server-staging"

3.5 可扩展性：插件式步骤与钩子机制

可扩展性确保当出现新的故障模式或新的恢复工具时，无需修改现有模板的核心流程。推荐采用步骤注册表和生命周期钩子两种模式。

# 步骤注册表示例（伪代码）
steps_registry:
  disk_cleanup:
    type: plugin
    path: /plugins/disk_cleanup.py
    version: "1.2.0"
  process_killer:
    type: plugin
    path: /plugins/process_killer.py
    version: "2.0.1"

# 模板中通过名称引用插件，而非内联命令
steps:
  - plugin: disk_cleanup
    params:
      mount_point: "/data"
      min_free_gb: 10
  - plugin: process_killer
    params:
      process_name: "java"
      signal: "SIGTERM"

3.6 版本控制：模板即代码

将Runbook模板视为代码资产，纳入Git版本管理。每次变更必须关联工单号，通过Code Review后合并，并自动同步到执行引擎。

# 模板文件头部元信息示例
# runbook-templates/prod/disk/disk_usage_auto_recovery.yaml
---
apiVersion: runbook/v2
kind: AutoRecoveryTemplate
metadata:
  name: disk-usage-recovery
  version: "2.1.0"
  changelog: "增加日志清理步骤，修复磁盘检测命令兼容性问题"
  related_issue: "INC-20250315-0042"
  author: "sre-team"
  approved_by: "arch-review"

3.7 模板化设计原则关系图

下图展示了五项原则之间的依赖与协作关系，以及它们如何共同支撑Runbook模板的健壮性。

3.8 原则落地检查清单

在编写或评审Runbook模板时，可使用以下清单快速评估模板质量：

• DRY检查： 模板中是否存在与其它模板重复的步骤？能否抽取为共享片段？
• 单一职责检查： 该模板是否只处理一种告警类型？是否包含与当前告警无关的条件分支？
• 可复用性检查： 模板中是否有硬编码的环境名、IP地址、端口号？是否全部通过变量注入？
• 可扩展性检查： 新增一种恢复动作是否需要修改模板核心流程？是否预留了钩子或插件接口？
• 版本控制检查： 模板是否包含版本号、变更日志、关联工单号？是否通过CI/CD流水线部署？