HM

HTTP 方法速查

9 个方法 · 安全性 / 幂等性 / 状态码 · 支持过滤

共 9 个方法
GET200 / 304 / 404
安全幂等可缓存无请求体
读取资源,不该产生任何副作用
别用 GET 做写操作。浏览器预取、爬虫、聊天软件生成链接预览都会真的把 URL 请求一遍,「点开这个链接就删库」就是这么来的。查询参数放 URL 上,注意会进日志和 Referer。
HEAD200 / 304 / 404
安全幂等可缓存无请求体
只要响应头,不要响应体
常用来探活、查文件大小(看 Content-Length)、查是否被修改(看 Last-Modified)。规范要求 HEAD 的响应头和 GET 完全一致,但现实中不少服务器没实现好,别强依赖。
POST201 / 200 / 400 / 409
非安全非幂等带请求体
创建资源、提交表单、触发动作
不幂等:同样的请求发两次会创建两条记录。做支付、下单这类接口必须加幂等键(客户端生成一个唯一的 request-id,服务端去重),否则用户连点两下就是两笔。
PUT200 / 201 / 204 / 409
非安全幂等带请求体
用请求体整体替换目标资源
幂等但语义是「整体替换」。请求体里漏掉的字段等于把它们清空,这是最容易踩的坑。只改一个字段时别用 PUT,会误伤其他字段。
PATCH200 / 204 / 409 / 415
非安全非幂等带请求体
只提交要改的字段
规范上不保证幂等。用 JSON Merge Patch(application/merge-patch+json)时语义接近幂等,但数组的合并规则有歧义。并发更新建议配 If-Match + ETag 做乐观锁。
DELETE204 / 200 / 404
非安全幂等带请求体
删除目标资源
幂等指的是「执行一次和执行多次,服务端状态一样」。第二次删同一个资源返回 404 还是 204是设计选择,只要状态没变就符合幂等。有些网关会拦带体的 DELETE,能不传就不传。
OPTIONS204 / 200
安全幂等无请求体
问服务器这个资源支持哪些方法
跨域请求的预检(CORS preflight)用的就是它。注意别在鉴权中间件里把 OPTIONS 一起拦掉,否则浏览器预检拿不到 Access-Control-Allow-* 头,正经请求根本发不出去。
TRACE405(多数生产环境直接禁)
安全幂等无请求体
把收到的请求原样回显,用于链路诊断
存在 XST(跨站跟踪)风险,能配合 HttpOnly 绕过读取 Cookie。主流服务器默认关闭,如果安全扫描报这个,直接回 405 就行。
CONNECT200
非安全非幂等无请求体
让代理建立一条 TCP 隧道
HTTPS 走代理时用的就是它:客户端先 CONNECT example.com:443,代理建好隧道后再在里面跑 TLS。写业务接口基本不会碰这个方法。
操作方法路径说明
查列表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 头列出可用方法

如何使用本工具

  1. 顶部输入框里搜关键词,比如「幂等」「201」「上传」都能命中。
  2. 每张卡片右上角是常见状态码,下面四个标签说明这个方法的性质。
  3. 记住两条最容易混的:PUT 是整体替换、幂等;PATCH 是局部更新、不保证幂等。
  4. 设计接口时对照下面的 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 利索。