3、接口调用机制总览：RESTful API设计原则、核验接口的请求-响应模型、同步与异步调用模式

环境一致性基线核验的核心价值在于通过标准化的接口调用，将分散的配置校验行为收敛为可编程、可观测、可复现的自动化流程。本章从接口设计原则、请求-响应模型、调用模式三个维度，构建核验接口的调用机制总览。

3.1 RESTful API 设计原则

核验接口严格遵循 RESTful 架构风格，确保资源定义清晰、操作语义统一、无状态交互可扩展。以下原则贯穿所有核验端点设计：

3.2 核验接口的请求-响应模型

所有核验接口遵循统一的请求-响应契约，包含标准化的请求头、请求体结构、响应状态码与响应体格式。该模型确保客户端与服务端之间的数据交换可预测、可解析。

3.2.1 请求结构

POST /api/v1/environments/{envId}/checks HTTP/1.1
Host: verify.example.com
Authorization: Bearer <>
Content-Type: application/json
Accept: application/json
X-Correlation-ID: 7a3b8c9d-1e2f-4a5b-8c7d-9e0f1a2b3c4d

{
  "baselineId": "bl-2025-03-001",
  "scope": {
    "nodes": ["node-01", "node-02", "node-05"],
    "categories": ["kernel", "network", "security"]
  },
  "mode": "async",
  "callbackUrl": "https://callback.example.com/checks/result"
}

3.2.2 响应结构

HTTP/1.1 202 Accepted
Content-Type: application/json
X-Correlation-ID: 7a3b8c9d-1e2f-4a5b-8c7d-9e0f1a2b3c4d
Location: /api/v1/checks/ck-20250315-001

{
  "checkId": "ck-20250315-001",
  "status": "accepted",
  "createdAt": "2025-03-15T10:30:00Z",
  "estimatedDuration": 45,
  "links": {
    "self": "/api/v1/checks/ck-20250315-001",
    "result": "/api/v1/checks/ck-20250315-001/result",
    "cancel": "/api/v1/checks/ck-20250315-001/cancel"
  }
}

3.3 同步与异步调用模式

核验接口根据业务场景提供两种调用模式：同步模式适用于轻量级、低延迟的核验场景；异步模式适用于大规模、跨节点、耗时较长的核验任务。两种模式在请求语义、响应行为、错误处理上存在显著差异。

3.3.1 同步模式最佳实践

• 超时控制：客户端设置 connectTimeout 为 5s，readTimeout 为 60s，避免长时间挂起。
• 重试策略：对 5xx 状态码采用指数退避重试（初始 1s，最大 30s，最多 3 次）。
• 限流保护：服务端对同步接口实施并发限制（默认 10 并发），超出返回 429 Too Many Requests。

3.3.2 异步模式最佳实践

• 轮询间隔：客户端以 estimatedDuration / 4 为初始轮询间隔，最小 5s，最大 60s。
• 幂等去重：客户端在请求头携带 X-Idempotency-Key，服务端在 24 小时内对相同 key 返回同一任务。
• 回调保障：服务端在任务完成后向 callbackUrl 发送 POST 请求，重试 3 次，间隔 10s。