RESTful API

1. RESTful API 概念

核心思想： 用 URL 定位资源，用 HTTP 方法描述操作。

• 资源：网络上的一个实体（如用户、文章），用 名词 表示。
• 端点：操作资源的 URL 地址。
• 无状态：每次请求都包含处理该请求所需的全部信息。

操作	传统描述	RESTful 风格
查询所有用户	getUsers()	GET /users
查询 ID 为 1 的用户	getUser(1)	GET /users/1
创建新用户	createUser(...)	POST /users
更新用户 1	updateUser(1, ...)	PUT /users/1
删除用户 1	deleteUser(1)	DELETE /users/1

---

2. HTTP 方法

定义了对资源要执行的操作。

方法	描述	是否幂等	是否有请求体
GET	检索/获取资源	是	通常无
POST	创建新资源	否	有
PUT	更新整个资源（全部替换）	是	有
PATCH	部分更新资源	否	有
DELETE	删除资源	是	通常无

幂等性：多次执行相同的操作，结果都一样。

---

3. HTTP 状态码

服务器对请求状态的响应。

码段	类别	常见状态码	描述
1xx	信息响应	100 Continue	请求已收到，请继续
2xx	成功	200 OK	成功 201 Created 创建成功 204 No Content 成功但无返回内容
3xx	重定向	301 Moved Permanently	资源已永久移动
4xx	客户端错误	400 Bad Request 请求错误 401 Unauthorized 未认证 403 Forbidden 无权限 404 Not Found 资源不存在
5xx	服务器错误	500 Internal Server Error 服务器内部错误 502 Bad Gateway 网关错误

---

4. 请求头/响应头

HTTP 请求和响应的元数据。

常见请求头：

Content-Type: application/json  // 请求体的格式
Authorization: Bearer <token>   // 身份验证令牌
Accept: application/json        // 希望接收的响应格式
User-Agent: ...                 // 客户端信息

常见响应头：

Content-Type: application/json  // 响应体的格式
Status: 200 OK                  // 状态码和描述
Set-Cookie: ...                 // 设置 Cookie

---

5. 请求体格式

客户端发送给服务器的数据格式。

格式	Content-Type	示例（创建用户）
JSON	application/json	{"name": "John", "age": 30}
Form Data	multipart/form-data	(用于文件上传和表单)
URL Encoded	application/x-www-form-urlencoded	name=John&age=30

---