3、自愈API设计原则：RESTful设计、幂等性、安全认证、超时与重试策略

自愈API是Prometheus告警触发自动化修复动作的执行端点。一个设计不良的API可能导致修复失败、重复执行、安全漏洞甚至系统雪崩。本章从RESTful设计、幂等性、安全认证、超时与重试四个维度，定义自愈API的核心设计原则。

3.1 RESTful设计原则

自愈API应遵循RESTful风格，使用标准HTTP方法和资源路径表达修复意图。资源路径应反映被修复的对象和操作类型，而非动词式RPC。

HTTP方法	资源路径	语义	示例场景
POST	/api/v1/heal/{resource_type}/{resource_id}	触发一次自愈操作	重启nginx服务、扩容Pod
GET	/api/v1/heal/{resource_type}/{resource_id}/status	查询自愈任务状态	获取上次修复结果
DELETE	/api/v1/heal/{resource_type}/{resource_id}/cancel	取消正在执行的自愈任务	终止误触发的修复

3.2 幂等性设计

自愈API必须保证幂等性：同一告警多次触发同一修复操作，结果与执行一次相同。幂等性防止网络重试、告警重复、Prometheus多次推送导致资源被反复操作。

场景	非幂等行为	幂等行为
重启服务	每次调用都执行systemctl restart	检查服务状态，仅当服务异常时重启
扩容Pod	每次调用都增加1个副本	设置目标副本数为期望值（如3），而非增量+1
清理磁盘	每次调用都删除日志文件	确保磁盘使用率低于阈值，而非无条件删除

3.3 安全认证

自愈API直接操作生产环境资源，必须实施严格的安全认证。Prometheus告警webhook调用自愈API时，应使用预共享密钥或OAuth2客户端凭证模式。

认证方式	适用场景	安全等级	实现复杂度
Bearer	Prometheus → 自愈API	中	低
mTLS	跨集群、跨网络调用	高	中
HMAC签名	无状态、轻量级认证	高	中
OAuth2 Client Credentials	企业级、多服务集成	高	高

3.4 超时与重试策略

自愈操作可能耗时较长（如重启容器等待就绪、扩容等待调度），API必须设计合理的超时和重试机制，避免调用方长时间阻塞或重复提交。

3.4.1 超时设计

超时层级	推荐值	说明
连接超时	5秒	建立TCP连接的最大等待时间
读取超时	30秒	等待服务端返回响应的最大时间
写入超时	10秒	发送请求体的最大时间
业务超时	120秒	自愈操作整体执行的最大时间

3.4.2 重试策略

自愈API应区分“可重试”和“不可重试”的错误类型，避免对非幂等操作进行盲目重试。

3.5 综合设计示例

以下是一个符合上述原则的自愈API请求/响应示例：

// 请求示例：Prometheus告警触发自愈
POST /api/v1/heal/services/nginx-prod HTTP/1.1
Host: selfheal.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
X-Request-ID: alert-abc123-20250321-001
Content-Type: application/json

{
  "alert_id": "alert-abc123",
  "alert_name": "HighCPUUsage",
  "resource_type": "service",
  "resource_id": "nginx-prod",
  "severity": "critical",
  "triggered_at": "2025-03-21T14:30:00Z",
  "heal_action": "restart",
  "parameters": {
    "graceful_shutdown": true,
    "timeout_seconds": 120
  }
}

// 响应示例
HTTP/1.1 202 Accepted
Content-Type: application/json
X-Request-ID: alert-abc123-20250321-001

{
  "task_id": "task-xyz789",
  "status": "accepted",
  "message": "自愈任务已接受，正在执行",
  "estimated_completion_seconds": 30,
  "status_url": "/api/v1/heal/services/nginx-prod/status/task-xyz789"
}