📚 课程目录第2章风控API基础概念

2. 风控API基础概念：RESTful API、端点、请求与响应模型及HTTP方法

在构建实时交易风控系统时，API（应用程序编程接口）是风控引擎与业务系统之间的通信桥梁。本章将围绕RESTful API的核心概念展开，帮助您建立统一、标准的风控接口设计认知。

2.1 什么是RESTful API

REST（Representational State Transfer，表述性状态转移）是一种软件架构风格，而非协议。RESTful API遵循以下六大约束，确保接口的简洁性、可扩展性和无状态性：

约束	说明	风控场景示例
客户端-服务器	分离用户界面与数据存储	交易系统（客户端）与风控引擎（服务器）独立部署
无状态	每个请求包含所有必要信息，服务器不保存客户端上下文	每次风控评估请求都需携带完整的交易信息和认证令牌
可缓存	响应可隐式或显式标记为可缓存或不可缓存	风控规则配置查询结果可缓存，交易评估结果不可缓存
统一接口	通过标准HTTP方法和资源URI进行操作	所有风控资源（交易、规则、黑名单）使用一致的接口风格
分层系统	客户端无法直接感知是否与最终服务器或中间层通信	风控API可经过网关、负载均衡、缓存层，对调用方透明
按需代码（可选）	服务器可向客户端传输可执行代码	风控策略热更新时下发规则脚本（较少使用）

设计要点： 在实时交易风控场景中，无状态和统一接口是最关键的约束。无状态保证了风控引擎的水平扩展能力，统一接口降低了业务系统的集成成本。

2.2 API端点（Endpoint）

API端点是RESTful API中可访问的特定URL路径，代表一个资源或资源集合。在风控系统中，端点设计应遵循名词复数形式，清晰表达资源层级。

风控API端点设计示例：

# 基础URL
https://api.riskcontrol.example.com/v1

# 交易评估资源
POST   /v1/transactions/assess          # 提交交易进行风控评估
GET    /v1/transactions/{txn_id}        # 查询单笔交易评估结果
GET    /v1/transactions                 # 查询交易列表（分页）

# 风控规则资源
GET    /v1/rules                        # 获取规则列表
POST   /v1/rules                        # 创建新规则
PUT    /v1/rules/{rule_id}              # 更新指定规则
DELETE /v1/rules/{rule_id}              # 删除指定规则

# 黑名单资源
GET    /v1/blacklist                    # 获取黑名单列表
POST   /v1/blacklist/entries            # 添加黑名单条目
DELETE /v1/blacklist/entries/{entry_id} # 移除黑名单条目

避坑指南： 不要在端点中使用动词（如 /assessTransaction），应使用HTTP方法表达动作。端点路径应全部小写，单词间使用连字符（-）或下划线（_），保持一致性。

2.3 请求与响应模型

RESTful API的请求与响应遵循标准的HTTP消息结构。下面以风控交易评估接口为例，展示完整的请求与响应模型。

2.3.1 请求模型

一个标准的HTTP请求包含以下部分：

请求行： HTTP方法 + 资源路径 + HTTP版本
请求头（Headers）： 包含认证信息、内容类型、请求ID等元数据
请求体（Body）： 携带业务数据，通常为JSON格式

风控交易评估请求示例：

POST /v1/transactions/assess HTTP/1.1
Host: api.riskcontrol.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type: application/json
X-Request-ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890

{
  "transaction_id": "TXN20250321001",
  "amount": 15000.00,
  "currency": "CNY",
  "payer": {
    "user_id": "U12345",
    "account_id": "A67890",
    "ip_address": "192.168.1.100",
    "device_fingerprint": "fp_abc123xyz"
  },
  "payee": {
    "user_id": "U67890",
    "account_id": "A12345"
  },
  "timestamp": "2025-03-21T14:30:00+08:00"
}

2.3.2 响应模型

风控API的响应应包含状态码、响应头和响应体，其中响应体需包含评估结果、风险等级、建议动作等关键信息。

风控交易评估响应示例：

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

{
  "status": "completed",
  "risk_level": "high",
  "risk_score": 85,
  "decision": "reject",
  "reasons": [
    {
      "code": "RULE_1001",
      "message": "单笔交易金额超过用户历史均值5倍",
      "severity": "critical"
    },
    {
      "code": "RULE_2003",
      "message": "IP地址归属地与用户常用登录地不一致",
      "severity": "high"
    }
  ],
  "suggested_action": "block_transaction",
  "evaluation_time_ms": 45
}

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

HTTP方法是RESTful API对资源执行操作的动词。在风控API设计中，四种主要方法对应CRUD（创建、读取、更新、删除）操作。

HTTP方法	CRUD操作	幂等性	安全性	风控API典型用途
GET	读取（Read）	是	是	查询交易评估结果、获取规则列表、查看黑名单
POST	创建（Create）	否	否	提交交易进行风控评估、添加黑名单条目、触发规则测试
PUT	更新/替换（Update）	是	否	更新风控规则配置、替换白名单条目
DELETE	删除（Delete）	是	否	删除过期规则、移除黑名单条目、清除缓存

  关键概念：
  幂等性： 多次执行相同的请求，资源状态与执行一次相同。GET、PUT、DELETE是幂等的，POST不是。
安全性： 请求不会改变服务器上的资源状态。只有GET是安全的。
在风控场景中，POST是最常用的方法，因为交易评估本质上是创建一次评估任务，每次结果可能不同（非幂等）。

2.5 RESTful风控API架构总览

下图展示了实时交易风控系统中RESTful API的完整调用链路和核心组件关系：

2.6 HTTP状态码在风控API中的应用

正确使用HTTP状态码可以让调用方快速理解请求结果，减少沟通成本。以下是风控API中常用的状态码：

状态码	含义	风控场景
200 OK	请求成功	交易评估完成，返回风险结果
201 Created	资源创建成功	成功添加黑名单条目
400 Bad Request	请求参数错误	交易金额为负数、缺少必填字段
401 Unauthorized	认证失败	API密钥无效或已过期
403 Forbidden	无权限访问	调用方未被授权访问特定规则资源
404 Not Found	资源不存在	查询不存在的交易ID或规则ID
429 Too Many Requests	请求频率超限	超过API调用配额，触发限流
500 Internal Server Error	服务器内部错误	风控引擎异常、数据库连接失败
503 Service Unavailable	服务暂时不可用	风控引擎正在重启或过载

最佳实践： 即使返回4xx或5xx状态码，响应体也应包含结构化的错误信息，包括 error_code、message 和 request_id，方便调用方定位问题。

2.7 本章小结

通过本章学习，您已掌握RESTful API在实时交易风控系统中的核心概念：

RESTful API 通过无状态、统一接口等约束，为风控系统提供标准化的通信方式。
API端点 使用名词复数形式表示资源，结合HTTP方法表达操作意图。
请求与响应模型 采用JSON格式，请求携带交易上下文，响应返回风险等级、评分和决策建议。
HTTP方法 中POST用于交易评估（非幂等），GET/PUT/DELETE用于资源管理（幂等）。
HTTP状态码 帮助调用方快速判断请求结果，200表示成功，4xx表示客户端错误，5xx表示服务端错误。