## 开场

> 世界上最远的距离，不是生与死，而是你写的API文档就摆在同事面前，他却看不懂你设计的URL。

作为一个写过无数API、也接无数API的老司机，我太懂那种看到一堆诡异接口时的崩溃感了。

`/getUserInfoById?id=123` —— 兄弟，都2026年了，RESTful的春风还没吹到你家吗？

`/api/v1.0/getUser` —— 版本号写URL里，你是打算每个版本都新建一套接口吗？

`POST /deleteUser` —— 用POST来删除，你是想让接手的同学怀疑人生吗？

今天我们就来聊聊，如何设计一批让人看了就想给你递烟的API。

## 一、URL设计：名字取得好，沟通没烦恼

### 资源名词，而非动词

这条规则我都说倦了，但架不住有人就是不听。

❌ 错误示范：
- `/getUsers`
- `/createUser`
- `/updateUserInfo`

✅ 正确姿势：
- `GET /users` —— 获取用户列表
- `POST /users` —— 创建用户
- `PUT /users/{id}` —— 完整更新用户
- `DELETE /users/{id}` —— 删除用户

记住一句话：**URL是名词的天下，动词请滚回HTTP方法里。**

### 层级结构要合理

❌ 过度嵌套：
```
GET /users/123/orders/456/items/789
```

✅ 扁平化设计：
```
GET /orders/456/items/789
```

层级控制在2-3层为宜，超过三层就要考虑是不是该拆API了。

## 二、HTTP方法：各司其职，别越俎代庖

| 方法 | 语义 | 幂等 |
|------|------|------|
| GET | 获取资源 | ✅ |
| POST | 创建资源 | ❌ |
| PUT | 完整替换 | ✅ |
| DELETE | 删除资源 | ✅ |

**GET、PUT、DELETE是幂等的**——调用1次和调用100次效果一样。**POST是非幂等的**——每次调用都会产生新资源。

这就解释了为什么删除用DELETE、更新用PUT、创建用POST。如果你用POST来做所有事情——`POST /deleteUser`、`POST /getUserList`——恭喜你，你成功让整个团队的性能监控变成了玄学。

## 三、状态码：别总返回200，地球人都知道成功了

我知道 `200 OK` 很迷人，但它不是万能的。

**2xx 成功系列：**
- `200 OK` —— 最常见的成功
- `201 Created` —— 创建资源成功
- `204 No Content` —— 删除成功，不需要返回body

**4xx 客户端错误：**
- `400 Bad Request` —— 请求参数有问题
- `401 Unauthorized` —— 未认证
- `403 Forbidden` —— 没权限
- `404 Not Found` —— 资源不存在

**5xx 服务端错误：**
- `500 Internal Server Error` —— 我的错
- `503 Service Unavailable` —— 服务暂时不可用

见过最离谱的返回：
```json
{ "code": 0, "msg": "成功", "data": null }
```
改成 `HTTP 404` + `"用户不存在"` 不香吗？

## 四、错误处理：善良一点，给点有用的信息

```json
{
"error": {
"code": "USER_NOT_FOUND",
"message": "用户不存在",
"details": { "user_id": "12345" }
}
}
```

错误码要稳定——一旦公开就不要改。给错误码文档链接——接锅也要让接锅的人知道怎么查。

## 五、版本管理：别让URL里长满版本号

**URL版本**（最常见）：
```
/api/v1/users
/api/v2/users
```

**原则：尽量少版本，能不升级就不升级，向下兼容是底线。**

升级策略：
1. 新字段加在最后
2. 不要删除字段，打死也不删除
3. 废弃字段打标记，别偷偷删

## 六、分页和过滤：优雅地处理大数据

```json
GET /users?page=2&page_size=20

{
"data": [...],
"pagination": {
"current_page": 2,
"page_size": 20,
"total_pages": 50,
"total_count": 1000
}
}
```

过滤和排序：
```
GET /users?status=active&sort=created_at,-name
```

## 总结：好的API是怎样炼成的

1. **URL是名词，HTTP方法才是动词**
2. **状态码要对，别总返回200**
3. **错误信息要详细，别让前端猜谜**
4. **版本管理要谨慎，向下兼容是底线**
5. **分页过滤排序，缺一不可**

最后送大家一句话：**你设计的API，三年后你还要维护。善待自己，善待同事。**

写得一手好API，不仅能让你在团队里横着走，还能让你三年后回看代码时，不至于想穿越回去掐死当年的自己。

与君共勉。