什么是API设计模式
开发中经常要和API打交道。不管是调用别人的接口，还是自己写服务供别人调用，一个设计良好的API能让协作变得顺畅。API设计模式就是一些被反复验证过的、解决常见问题的接口设计套路。它们不是硬性规范，但能帮你避免踩坑。
资源导向的REST风格
很多人提到API就想到REST。它主张把数据当作“资源”来设计接口。比如用户信息是一个资源，地址就该是 /users，而不是 /getUserList 这种动词开头的写法。
操作方式通过HTTP方法表达：GET查、POST增、PUT改、DELETE删。这种约定能让调用者一看路径和方法就知道要干什么，就像日常对话一样自然。
GET /users // 获取用户列表
POST /users // 创建新用户
GET /users/123 // 获取ID为123的用户
PUT /users/123 // 更新用户信息
DELETE /users/123 // 删除用户统一的响应结构
有些团队返回成功时给数据，出错时直接抛异常，前端处理起来特别头疼。更好的做法是统一包装响应体，无论成败都返回类似结构：
{
"code": 0,
"message": "success",
"data": {
"id": 123,
"name": "张三"
}
}这样前端可以统一判断code字段，不需要写一堆try-catch或不同逻辑分支，代码更干净。
分页与过滤参数标准化
列表接口几乎都会遇到分页。与其每个接口自己定义参数名，不如统一使用 page 和 size，或者偏移式 offset 和 limit。
搜索条件也尽量用一致的方式传递。比如用户列表按名字查询，可以这样：
GET /users?page=1&size=10&name=张这种风格看起来像浏览器搜东西，开发者容易猜出怎么用，减少翻文档的次数。
版本控制别等到上线才想
API一旦发布，就不能随便改。加字段还好，删字段或改字段名可能让老客户端崩溃。提前在URL或请求头里加上版本号，能平滑过渡。
GET /v1/users
// 或
GET /users Header: Accept: application/vnd.myapp.v1+json新功能上 v2，老系统还能跑在 v1，两边互不干扰，升级更从容。
错误码设计要有意义
别所有错误都返回500。HTTP状态码本身就是一种标准信号。404表示资源不存在，400说明参数不对，401是没登录，这些都能帮助调用方快速定位问题。
配合前面说的统一响应体，再加上自定义业务错误码，排查效率会高很多。比如下单失败，返回400 + code 2003，文档里注明这是“库存不足”，前端就能给出明确提示。
用HATEOAS让API自己“说话”
这个模式可能听起来有点陌生，但其实很实用。它指的是在返回结果里附带相关操作的链接，告诉调用者“接下来你能做什么”。
{
"id": 123,
"name": "张三",
"links": [
{ "rel": "self", "href": "/users/123" },
{ "rel": "delete", "href": "/users/123", "method": "DELETE" }
]
}这种设计让API更有“导航感”，适合复杂流程，比如订单状态流转，每一步都提示下一个可执行动作。
幂等性设计减少意外
网络不稳定时，客户端可能会重复提交请求。比如创建订单的API被发了两次，结果生成两个订单，用户就被多扣钱了。这时候就需要幂等性——同样的请求多次执行，效果和一次一样。
常见做法是让客户端传一个唯一标识（如request_id），服务端先检查是否处理过，避免重复操作。这种模式在支付、提交类接口中几乎是标配。