4. 接口调用基础：HTTP方法（GET/POST/PUT/DELETE）、请求头、请求体、响应解析

在变更窗口告警路由的自动化部署中，所有标准模板的交互均通过 RESTful API 完成。理解 HTTP 方法、请求头、请求体及响应解析是调用接口的基石。本章将系统梳理这些核心概念，并结合告警路由场景进行说明。

4.1 HTTP 方法：操作语义与路由场景

RESTful 接口通过不同的 HTTP 方法表达对资源的操作意图。在告警路由模板中，每个方法对应一种标准操作：

4.2 请求头（Headers）：认证与内容协商

请求头携带元数据，用于认证、内容类型声明、缓存控制等。告警路由接口调用中，以下请求头最为关键：

• Authorization：Bearer 或 ，用于接口鉴权。
• Content-Type：声明请求体的媒体类型，通常为 application/json。
• Accept：声明客户端期望的响应格式，通常为 application/json。
• X-Request-Id：自定义请求追踪 ID，便于链路排查。
• X-Change-Window-Id：变更窗口标识，用于路由上下文绑定（自定义头）。

# 示例：告警路由模板查询请求头
GET /api/v1/alert-routes?window_id=win-2025-04-01
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type: application/json
Accept: application/json
X-Request-Id: req-abc-12345
X-Change-Window-Id: win-2025-04-01

4.3 请求体（Body）：结构化数据提交

POST 和 PUT 方法需要携带请求体，通常为 JSON 格式。告警路由模板的请求体遵循标准 schema，包含路由名称、条件、目标动作等字段。

// POST /api/v1/alert-routes  创建告警路由规则
{
  "route_name": "变更窗口-生产环境-高优先级",
  "window_id": "win-2025-04-01",
  "conditions": {
    "severity": ["critical", "major"],
    "environment": "production",
    "alert_source": ["prometheus", "grafana"]
  },
  "actions": {
    "target_channel": "pagerduty",
    "escalation_policy": "sre-oncall",
    "notify_slack": true
  },
  "enabled": true
}

4.4 响应解析：状态码、响应头与响应体

每次接口调用都会返回一个 HTTP 响应，包含状态码、响应头和响应体。正确解析这三部分是自动化部署稳定性的保障。

4.4.1 状态码语义

4.4.2 响应头关键字段

• Content-Type：确认响应体格式，通常为 application/json。
• X-Request-Id：回显请求 ID，用于日志关联。
• Retry-After：429 状态码时返回，指示重试等待秒数。
• X-RateLimit-Remaining：剩余调用配额。

4.4.3 响应体结构解析

标准响应体通常包含 code、message、data 三层结构，便于客户端统一解析。

// 200 OK 响应示例
{
  "code": 0,
  "message": "success",
  "data": {
    "route_id": "route-67890",
    "route_name": "变更窗口-生产环境-高优先级",
    "window_id": "win-2025-04-01",
    "conditions": { ... },
    "actions": { ... },
    "enabled": true,
    "created_at": "2025-04-01T10:00:00Z",
    "updated_at": "2025-04-01T10:00:00Z"
  }
}

// 400 错误响应示例
{
  "code": 40001,
  "message": "参数校验失败",
  "data": {
    "field": "conditions.severity",
    "reason": "枚举值不支持 'info'，可选值: [critical, major, warning]"
  }
}

4.5 接口调用流程总览

下图展示了从构造请求到解析响应的完整链路，涵盖方法选择、头设置、体构造、发送及响应处理：

4.6 常见调用错误与排查