📋 HTTP 方法与状态码速查表

这份速查表帮助你快速查阅 RESTful API 设计中常用的 HTTP 方法和状态码。

💬 看到不懂的方法或状态码？点右下角 ❓ 有疑问 提交，我会把解答做成青紫色方框插到相关章节，并告诉你它在哪。

HTTP 方法

GET - 获取资源

语义：获取指定资源，不修改服务器状态

幂等性：✅ 是（多次请求结果相同）

安全性：✅ 是（不改变资源状态）

使用场景：

获取资源列表：GET /api/users
获取单个资源：GET /api/users/123
搜索/筛选：GET /api/users?role=admin

POST - 创建资源

语义：创建新资源或提交数据

幂等性：❌ 否（多次请求会创建多个资源）

安全性：❌ 否（会创建新资源）

使用场景：

创建新资源：POST /api/users
提交表单数据：POST /api/contact
触发操作：POST /api/orders/123/cancel

PUT - 更新资源（全量）

语义：完整替换指定资源

幂等性：✅ 是（多次请求结果相同）

安全性：❌ 否（会修改资源）

使用场景：

更新整个资源：PUT /api/users/123
需要提供完整的资源数据
如果资源不存在，可选择创建（404 或 201）

PATCH - 更新资源（部分）

语义：部分更新指定资源

幂等性：✅ 是（多次请求结果相同）

安全性：❌ 否（会修改资源）

使用场景：

更新部分字段：PATCH /api/users/123
只需提供需要修改的字段
比 PUT 更节省带宽

DELETE - 删除资源

语义：删除指定资源

幂等性：✅ 是（多次请求结果相同）

安全性：❌ 否（会删除资源）

使用场景：

删除资源：DELETE /api/users/123
软删除：DELETE /api/users/123（标记为已删除）
批量删除：DELETE /api/users?ids=1,2,3

📊 HTTP 状态码

✅ 成功响应 (2xx)

状态码	名称	使用场景	示例
200	OK	成功获取或更新资源	GET /api/users/123 → 返回用户数据
201	Created	成功创建资源	POST /api/users → 返回新创建的用户
204	No Content	成功删除，无返回内容	DELETE /api/users/123 → 空响应体

⚠️ 客户端错误 (4xx)

状态码	名称	使用场景	示例
400	Bad Request	请求参数错误或验证失败	POST /api/users → 缺少必填字段
401	Unauthorized	未认证（需要登录）	GET /api/profile → 未提供 Token
403	Forbidden	无权限访问	DELETE /api/admin → 普通用户尝试删除
404	Not Found	资源不存在	GET /api/users/999 → 用户不存在
409	Conflict	资源冲突（如重复创建）	POST /api/users → 邮箱已存在
422	Unprocessable Entity	语义错误（验证通过但逻辑错误）	POST /api/orders → 库存不足

❌ 服务器错误 (5xx)

状态码	名称	使用场景	示例
500	Internal Server Error	服务器内部错误（未捕获异常）	数据库连接失败
502	Bad Gateway	网关错误（微服务间调用失败）	下游服务不可用
503	Service Unavailable	服务不可用（维护或过载）	系统升级中

💡 RESTful 设计最佳实践

GET /api/users 200 - 获取用户列表
GET /api/users/123 200 - 获取单个用户
POST /api/users 201 - 创建用户
PUT /api/users/123 200 - 更新用户
PATCH /api/users/123 200 - 部分更新
DELETE /api/users/123 204 - 删除用户

💡 设计原则：

名词复数：使用 /users 而非 /user
嵌套关系：/users/123/orders 表示用户123的订单
查询参数：用于过滤、排序、分页（?page=1&size=10）
版本控制：/api/v1/users 或 Header Accept-Version: v1

🔗 相关链接

← 第2课第3课：数据库集成（待开课）