📚 课程目录第4章接口调用基础

4. 接口调用基础：HTTP请求方法（GET/POST/PUT/DELETE）、请求头与请求体、响应状态码、错误处理机制

在 Service Catalog 平台门户的基线校验中，所有功能最终都通过 HTTP 接口暴露。理解 HTTP 请求方法、请求结构、响应状态码以及错误处理机制，是进行接口调用与自动化测试的基石。本章将系统梳理这些核心概念，并结合 Service Catalog 场景给出最佳实践。

4.1 HTTP 请求方法：CRUD 操作的语义映射

HTTP 协议定义了多种请求方法，在 RESTful API 设计中，最常用的四种方法分别对应资源的增、删、改、查操作。Service Catalog 的接口设计严格遵循这一语义。

HTTP 方法	CRUD 操作	Service Catalog 典型场景	请求体（Body）	幂等性
GET	查询（Read）	获取服务列表、查询服务详情、获取基线校验结果	无	是
POST	创建（Create）	创建新服务、提交基线校验任务、注册新平台门户	有（JSON）	否
PUT	全量更新（Update）	更新服务配置、替换基线规则集	有（JSON）	是
DELETE	删除（Delete）	删除已废弃的服务、移除基线校验规则	通常无	是

最佳实践：在 Service Catalog 接口调用中，GET 请求不应携带请求体，即使部分框架允许，也应避免。对于 POST 创建资源，注意其非幂等性——重复提交可能导致重复创建，建议在客户端实现去重逻辑或利用服务端的唯一键约束。

4.2 请求头与请求体：接口调用的完整结构

一个完整的 HTTP 请求由请求行、请求头（Headers）和请求体（Body）三部分组成。在 Service Catalog 的基线校验场景中，请求头和请求体的正确设置直接决定了接口调用的成败。

4.2.1 核心请求头

Content-Type：标识请求体的媒体类型。对于 RESTful API，通常设置为 application/json。若涉及文件上传（如导入基线规则模板），则使用 multipart/form-data。
Authorization：携带认证凭证。Service Catalog 平台通常使用 Bearer 或，格式为 Bearer <>。
Accept：告知服务器客户端期望接收的响应格式，通常为 application/json。
X-Request-ID：自定义请求追踪 ID，用于在分布式链路中定位问题，尤其在基线校验失败时便于日志关联。

4.2.2 请求体结构（JSON 示例）

以“提交基线校验任务”的 POST 请求为例，请求体通常包含校验目标、规则版本和回调地址：

{
  "serviceId": "svc-20250301-001",
  "baselineVersion": "v2.1.0",
  "checkItems": [
    {
      "ruleId": "rule-portal-auth-001",
      "expectedValue": "OAuth2.0"
    },
    {
      "ruleId": "rule-portal-https-002",
      "expectedValue": "enabled"
    }
  ],
  "callbackUrl": "https://portal.example.com/callback/baseline"
}

常见错误：请求体 JSON 格式错误（如多余的逗号、键未使用双引号）会导致服务器返回 400 Bad Request。建议在发送前使用 JSON 校验工具验证。另外，PUT 请求要求传递完整的资源表示，缺失字段可能被重置为默认值。

4.3 响应状态码：接口调用的“交通信号灯”

HTTP 响应状态码由三位数字组成，用于指示请求的处理结果。在 Service Catalog 接口调用与基线校验中，需要重点关注以下几类状态码：

4.4 错误处理机制：从异常到可恢复的流程

在 Service Catalog 平台门户基线校验的自动化调用中，错误处理不是简单的“捕获异常”，而是一套完整的策略，包括错误识别、重试、降级和告警。

4.4.1 错误响应体结构

一个设计良好的 API 在返回 4xx/5xx 状态码时，会在响应体中提供详细的错误信息，便于调用方定位问题。Service Catalog 的标准错误响应格式如下：

{
  "error": {
    "code": "BASELINE_RULE_NOT_FOUND",
    "message": "指定的基线规则 ID 'rule-xxx' 不存在",
    "details": {
      "ruleId": "rule-xxx",
      "serviceId": "svc-20250301-001",
      "suggestion": "请检查规则 ID 是否正确，或通过 GET /api/v1/rules 获取可用规则列表"
    },
    "traceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

4.4.2 错误处理策略矩阵

状态码	错误类型	处理策略	重试机制	告警级别
400	请求参数错误	修正请求体后重新发送	不重试，需人工介入	警告
401 / 403	认证/授权失败	刷新或检查权限	最多重试 1 次（刷新后）	严重
404	资源不存在	检查资源 ID 或路径	不重试	警告
429	请求频率过高	等待 Retry-After 头指定的时间	指数退避重试（最多 3 次）	信息
500	服务端内部错误	记录 traceId 并上报运维	固定间隔重试 2 次	严重
503	服务暂时不可用	等待后重试	指数退避重试（最多 5 次）	严重

4.4.3 重试与退避算法（伪代码）

function callWithRetry(requestFn, maxRetries = 3) {
  let attempt = 0;
  while (attempt <= maxRetries) {
    try {
      const response = requestFn();
      if (response.status >= 200 && response.status < 300) {
        return response.data;
      }
      // 对可重试的状态码进行处理
      if ([429, 500, 503].includes(response.status) && attempt < maxRetries) {
        const delay = Math.pow(2, attempt) * 1000; // 指数退避: 1s, 2s, 4s
        console.warn(`请求失败，状态码 ${response.status}，第 ${attempt + 1} 次重试，等待 ${delay}ms`);
        sleep(delay);
        attempt++;
        continue;
      }
      // 不可重试的错误，直接抛出
      throw new Error(`请求失败: ${response.status} ${response.data.error.message}`);
    } catch (error) {
      if (attempt >= maxRetries) throw error;
      const delay = Math.pow(2, attempt) * 1000;
      sleep(delay);
      attempt++;
    }
  }
}

基线校验场景提示：在调用 Service Catalog 的“批量基线校验”接口时，如果返回 202 Accepted（异步任务已接受），则不应使用上述重试逻辑，而应通过轮询 GET /api/v1/tasks/{taskId} 获取最终结果。轮询间隔建议为 5 秒，最大超时时间根据校验规则数量设定（通常为 5 分钟）。

4.5 接口调用完整流程（SVG 时序图）

以下 SVG 图展示了 Service Catalog 客户端调用基线校验接口的完整生命周期，涵盖请求构造、错误重试与结果获取：

4.6 本章小结

请求方法：GET 用于查询，POST 用于创建，PUT 用于全量更新，DELETE 用于删除。Service Catalog 接口严格遵循 RESTful 语义。
请求结构：正确设置 Content-Type、Authorization 等请求头，确保请求体 JSON 格式合法。
响应状态码：2xx 表示成功，4xx 表示客户端错误，5xx 表示服务端错误。基线校验场景中 202 表示异步任务已接受。
错误处理：根据状态码和错误码采取不同策略，对可重试错误使用指数退避算法，对不可重试错误及时告警并记录 traceId。