4. 请求与响应规范：HTTP方法选择、状态码语义与统一响应体结构

在评分通道API的设计中，请求与响应规范是保障前后端协作效率、降低集成故障率的基石。本章围绕三个核心维度展开：HTTP方法选择（POST/GET/PUT/DELETE）、状态码语义（200/201/400/401/403/404/500）以及统一响应体结构。遵循这些规范，可使API具备自描述性、可预测性和可监控性。

4.1 HTTP方法选择：语义化操作映射

每个HTTP方法对应一种资源操作语义。评分通道API应严格遵循RESTful原则，避免方法滥用（如用GET执行写操作、用POST执行查询）。

4.2 状态码语义：精准表达处理结果

状态码是API与调用方之间的“信号灯”。评分通道API应覆盖以下关键状态码，避免统一返回200然后在业务体内包装错误。

• 200 OK：GET、PUT请求成功，响应体包含完整资源数据。
• 201 Created：POST创建成功，响应体包含新资源ID及访问路径。
• 400 Bad Request：请求参数校验失败（如评分分数超出范围、缺少必填字段）。
• 401 Unauthorized：缺少认证凭证或凭证已过期。
• 403 Forbidden：认证通过但无权限操作该资源（如非管理员删除通道）。
• 404 Not Found：请求的资源不存在（如查询不存在的评分任务ID）。
• 500 Internal Server Error：服务端未捕获的异常，需结合监控告警处理。

4.3 统一响应体结构：可预测的数据契约

所有响应体（无论成功或失败）应遵循统一JSON结构，便于客户端做通用解析和错误处理。

{
  "code": 0,                // 业务状态码：0=成功，非0=具体错误码
  "message": "success",     // 人类可读的描述信息
  "data": {                 // 实际业务数据，可为null
    "taskId": "task_20240501_001",
    "score": 95,
    "status": "completed"
  },
  "requestId": "req_abc123" // 全链路追踪ID，用于日志关联
}

4.4 请求与响应流程总览

下图展示了评分通道API从请求到达、方法路由、状态码决策到统一响应体返回的完整链路。

4.5 错误响应示例与监控要点

以下展示两种典型错误场景下的统一响应体，帮助开发者和监控系统快速定位问题。

{
  "code": 1001,
  "message": "评分分数超出允许范围（0-100）",
  "data": null,
  "requestId": "req_20240501_002"
}

{
  "code": 2001,
  "message": "AccessToken已过期，请重新获取",
  "data": null,
  "requestId": "req_20240501_003"
}