4. RESTful API 设计原则：评分接口规范、请求/响应数据结构设计、错误码与异常处理

在风控评分通道的 Model Serving 实践中，API 是上游业务系统与模型推理引擎之间的唯一契约。一个设计良好的 RESTful 评分接口，不仅要保证数据交换的准确性与实时性，还必须具备清晰的语义、健壮的异常处理机制以及可扩展的数据结构。本章围绕评分接口的规范、请求/响应结构设计以及错误码体系展开，确保接口在生产环境中具备高可用性与可维护性。

4.1 评分接口规范

评分接口遵循标准的 RESTful 风格，使用 HTTP POST 方法提交特征数据并获取评分结果。接口路径设计应体现资源语义，避免动词化。

4.2 请求数据结构设计

评分请求体采用扁平化 JSON 对象，包含三个核心字段：request_id、features、context。其中 features 为必填字段，承载模型推理所需的全部特征变量。

{
  "request_id": "202503211234567890001",
  "features": {
    "age": 35,
    "income": 250000,
    "credit_limit": 50000,
    "loan_amount": 120000,
    "loan_term": 36,
    "overdue_days_30": 0,
    "overdue_days_90": 1,
    "query_count_3m": 5,
    "existing_loans": 2
  },
  "context": {
    "channel": "APP",
    "product_code": "P001",
    "timestamp": "2025-03-21T14:30:00+08:00"
  }
}

4.3 响应数据结构设计

评分响应体同样采用 JSON 格式，包含 code、message、data 三个顶层字段。其中 data 字段封装评分结果与辅助信息，便于上游系统直接消费。

{
  "code": 0,
  "message": "success",
  "data": {
    "score": 725,
    "decision": "approve",
    "reason_code": "R001",
    "model_version": "v2.3.1",
    "score_timestamp": "2025-03-21T14:30:01.123+08:00",
    "extra": {
      "probability": 0.87,
      "bucket": "A"
    }
  }
}

4.4 错误码与异常处理

错误码体系采用分层设计，分为 HTTP 状态码与业务状态码两层。HTTP 状态码用于表示通信层面的成功或失败，业务状态码用于表示评分业务层面的具体异常类型。

4.4.1 HTTP 状态码定义

4.4.2 业务状态码定义

4.4.3 异常处理策略

• 重试机制：对于 504 网关超时与 2001 模型推理超时，采用指数退避重试策略，初始间隔 200ms，最大重试次数 3 次。
• 降级策略：当模型服务不可用时，根据 context.product_code 返回预设的默认评分或缓存评分，确保业务连续性。
• 熔断保护：基于滑动窗口统计错误率，当 30 秒内错误率超过 50% 时触发熔断，熔断时长 60 秒，熔断期间直接返回降级结果。
• 告警通知：业务码 3001 及以上异常自动触发告警，通过钉钉/企业微信机器人通知值班人员，并记录完整请求日志用于事后分析。

4.5 接口安全与版本管理

评分接口涉及用户敏感特征数据，必须实施传输层安全与访问控制。同时，接口版本管理应支持平滑升级与灰度切换。

• 传输安全：强制使用 HTTPS，TLS 版本不低于 1.2，证书由内部 CA 签发或使用云厂商托管证书。
• 访问控制：请求头携带 X-API-Key 字段，网关层校验有效性，支持按渠道、产品码进行细粒度权限控制。
• 版本管理：路径版本号（v1, v2）与模型版本解耦，接口版本升级时保留旧版本至少 3 个月，通过网关权重配置实现灰度切换。
• 审计日志：所有评分请求与响应均记录至审计日志系统，包含 request_id、时间戳、调用方身份、模型版本、评分结果，满足合规要求。