HTTP 方法速查
9 个方法 · 安全性 / 幂等性 / 状态码 · 支持过滤
| 操作 | 方法 | 路径 | 说明 |
|---|---|---|---|
| 查列表 | GET | /users?page=2 | 分页参数放 query,返回 200 + 数组 |
| 查详情 | GET | /users/1 | 找不到就 404,别返回 200 + null |
| 创建 | POST | /users | 成功返回 201 + Location 指向新资源 |
| 整体替换 | PUT | /users/1 | 客户端要传完整对象 |
| 局部更新 | PATCH | /users/1 | 只传要改的字段 |
| 删除 | DELETE | /users/1 | 成功 204 无响应体 |
| 轻量检查 | HEAD | /users/1 | 只要知道存在与否,不下载正文 |
| 查支持方法 | OPTIONS | /users | 返回 Allow 头列出可用方法 |
如何使用本工具
- 顶部输入框里搜关键词,比如「幂等」「201」「上传」都能命中。
- 每张卡片右上角是常见状态码,下面四个标签说明这个方法的性质。
- 记住两条最容易混的:PUT 是整体替换、幂等;PATCH 是局部更新、不保证幂等。
- 设计接口时对照下面的 REST 表,先想清楚「这一步是换掉资源还是改字段」,方法自然就选对了。
常见问题
Q:PUT 和 PATCH 到底怎么选?
A:看调用方知不知道资源的完整样子。知道、能传全量,就用 PUT,它的语义是「这个资源现在应该长这样」,重复调用结果一样,网络重试很安全。只知道要改哪个字段,就用 PATCH,但要注意它不保证幂等,并发场景最好配 ETag 做乐观锁。
Q:POST 不幂等,那重试怎么办?
A:让客户端生成一个幂等键(比如 UUID),放在请求头或请求体里一起发。服务端把这个键存起来,遇到重复的键直接返回第一次的结果。支付、下单、发券这类接口必须这么做,否则用户手抖点两下就多一笔。
Q:「安全」和「幂等」是两个不同的事?
A:安全(safe)指不改变服务端状态,GET、HEAD、OPTIONS、TRACE 属于这一类,所以浏览器敢预取、爬虫敢抓。幂等(idempotent)指执行多次和执行一次效果相同,PUT 和 DELETE 幂等但不安全。一个方法可以安全又幂等(GET),也可以两条都不满足(POST)。
Q:为什么 OPTIONS 老是被 CORS 卡住?
A:跨域且不是简单请求时,浏览器会先发一个 OPTIONS 预检,问服务器「我能不能用这个方法和这些头」。如果后端把 OPTIONS 也走了鉴权,预检直接 401,浏览器就不会再发真正的请求。正确做法是让 OPTIONS 无条件返回 204 并带上 Access-Control-Allow-* 头。
Q:接口里 DELETE 要不要带请求体?
A:尽量不带。规范没禁止,但不少代理、网关、CDN 会丢掉 DELETE 的请求体,行为不一致。真要传一堆条件,改成 POST /users/1:cancel 这类动作式接口更稳。
Q:404 和 410 有什么区别?
A:404 是「现在找不到」,可能以后又有;410 是「这里曾经有,永久没了」。搜索引擎看到 410 会更快地把 URL 从索引里删掉,做内容下线时用 410 比 404 利索。