3. API设计原则

风控规则引擎的API是业务系统与决策核心之间的桥梁。设计不良的API会导致集成困难、版本混乱、重复扣分甚至数据不一致。本章围绕四个核心原则展开：RESTful风格、资源命名规范、版本控制策略和幂等性设计，确保API既符合业界标准，又能应对风控场景的高并发与强一致性要求。

3.1 RESTful风格：以资源为中心

REST（Representational State Transfer）是一种基于HTTP协议的架构风格。在风控规则引擎中，我们将决策请求、规则集、策略、名单等视为资源，通过标准HTTP方法对其进行操作。

3.2 资源命名规范：清晰、一致、可预测

资源命名是API的可读性基石。风控规则引擎涉及多种资源类型，命名应遵循以下规范：

• 使用复数名词：/rules、/decisions、/blacklists，而非 /rule、/getDecision。
• 层级关系用斜杠表示：/rules/{ruleId}/versions 表示某个规则的所有版本。
• 查询参数用于过滤和分页：/decisions?status=reject&page=1&size=20。
• 使用小写字母和连字符：/risk-profiles 而非 /riskProfiles 或 /risk_profiles。
• 避免过深的嵌套：超过三级嵌套建议使用查询参数或扁平化设计。

3.3 版本控制策略：平滑演进，向后兼容

风控规则引擎需要频繁迭代规则逻辑、新增字段或调整决策流程。版本控制是保障客户端不受破坏性变更影响的关键。

推荐采用URL路径版本控制，将版本号显式放在路径中：

GET /v1/decisions/{decisionId}
GET /v2/decisions/{decisionId}

版本控制的核心原则：

• 主版本号（v1, v2）：引入不兼容变更时递增，如删除字段、修改响应结构。
• 向后兼容：同一主版本内，只做新增字段或可选参数变更，不破坏已有客户端。
• 版本生命周期：每个版本至少维护6-12个月，提前通知废弃计划。
• 默认版本：新客户端应始终使用最新稳定版本，旧版本逐步下线。

3.4 幂等性设计：防止重复扣分与重复决策

在风控场景中，网络超时、客户端重试、消息队列重复投递都可能导致同一笔交易被多次提交。如果API不具备幂等性，就会产生重复扣分、重复审核、重复发送告警等严重问题。

幂等性指无论调用多少次，结果都与调用一次相同。对于风控规则引擎，以下方法需要重点设计幂等：

• POST /decisions：提交决策请求，必须支持幂等。
• PUT /rules/{ruleId}：全量更新规则，天然幂等。
• DELETE /blacklists/{id}：删除操作，重复调用返回相同结果。

幂等性实现方案：客户端令牌（Idempotency-Key）

客户端在请求头中携带一个全局唯一的 Idempotency-Key（如UUID），服务端缓存该Key及其响应结果。当收到相同Key的请求时，直接返回缓存结果，不再重复执行业务逻辑。

POST /v2/decisions
Content-Type: application/json
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

{
  "transactionId": "TXN20250321001",
  "amount": 1500.00,
  "userId": "U12345"
}

3.5 原则总结与设计检查清单