3. API 设计原则：RESTful 设计规范、资源命名、HTTP 方法选择、状态码定义

在支付风控评分通道的 API 设计中，遵循统一的 RESTful 设计规范是保障接口可维护性、可扩展性与团队协作效率的基石。本节将围绕资源命名、HTTP 方法选择与状态码定义三个核心维度展开，确保 API 设计既符合行业标准，又能精准表达风控业务语义。

3.1 RESTful 设计核心规范

REST（Representational State Transfer）是一种基于资源的架构风格。在风控评分通道中，我们将每一次评分请求、规则配置、模型版本、策略集均视为“资源”，通过统一的接口对资源进行增删改查操作。核心规范包括：

• 无状态性：每次请求包含所有必要信息（如商户 ID、签名、时间戳），服务端不保存客户端会话状态。
• 统一接口：使用标准 HTTP 方法操作资源，通过 URI 定位资源，通过请求体/查询参数传递业务数据。
• 资源导向：URI 只表示资源，不表示动作。例如 /v1/score/orders 表示订单评分资源，而非 /v1/score/doScoring。
• 版本管理：在 URI 中显式携带版本号（如 /v1/、/v2/），避免向后兼容问题。

3.2 资源命名规范

资源命名直接影响 API 的可读性与一致性。支付风控评分通道的资源命名遵循以下规则：

3.3 HTTP 方法选择

每个 HTTP 方法对应一种标准操作。在风控评分通道中，方法选择必须严格遵循语义，避免滥用 POST 或 GET 执行非预期操作。

3.4 状态码定义

状态码是 API 响应语义的第一道关口。风控评分通道必须覆盖成功、客户端错误、服务端错误三大类，并针对风控业务扩展特定状态码。

3.4.1 成功状态码

3.4.2 客户端错误状态码

3.4.3 服务端错误状态码

3.5 API 设计流程总览

下图展示了从资源识别到状态码定义的完整设计流程，帮助团队在 API 设计阶段建立统一规范。

3.6 错误响应体规范

统一的错误响应结构有助于客户端实现通用错误处理逻辑。推荐使用以下 JSON 格式：

{
  "error_code": "INVALID_PARAMETER",
  "error_message": "字段 'amount' 必须为正整数",
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "timestamp": "2025-03-21T10:30:00Z",
  "details": [
    {
      "field": "amount",
      "reason": "金额不能为负数",
      "value": -100
    }
  ]
}

3.7 幂等性设计

支付风控场景对幂等性要求极高，避免因网络重试导致重复评分或重复扣减。设计要点如下：

• 幂等键机制：客户端在 POST 请求头中携带 Idempotency-Key，服务端缓存该键与响应结果，相同键的重复请求直接返回缓存结果。
• 键有效期：建议幂等键有效期为 24 小时，过期后允许重新提交。
• 键生成规则：推荐使用 UUID v4，确保全局唯一。
• 冲突处理：若幂等键已存在但请求体不一致，返回 409 Conflict。

// 幂等评分请求示例
POST /v1/score/orders
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json

{
  "merchant_id": "M10086",
  "order_id": "ORD20250321001",
  "amount": 29900,
  "currency": "CNY",
  "payee_account": "2088****1234"
}

3.8 分页与过滤设计

对于列表查询接口（如查询评分订单列表），必须支持分页与过滤，避免一次性返回大量数据导致性能问题。

// 分页响应示例
{
  "data": [
    {
      "order_id": "ORD20250321001",
      "status": "approved",
      "score": 85,
      "created_at": "2025-03-21T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total_count": 156,
    "total_pages": 8
  }
}

3.9 版本管理策略

API 版本管理是长期维护的必备手段。推荐在 URI 中嵌入版本号，并遵循以下策略：

• 主版本号：不兼容变更时递增（如 /v1/ → /v2/）。
• 向后兼容：新增字段、新增可选参数、扩展枚举值均属于兼容变更，无需升级版本。
• 废弃周期：旧版本至少维护 6 个月，废弃前通过响应头 Deprecation: true 和 Sunset: Sat, 20 Sep 2025 23:59:59 GMT 通知客户端。
• 版本映射：服务端内部可维护版本路由表，将不同版本的请求映射到对应的处理逻辑。

// 废弃版本响应头示例
HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 20 Sep 2025 23:59:59 GMT
Content-Type: application/json

{
  "message": "此 API 版本将于 2025 年 9 月 20 日废弃，请迁移至 /v2/score/orders"
}