计算机网络 / 系统课时
7.8 RESTful API 设计
RESTful API 设计
🎯 学习目标:理解 REST 的核心原则,能设计出规范、可预测的 API。
REST 是一种风格,不是标准
REST 是一套设计 Web API 的风格约定:把一切抽象为资源,用 URL 定位资源、用 HTTP 方法表达操作、用状态码表达结果。目标是让 API 可预测、自解释、易维护。
核心原则
1. 用名词表示资源,别用动词。
text
✅ GET /users 获取用户列表
✅ GET /users/42 获取 id=42 的用户
✅ POST /users 创建用户
✅ PUT /users/42 更新用户
✅ DELETE /users/42 删除用户
❌ GET /getUsers ❌ POST /createUser ❌ POST /deleteUserByIdURL 里是资源(名词),动作交给 HTTP 方法。这样一套资源自然支持增删改查,无需为每个操作发明新路径。
2. 用 HTTP 方法表达语义(呼应 7.1 的方法表):GET 查、POST 增、PUT/PATCH 改、DELETE 删。别用 GET 做修改(GET 应当无副作用且可缓存)。
3. 用状态码表达结果(呼应 7.2):成功 200/201/204,客户端错 4xx,服务端错 5xx。别用 200 包装错误。4. 层级表达关系。 用嵌套表达从属:
text
GET /users/42/orders 某用户的所有订单
GET /users/42/orders/1001 某用户的某个订单5. 复杂查询用查询参数。 分页、过滤、排序放 query:
text
GET /users?page=2&size=20&role=admin&sort=-createdAt一致性比"纯粹"更重要
REST 是风格不是铁律,现实中常有取舍:批量操作、复杂业务动作(如"取消订单")有时难以纯资源化。这时团队内保持一致比"绝对符合 REST"更重要——比如统一约定复杂动作用 POST /orders/{id}/cancel 这样的子资源,全项目照此办理即可。
按自己的节奏,确认真正理解。