3. API 基础概念回顾：RESTful API 设计原则、HTTP 方法、状态码与请求响应结构

在构建反洗钱（AML）推理服务时，API 是模型与业务系统之间的桥梁。RESTful 风格因其无状态、可缓存、统一接口等特性，成为 AML 在线推理服务的主流架构选择。本节将系统回顾 RESTful API 的核心设计原则、HTTP 方法语义、状态码含义以及请求/响应结构，为后续的 API 发布与推理实践奠定基础。

3.1 RESTful API 六大设计原则

REST（Representational State Transfer）由 Roy Fielding 于 2000 年提出，其核心是围绕资源进行表述状态转移。以下六项原则是判断 API 是否“RESTful”的关键标准：

3.2 HTTP 方法语义与 AML 场景映射

RESTful API 通过 HTTP 方法表达对资源的操作意图。在 AML 推理服务中，最常用的方法是 POST（创建推理任务）和 GET（查询结果或状态）。以下是标准 HTTP 方法及其在 AML 场景中的典型用法：

3.3 HTTP 状态码：AML 推理 API 的语义信号

状态码是服务器对请求处理结果的标准化反馈。在 AML 推理场景中，合理使用状态码可以帮助客户端快速判断请求状态并采取相应措施。以下是 AML API 最常用的状态码分类：

3.4 请求与响应结构设计

统一的请求/响应结构是 API 可维护性的基石。AML 推理 API 通常采用 JSON 格式，并遵循以下设计规范：

3.4.1 请求结构

一个标准的 AML 推理请求应包含以下层级：

• 请求头（Headers）：认证信息（Authorization: Bearer <token>）、内容类型（Content-Type: application/json）、幂等键（可选）
• 请求体（Body）：包含交易特征、客户信息、上下文元数据

POST /api/v1/aml/predict HTTP/1.1
Host: aml-api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type: application/json
Idempotency-Key: 7a3b8c9d-1e2f-4a5b-8c7d-9e0f1a2b3c4d

{
  "request_id": "req-20250321-001",
  "timestamp": "2025-03-21T10:30:00Z",
  "transaction": {
    "tx_id": "TX20250321001",
    "amount": 150000.00,
    "currency": "CNY",
    "sender_account": "622202****1234",
    "receiver_account": "621700****5678",
    "channel": "online_banking"
  },
  "customer": {
    "customer_id": "CUST2023001",
    "risk_level": "medium",
    "kyc_status": "verified"
  },
  "features": {
    "amount_zscore": 3.45,
    "tx_frequency_24h": 12,
    "avg_amount_30d": 8500.00,
    "is_high_risk_country": false
  }
}

3.4.2 响应结构

响应应包含状态、数据、元数据三个部分，便于客户端统一解析：

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req-20250321-001
X-Model-Version: 2.1.0

{
  "status": "success",
  "data": {
    "risk_score": 0.87,
    "risk_level": "high",
    "decision": "block",
    "confidence": 0.94,
    "rule_hits": [
      {"rule_id": "R001", "rule_name": "大额交易", "weight": 0.4},
      {"rule_id": "R007", "rule_name": "高频交易", "weight": 0.3}
    ]
  },
  "meta": {
    "request_id": "req-20250321-001",
    "processing_time_ms": 45,
    "model_version": "2.1.0",
    "timestamp": "2025-03-21T10:30:00.123Z"
  }
}

3.5 最佳实践与常见反模式