2. API 基础概念：RESTful API、HTTP 方法与状态码

在信用评分系统的在线推理链路中，API（应用程序编程接口）是服务端与客户端之间的通信契约。现代微服务架构普遍采用 RESTful API 风格来设计评分接口，其核心要素包括资源标识、HTTP 方法、请求/响应格式以及状态码。

2.1 什么是 RESTful API

REST（Representational State Transfer，表述性状态转移）是一种基于 HTTP 协议的架构风格，强调将业务实体抽象为“资源”，并通过统一的接口对资源进行操作。信用评分 API 中的典型资源包括：

• 评分请求（ScoreRequest）：包含客户特征数据的输入对象。
• 评分结果（ScoreResult）：包含信用分数、决策建议的输出对象。
• 模型版本（ModelVersion）：当前生效的评分模型元数据。

2.2 HTTP 方法（GET / POST / PUT / DELETE）

RESTful API 通过 HTTP 方法（也称为“动词”）来定义对资源的操作类型。信用评分 API 中最常用的方法是 POST，因为评分请求通常包含敏感特征数据，且需要保证请求体的完整性。

2.3 HTTP 状态码含义

状态码是服务端对请求处理结果的标准化反馈。信用评分 API 中，状态码直接反映评分链路是否正常、数据是否有效、服务是否可用。状态码按类别分为 5 类：

• 1xx（信息性）：协议升级或临时响应，评分 API 中极少使用。
• 2xx（成功）：请求已成功处理。
• 3xx（重定向）：资源位置变更，评分 API 中通常不涉及。
• 4xx（客户端错误）：请求格式错误、参数缺失、认证失败等。
• 5xx（服务端错误）：评分引擎内部异常、模型加载失败、数据库超时等。

2.4 信用评分 API 的典型请求与响应

以下是一个使用 POST 方法提交信用评分请求的完整示例，包含请求头和请求体（JSON 格式）：

POST /api/v1/score HTTP/1.1
Host: credit-scoring.example.com
Content-Type: application/json
Authorization: Bearer <access_token>
X-Request-ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890

{
  "customer_id": "CUST-2024-001",
  "features": {
    "age": 35,
    "income": 85000,
    "credit_history_length_months": 72,
    "existing_loans": 2,
    "payment_defaults_12m": 0,
    "debt_to_income_ratio": 0.28
  },
  "model_version": "v2.1.0"
}

服务端处理成功后，返回 200 OK 状态码及评分结果：

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890

{
  "score": 725,
  "rating": "A",
  "decision": "APPROVE",
  "probability_default": 0.032,
  "model_version": "v2.1.0",
  "processing_time_ms": 45
}

2.5 状态码在评分链路中的实际应用

在信用评分在线推理链路中，不同阶段可能返回不同的状态码。下表总结了常见场景及对应的处理建议：