📚 课程目录第3章 API接口设计原则

3. API 接口设计原则：RESTful 规范与反洗钱实战

在反洗钱推理链路中，API 是数据交换与指令下达的核心通道。遵循 RESTful 设计规范，能够确保接口的可读性、可维护性与扩展性。本章将围绕资源命名、HTTP 动词选择、状态码语义三大支柱，结合 AML 场景进行实战解析。

3.1 RESTful 核心设计原则

REST（Representational State Transfer）是一种基于资源的架构风格。在 AML 系统中，每一笔交易、每一个客户、每一条预警记录都应被视为一个“资源”，通过统一的接口进行访问与操作。

原则	说明	AML 场景示例
资源导向	URL 表示资源，而非操作	`/api/v1/transactions` 而非 `/api/v1/getTransactions`
无状态	每个请求包含所有必要信息	Token 携带用户权限与租户 ID
统一接口	使用标准 HTTP 动词操作资源	POST 创建预警，PUT 更新状态
可缓存	响应明确缓存策略	客户画像数据可缓存 5 分钟

设计要点： 反洗钱接口应避免在 URL 中出现动词（如 /createAlert），而应使用名词复数形式（如 /alerts），通过 HTTP 方法表达操作意图。

3.2 资源命名规范

资源命名是 RESTful 设计的起点。AML 推理链路中常见的资源包括：客户（customers）、交易（transactions）、预警（alerts）、案例（cases）、报告（reports）。

使用名词复数： /api/v1/customers、/api/v1/transactions
层级关系用斜杠： /api/v1/customers/{id}/transactions 表示某客户的所有交易
过滤参数用查询字符串： /api/v1/transactions?amount_gt=10000&date_from=2024-01-01
版本号放在路径前缀： /api/v1/ 或 /api/v2/
避免下划线，使用连字符： risk-score 而非 risk_score

  反洗钱命名示例：

  GET /api/v1/customers/{customerId}/transactions?type=wire&page=1

  POST /api/v1/alerts/{alertId}/actions  — 对预警执行操作（如升级、关闭）

3.3 HTTP 动词与 AML 操作映射

每个 HTTP 动词对应一种标准操作。在反洗钱推理链路中，动词的选择直接影响接口的语义清晰度。

HTTP 动词	CRUD 操作	AML 场景	请求体	响应状态码
GET	读取	查询交易列表、获取客户详情	无	200 OK
POST	创建	提交可疑交易报告、创建预警	有	201 Created
PUT	全量更新	更新客户风险等级	有	200 OK
PATCH	部分更新	修改预警状态为“调查中”	有	200 OK
DELETE	删除	删除误报预警	无	204 No Content

注意： 在 AML 系统中，DELETE 操作应谨慎使用。通常采用“软删除”或状态变更（如 PATCH /alerts/{id} { "status": "archived" }）替代物理删除，以满足审计追溯要求。

3.4 状态码选择策略

正确的状态码能让调用方快速理解请求结果。反洗钱接口应遵循以下状态码使用规范：

2xx 成功：
- 200 OK — GET、PUT、PATCH 成功返回
- 201 Created — POST 创建资源成功
- 204 No Content — DELETE 成功，无返回体
4xx 客户端错误：
- 400 Bad Request — 参数校验失败（如金额格式错误）
- 401 Unauthorized — 未提供或无效 Token
- 403 Forbidden — 无权限操作该资源
- 404 Not Found — 资源不存在
- 409 Conflict — 资源冲突（如重复提交预警）
- 422 Unprocessable Entity — 业务规则校验失败（如风险等级超出范围）
5xx 服务端错误：
- 500 Internal Server Error — 未捕获的异常
- 502 Bad Gateway — 上游推理引擎不可用
- 503 Service Unavailable — 服务过载或维护中

实战建议： 对于反洗钱推理链路中的批量操作（如批量更新预警状态），建议使用 202 Accepted 异步处理，并在响应中返回任务 ID，供客户端轮询结果。

3.5 RESTful 接口设计示例：预警管理

以下是一个完整的预警管理接口设计，涵盖资源命名、动词映射与状态码选择：

# 创建预警
POST /api/v1/alerts
Content-Type: application/json
{
  "transaction_id": "txn_20240301_001",
  "risk_score": 85,
  "rule_id": "rule_aml_007",
  "description": "大额跨境交易触发阈值"
}
Response: 201 Created
Location: /api/v1/alerts/alert_12345

# 查询预警列表
GET /api/v1/alerts?status=open&risk_score_gte=70
Response: 200 OK
{
  "data": [
    {
      "id": "alert_12345",
      "status": "open",
      "risk_score": 85,
      "created_at": "2024-03-01T10:30:00Z"
    }
  ],
  "total": 1,
  "page": 1
}

# 更新预警状态（部分更新）
PATCH /api/v1/alerts/alert_12345
Content-Type: application/json
{
  "status": "investigating",
  "assigned_to": "analyst_01"
}
Response: 200 OK

# 删除误报预警
DELETE /api/v1/alerts/alert_12345
Response: 204 No Content

3.6 反洗钱推理链路 API 架构图

下图展示了基于 RESTful 设计的 AML 推理链路 API 架构，清晰呈现资源层级与动词映射关系：

3.7 常见设计误区与避坑指南

误区	错误示例	正确做法
URL 中包含动词	`POST /api/createAlert`	`POST /api/v1/alerts`
忽略版本号	`/api/alerts`	`/api/v1/alerts`
状态码使用不当	创建成功返回 200	返回 201 Created + Location 头
嵌套层级过深	`/customers/{id}/transactions/{tid}/alerts`	使用查询参数：`/alerts?customer_id=xxx&transaction_id=yyy`
DELETE 返回 200 带 body	`DELETE /alerts/1` 返回 200 + 删除对象	返回 204 No Content

  核心原则总结： 资源是名词，动词是 HTTP 方法，状态码是语义信号。在反洗钱推理链路中，遵循 RESTful 规范不仅提升开发效率，更让接口语义对监管审计透明可追溯。