API设计原则：RESTful设计哲学、资源导向设计、无状态性、幂等性设计
好，咱们今天聊聊API设计原则。说实话，这章内容我特别想跟你好好掰扯掰扯。为什么？因为我在风控系统里踩过的坑，十有八九都跟这些原则没吃透有关。你想想看，风控系统每天要处理几百万甚至上千万的请求，如果API设计一开始就歪了，后面想改？那成本可就大了去了。
RESTful设计哲学：别把它当教条
很多人一提到RESTful，就想到一堆条条框框。什么必须用名词、必须用特定HTTP方法、必须返回特定状态码……我个人习惯是，先理解它的核心思想，再结合实际场景做取舍。
RESTful的核心是什么？说白了，就是把你的业务能力抽象成「资源」。风控系统里，资源可以是「用户」、「订单」、「规则」、「策略」、「黑名单」等等。每个资源都有唯一的标识（URI），通过HTTP方法（GET、POST、PUT、DELETE）来操作。
核心要点：RESTful不是银弹，但它提供了一套很好的沟通语言。团队内部用这套语言，沟通成本会低很多。
我在项目中遇到过一种情况：有人把RESTful用成了RPC。比如设计一个接口叫 /api/checkRisk，这明显是个动作，不是资源。正确的做法应该是 /api/orders/{orderId}/risk，把「风险检查」看作是订单资源的一个子资源或操作。
资源导向设计：你的API就是你的数据模型
资源导向设计，说白了就是「你的API长什么样，你的数据模型就长什么样」。这一点在风控系统里尤其重要。因为风控系统本质上是在处理各种实体之间的关系。
举个例子，风控系统里常见的资源关系：
| 资源 | URI示例 | 说明 |
|---|---|---|
| 用户 | /api/users/{userId} |
用户基本信息 |
| 用户的风险画像 | /api/users/{userId}/riskProfile |
用户的综合风险评分 |
| 用户的订单列表 | /api/users/{userId}/orders |
该用户的所有订单 |
| 订单的风险决策 | /api/orders/{orderId}/decision |
该订单的最终风控决策 |
| 规则引擎 | /api/rules/{ruleId} |
风控规则的定义 |
你发现没有？这种设计方式，让API的路径本身就表达了数据之间的层级关系。前端同学一看就懂，后端同学维护起来也清晰。
我的小技巧：设计资源时，先画一张实体关系图（ER图）。API的路径结构，基本上就是这张图的映射。别跳过这一步，我见过太多人直接上手写接口，写到一半发现资源关系理不清，又得重构。
无状态性：风控系统的命脉
无状态性，这是RESTful里最容易被忽略、但又最关键的一条。为什么？因为风控系统往往是分布式部署的，今天请求打到A机器，明天可能打到B机器。如果API有状态，那麻烦就大了。
无状态性的核心含义是：每个请求都包含所有必要的信息，服务器不保存任何客户端上下文。嗯，这里要注意，不是说你的系统不能有状态，而是说API层不能依赖服务端保存的会话状态。
我曾经接手过一个风控系统，它的API设计是这么干的：
// 错误示例：依赖服务端会话
POST /api/startRiskCheck
// 返回一个sessionId: "abc123"
POST /api/submitData
// 依赖sessionId: "abc123" 来获取上下文
POST /api/getResult
// 还是依赖sessionId
这种设计在单机部署时没问题，一旦上了集群，session同步就成了噩梦。而且，如果客户端丢了sessionId，整个流程就得重来。
正确的做法应该是这样：
// 正确示例：无状态设计
POST /api/riskCheck
{
"userId": "U12345",
"orderId": "O67890",
"amount": 1999.00,
"ip": "192.168.1.1",
"deviceId": "DEVICE_ABC",
"timestamp": 1700000000
}
// 返回结果，不依赖任何会话
{
"decision": "REJECT",
"reason": "高风险设备",
"riskScore": 85
}
避坑指南：我曾经因为没坚持无状态性，导致线上出现「同一个用户请求，不同机器返回不同结果」的诡异问题。查了两天才发现，是某台机器的会话缓存没清干净。从那以后，我所有风控API都强制要求无状态。
幂等性设计：重复请求不可怕
幂等性，这个词听起来高大上，其实意思很简单：同一个请求执行一次和执行多次，结果是一样的。在风控系统里，这太重要了。因为网络抖动、客户端重试、消息队列重复投递……这些情况太常见了。
举个例子，用户提交一笔订单，风控系统需要做决策。如果因为网络超时，客户端重试了三次，结果风控系统创建了三条相同的决策记录，那不就乱套了吗？
幂等性设计的常见做法：
- 使用幂等键（Idempotency Key）：客户端每次请求带一个唯一标识，服务端根据这个标识去重。
- 利用业务主键：比如用订单ID作为幂等键，同一个订单ID的请求只处理一次。
- 状态机校验：只有特定状态的资源才能执行特定操作。
我建议你在风控系统里这样实现幂等性：
// 请求头中携带幂等键
POST /api/orders/{orderId}/decision
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
// 服务端处理逻辑
1. 检查幂等键是否已存在
2. 如果存在，直接返回上次的处理结果
3. 如果不存在，执行风控决策，并缓存结果
4. 返回决策结果
重要提醒：幂等键的缓存时间要合理设置。太短了起不到去重作用，太长了浪费存储。我一般设置为24小时，对于风控场景来说足够了。
你想想看，如果没有幂等性设计，你的风控系统可能会遇到什么情况？
- 用户重复提交订单，风控系统重复扣减额度
- 规则引擎重复执行，导致规则命中次数统计翻倍
- 黑名单重复添加，造成数据冗余
这些坑，我全都踩过。嗯，说起来都是泪。
本章知识体系
下面这张图，是我对本章核心逻辑的总结。你可以把它当作一个快速参考：
最后说一句：这些原则不是用来束缚你的，而是用来帮你做决策的。遇到具体问题时，问问自己：「这样设计，违反了哪条原则？违反了会有什么后果？」想清楚了，再做决定。
公众号:蓝海资料掘金营，微信deep3321