计算机网络 / 系统课时

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 /deleteUserById

URL 里是资源(名词),动作交给 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 这样的子资源,全项目照此办理即可。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

7.8 RESTful API 设计

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通