3. API设计原则：RESTful风格、无状态、幂等性、版本控制

商户风险评分API作为金融级接口，其设计必须遵循一套严格的原则，以确保系统的可维护性、可靠性与可扩展性。本章将深入剖析四项核心设计原则：RESTful风格、无状态、幂等性与版本控制。这些原则共同构成了API架构的基石，直接影响着商户接入的体验与风控系统的稳定性。

3.1 RESTful风格：资源导向的架构

RESTful风格将API视为对“资源”的操作，而非对“动作”的调用。在商户风险评分场景中，资源包括“商户”、“评分记录”、“风险事件”等。通过标准的HTTP方法（GET、POST、PUT、PATCH、DELETE）对资源进行增删改查，使接口语义清晰、易于理解。

3.2 无状态：水平扩展的基石

无状态原则要求每个API请求都包含服务端处理所需的所有信息，服务端不存储任何客户端会话状态。在风控场景中，这意味着每次评分请求都必须携带完整的商户标识、认证令牌和上下文参数，服务端不依赖之前的请求记录。

3.3 幂等性：防止重复处理的保障

幂等性是指无论请求执行一次还是多次，对资源产生的最终影响相同。在商户风险评分中，幂等性至关重要——网络重试、超时重发等场景下，必须防止重复评分导致的风控结果错误或商户数据污染。

幂等性实现策略

• 幂等键（Idempotency-Key）：客户端为每个请求生成唯一键（如UUID），服务端记录已处理的键，重复请求直接返回首次结果。
• 自然幂等操作：
  • GET、PUT、DELETE 方法天然幂等。
  • POST 方法需额外实现幂等机制。
• 业务去重：利用业务唯一标识（如 transaction_id）进行去重，确保同一笔交易只被评分一次。

// 幂等键使用示例（HTTP 请求头）
POST /api/v3/merchants/123/risk-scores
Content-Type: application/json
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

{
  "transaction_id": "TXN20250321001",
  "amount": 1500.00,
  "currency": "CNY"
}

// 服务端响应（首次）
HTTP/1.1 201 Created
{
  "score_id": "SCR-20250321-001",
  "risk_level": "medium",
  "score": 65
}

// 重复请求（相同幂等键）
HTTP/1.1 200 OK  // 返回已存在的记录，而非新建
{
  "score_id": "SCR-20250321-001",
  "risk_level": "medium",
  "score": 65
}

3.4 版本控制：平滑演进的保障

API版本控制允许在引入新功能或修改现有行为时，不影响已接入的商户。版本控制策略直接决定了风控系统的迭代效率与商户的迁移成本。

版本控制策略对比

版本生命周期管理

• 主版本（Major）：不兼容的API变更，如删除字段、修改请求结构。至少提前 6 个月通知商户。
• 次版本（Minor）：向后兼容的新增功能，如增加可选字段。无需通知商户。
• 补丁（Patch）：内部修复，不影响接口行为。无需版本变更。
• 废弃策略：旧版本标记为“废弃（Deprecated）”，保留至少 12 个月后下线。

// 版本控制示例
// v2 接口（旧版本，已废弃）
GET /api/v2/merchants/123/risk-score
Response: { "score": 65, "level": "medium" }

// v3 接口（新版本，推荐使用）
GET /api/v3/merchants/123/risk-scores
Response: {
  "score_id": "SCR-20250321-001",
  "score": 65,
  "risk_level": "medium",
  "factors": [
    { "name": "transaction_velocity", "weight": 0.3, "score": 70 },
    { "name": "amount_anomaly", "weight": 0.4, "score": 60 }
  ]
}

// 响应头中声明版本
HTTP/1.1 200 OK
Content-Type: application/json
API-Version: v3
Deprecated: true  // 仅 v2 响应包含此头
Sunset: Sat, 31 Mar 2026 23:59:59 GMT  // 下线时间