3. API 设计原则：RESTful 规范、资源命名、版本控制策略在 AML 场景下的应用

在反洗钱（AML）推理链路中，API 是连接数据源、规则引擎、模型推理与案件管理系统的核心桥梁。遵循 RESTful 设计原则，能够确保 AML 系统具备可扩展性、可维护性与清晰的语义边界。本节将聚焦于 RESTful 规范、资源命名策略以及版本控制方法在 AML 场景下的具体落地实践。

3.1 RESTful 规范在 AML 场景中的核心约束

REST（Representational State Transfer）是一种基于 HTTP 协议的架构风格。在 AML 系统中，我们严格遵循以下核心约束：

• 无状态性（Stateless）： 每个 API 请求必须包含所有必要信息，服务端不保存客户端上下文。例如，查询交易链路时，客户端需在每次请求中携带认证令牌与筛选参数。
• 统一接口（Uniform Interface）： 使用标准的 HTTP 方法（GET、POST、PUT、PATCH、DELETE）对资源进行操作，避免自定义动作。
• 资源导向（Resource-Oriented）： 将 AML 业务实体（如交易、客户、预警、案例）抽象为资源，通过 URI 进行唯一标识。
• 表现层状态转移（HATEOAS）： 在响应中包含相关资源的链接，引导客户端进行下一步操作，提升 API 的可发现性。

3.2 资源命名策略：AML 业务实体的 URI 设计

资源命名是 RESTful API 设计的核心。在 AML 场景下，命名应遵循以下规范：

以下是一个典型的 AML 推理链路资源树示例：

# 客户资源
/customers
/customers/{customerId}
/customers/{customerId}/risk-profiles

# 交易资源
/transactions
/transactions/{transactionId}
/transactions/{transactionId}/link-analysis

# 预警与案例资源
/alerts
/alerts/{alertId}
/alerts/{alertId}/investigations
/cases
/cases/{caseId}
/cases/{caseId}/evidence

# 推理链路专用资源
/inference-chains
/inference-chains/{chainId}
/inference-chains/{chainId}/nodes
/inference-chains/{chainId}/edges

3.3 版本控制策略：保障 AML 推理链路的稳定性

AML 系统通常需要与监管机构、数据提供商以及内部多个子系统对接。API 版本控制是避免破坏性变更影响业务连续性的关键手段。以下是三种主流策略在 AML 场景下的对比：

3.4 AML 推理链路 API 版本生命周期管理

为了确保 AML 系统在监管审计中具备可追溯性，API 版本的生命周期管理必须制度化：

• 主版本号（Major）： 当引入不兼容的 API 变更时递增，例如修改推理链路的节点数据结构或删除必填字段。
• 次版本号（Minor）： 当向后兼容地新增功能时递增，例如为推理链路新增一个可选的“风险标签”字段。
• 补丁版本号（Patch）： 当进行内部 bug 修复且不改变 API 契约时递增，例如修复某个节点计算逻辑的精度问题。
• 废弃策略： 每个主版本至少维护 12 个月，废弃前需提前 6 个月在响应头中添加 Deprecation: true 和 Sunset: datetime 字段。

3.5 实战案例：设计一个 AML 推理链路查询 API

假设我们需要设计一个查询“客户关联交易推理链路”的 API。结合上述原则，最终设计如下：

# 请求示例
GET /v2/customers/550e8400-e29b-41d4/inference-chains?depth=3
Authorization: Bearer <token>
Accept: application/vnd.aml.v2+json

# 响应示例（简化）
{
  "chainId": "a1b2c3d4-e5f6-7890",
  "customerId": "550e8400-e29b-41d4",
  "depth": 3,
  "nodes": [
    {
      "nodeId": "n1",
      "type": "transaction",
      "label": "转账 50000 USD",
      "timestamp": "2025-03-01T10:30:00Z"
    },
    {
      "nodeId": "n2",
      "type": "entity",
      "label": "关联公司 A",
      "riskScore": 85
    }
  ],
  "edges": [
    {
      "source": "n1",
      "target": "n2",
      "relationship": "beneficiary"
    }
  ],
  "_links": {
    "self": { "href": "/v2/customers/550e8400-e29b-41d4/inference-chains?depth=3" },
    "full-chain": { "href": "/v2/customers/550e8400-e29b-41d4/inference-chains?depth=10" },
    "alerts": { "href": "/v2/alerts?customerId=550e8400-e29b-41d4" }
  }
}