📚 课程目录第4章 API设计原则

4. API 设计原则：RESTful 设计规范、资源命名、版本控制策略、无状态设计

实时交易风控 API 的设计必须兼顾金融系统的严谨性与互联网 API 的易用性。本章围绕 RESTful 架构风格，从资源命名、版本控制、无状态约束三个核心维度展开，确保 API 在高速交易场景下具备可扩展性、可维护性与高可用性。

REST（Representational State Transfer）是一种基于 HTTP 协议的架构风格，强调资源导向、统一接口与无状态通信。在风控系统中，每一笔交易、每一次规则评估、每一个风险事件都被抽象为资源，通过标准 HTTP 方法进行操作。

HTTP 方法	操作语义	风控场景示例	幂等性
GET	查询资源	查询交易风险评估结果	是
POST	创建资源 / 提交指令	提交交易进行实时风控审核	否
PUT	全量替换资源	更新风控规则配置	是
PATCH	部分更新资源	修改交易拦截状态	否
DELETE	删除资源	撤销已创建的风控策略	是

  关键约束：POST 用于创建或触发操作，不保证幂等；PUT 必须提供完整资源表示，幂等性由服务端保证。在交易风控中，POST /v1/transactions/risk-assessment 是核心入口，每次调用生成唯一的评估 ID。

资源 URI 是 API 的对外标识，命名应遵循名词复数、小写字母、连字符分隔的原则。避免使用动词或操作名，将动作隐含在 HTTP 方法中。

使用名词复数：/transactions、/risk-rules、/blocked-accounts
层级关系通过路径表达：/accounts/{accountId}/transactions
查询参数用于过滤与分页：/transactions?status=blocked&page=1&size=50
避免动词：不要使用 /getTransaction 或 /createRule，应使用 GET /transactions/{id} 和 POST /risk-rules

最佳实践：风控 API 中，/v2/risk-evaluations 比 /v2/evaluate-risk 更符合 REST 风格。资源名保持一致性，客户端可通过标准 HTTP 方法推导所有操作。

风控 API 的版本控制是保障向后兼容与平滑演进的关键。推荐使用 URI 路径版本控制，将版本号显式嵌入路径中，如 /v1/、/v2/。这种方式最直观，客户端无需解析请求头即可明确版本。

版本策略	实现方式	优点	缺点
URI 路径版本	`/v1/transactions`	显式、易缓存、客户端无歧义	URI 结构变长
请求头版本	`Accept: application/vnd.risk.v2+json`	URI 简洁、符合 REST 语义	调试困难、网关支持要求高
查询参数版本	`/transactions?version=2`	实现简单	缓存混乱、语义不清晰

避坑提示：不要使用查询参数进行版本控制，容易导致缓存键冲突，且不符合 REST 资源标识的稳定性原则。风控系统建议统一采用 URI 路径版本，并在 API 网关层做版本路由。

无状态（Stateless）是 REST 架构的核心约束之一。每个请求必须包含服务端处理所需的所有信息，服务端不保存客户端上下文。在实时交易风控中，无状态设计直接决定了系统的水平扩展能力与故障恢复速度。

实践建议：在风控 API 中，每个 POST 请求必须携带 Idempotency-Key 请求头，服务端基于该键进行去重判断。无状态设计配合幂等键，可有效防止重复交易审核导致的资金风险。