第 2 章:方法与状态码
一封请求信有两处"格式"最关键:信封上写的动作(方法),和对方回信时写的结论(状态码)。读懂这两样,大部分接口问题都能自己定位。
学习目标
- 分清 GET、POST、PUT、PATCH、DELETE 各自的语义
- 理解"幂等"是什么,为什么它决定了能不能重试
- 看到状态码能立刻判断:是我的问题、服务器的问题,还是可以重试
- 知道 401 和 403 的区别——这两个搞混,排查会走很多弯路
- 会用
curl -i自己刷出一份真实响应,对照本章规则验证
2.1 五个方法,各管一件事
| 方法 | 语义 | 有没有请求体 | 幂等 | 典型用途 |
|---|---|---|---|---|
GET | 读取资源 | 一般没有 | ✅ | 查列表、查详情、下载 |
POST | 提交/创建 | 有 | ❌ | 新建订单、发起对话、上传 |
PUT | 整体替换 | 有 | ✅ | 更新整条记录(传全量字段) |
PATCH | 局部修改 | 有 | ⚠️ 视实现 | 只改一个字段 |
DELETE | 删除 | 一般没有 | ✅ | 删除资源 |
幂等:同一个请求做多次,结果一样
"幂等"不是说"返回内容一样",而是副作用一样:
GET /books/1调十次,数据不变,幂等;DELETE /books/1调十次,第一次删掉,后九次都是"不存在",最终状态一样,幂等;POST /orders调十次,会建十张订单,不幂等。
为什么关心这个:网络超时的时候,你不知道请求到底成没成功。如果方法是幂等的,重试是安全的;如果是 POST,重试可能造成重复下单。
这就是为什么支付、下单这类接口需要额外的"幂等键"(Idempotency-Key 请求头),由服务端保证同一个键只处理一次。
GET 和 POST 的实际差别
很多人以为区别只是"参数放 URL 还是放 body",其实还有几个实际影响:
| 维度 | GET | POST |
|---|---|---|
| 参数位置 | URL 查询串 | 请求体 |
| 能否被缓存 | 可以(浏览器、CDN 常缓存) | 默认不缓存 |
| 会不会进访问日志 | 完整 URL 会进日志 | 体不进日志 |
| 长度限制 | 受 URL 长度限制(浏览器约 2KB 起) | 基本不受限 |
| 书签/分享 | 可以直接分享链接 | 不能 |
所以:
- 查数据用 GET,能被缓存、能分享、日志可查;
- 提交数据用 POST,尤其是含密钥、手机号、文件内容的;
- 不要把敏感信息放 URL:URL 会进浏览器历史、服务器日志、Referer 头。API Key 放查询参数是常见但危险的做法(第 5 章细讲)。
2.2 状态码:三段数字,各说各的事
状态码是三位数,第一位决定大类:
记住大类就够了:4xx 是你发错了,5xx 是对方崩了。这条判断直接决定"要不要改代码"还是"要不要等一会儿再试"。
必须认识的十个码
| 码 | 含义 | 你会遇到的场景 |
|---|---|---|
200 | 成功 | 绝大多数正常响应 |
201 | 已创建 | POST 新建资源成功 |
204 | 成功但无内容 | DELETE 成功、不返回体 |
301 / 302 | 永久 / 临时重定向 | 域名迁移、http 跳 https |
304 | 未修改 | 缓存命中,不重新下载 |
400 | 请求格式/参数有误 | JSON 少字段、类型不对 |
401 | 未认证 / 凭证无效 | 没带 token、token 过期 |
403 | 已认证但无权限 | 普通用户访问管理员接口 |
404 | 资源不存在 | 路径写错、id 不存在 |
429 | 请求过多被限流 | 免费额度、并发限制 |
500 / 502 / 503 | 服务端故障 | 对方服务崩了、网关超时、维护中 |
401 和 403 的区别
这两个最容易混:
- 401 Unauthorized:我不知道你是谁。解决方案是"去登录/换一个有效凭证"。
- 403 Forbidden:我知道你是谁,但你不能做这件事。再登录也没用,要找管理员授权。
实际排查时的差别:看到 401 先检查 token 有没有带、有没有过期;看到 403 先检查账号权限、接口是否对当前角色开放。
2.3 该不该重试:一张判断表
网络请求失败时,"再试一次"不是万能药。判断依据是错误类型 + 方法是否幂等:
| 情况 | 能重试吗 | 说明 |
|---|---|---|
| 连接超时 / 读超时 | ✅ | 网络抖动,等一下重试 |
429 限流 | ✅ | 按 Retry-After 头等一会儿 |
500 / 502 / 503 | ✅(有限次) | 对方临时故障,退避重试 |
400 / 422 | ❌ | 参数错了,重试还是错 |
401 / 403 | ❌ | 凭证/权限问题,重试无意义 |
404 | ❌ | 资源不存在 |
POST 超时 | ⚠️ 谨慎 | 可能已成功,需要幂等键或查状态 |
两条实践原则:
- 重试要有上限和退避。立刻连着重试三次,只会把对方的限流触发得更彻底。常用指数退避:1s、2s、4s。
- 非幂等操作重试前先确认结果。下单超时了,先查"这笔订单存不存在",再决定要不要重发。
2.4 一个真实响应长什么样
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 132
Cache-Control: no-store
X-Request-Id: 7f3a9c21
{"id":"chatcmpl-123","object":"chat.completion","choices":[{"message":{"role":"assistant","content":"你好"}}]}逐行读:
HTTP/1.1 200 OK:协议版本 + 状态码 + 原因短语;Content-Type:响应体是什么格式、什么编码;Content-Length:体有多长(字节);Cache-Control:能不能缓存;X-Request-Id:服务端的请求追踪号,报障时提供给对方,能快速定位;- 空行之后是响应体,这里是 JSON。
排查问题时,先看状态码,再看 Content-Type,最后看体。顺序反了容易误判——比如返回了 200 但体是 HTML 错误页,说明中间有网关拦截。
2.5 用 curl 亲手发一次请求
2.4 那份报文是摆给你看的。这一节换你来刷一份真的——只需要 curl,几乎所有系统自带,不用装 Python,不用开编辑器。
五个动作,从最简单开始
# ① 默认只输出响应体,状态码被藏起来了
curl https://www.51moqian.com/notes/http-json/
# ② 加 -i,四段全出来
curl -i https://www.51moqian.com/notes/http-json/
# ③ 访问一个不存在的路径,看 404
curl -i https://www.51moqian.com/notes/http-json/no-such-page
# ④ 静态站点不接受 POST,看 405
curl -i -X POST https://www.51moqian.com/notes/http-json/
# ⑤ 发一段 JSON 出去,让对方原样回显
curl -X POST -H 'Content-Type: application/json' \
-d '{"title":"hello"}' https://httpbin.org/post五条命令分别对上本章的哪些规则:
| # | 第一行会看到 | 对上哪节 |
|---|---|---|
| ① | 只有 HTML,没有状态行 | -i 的作用就是补回前三段 |
| ② | HTTP/1.1 200 OK | 2xx:成了 |
| ③ | HTTP/1.1 404 Not Found | 4xx:请求错了,重试也没用 |
| ④ | HTTP/1.1 405 Method Not Allowed | 方法不被允许,改方法而不是改参数 |
| ⑤ | 返回体里带 "json": {"title": "hello"} | 你发的 JSON 被完整接收并回显 |
④ 那条值得多想一步:同一个 URL,GET 能通、POST 不通,说明问题不在地址,在方法。这类报错如果按 2.3 的判断表去重试,只会白等。
四个开关,够用很久
| 开关 | 作用 | 什么时候用 |
|---|---|---|
-i | 连响应头一起显示 | 看状态码和响应头类型,最常用 |
-v | 打印全过程:请求头、TLS 握手、响应头 | 「我到底发出去什么了」 |
--max-time | 5 秒还没回就放弃 | 脚本里调接口,防止卡死 |
-L | 自动跟随 3xx 跳转 | 短链、域名迁移 |
-v 特别值得试一次:它会把请求头也打出来,你能亲眼看到自己带的 User-Agent、Accept、Host——这些正是第 3 章要拆的东西。
为什么示例用自己的域名
httpbin.org 是最好的「回显服务器」,但它在国内时通时不通。所以前四条都指向本站:域名稳定、分钟级可用,200、404、405 三种结果随要随有。第 ⑤ 条只是演示「怎么发 JSON」,连不上就跳过,不影响理解。
本章小结
| 要点 | 说明 |
|---|---|
| 五个方法 | GET 查、POST 建、PUT 整体替换、PATCH 局部改、DELETE 删 |
| 幂等 | 多次执行副作用相同,决定能否安全重试 |
| GET 与 POST | 缓存、日志、长度、可分享性都不同 |
| 状态码大类 | 4xx 你错、5xx 对方错 |
| 401 vs 403 | 不知道你是谁 vs 知道但没权限 |
| 重试条件 | 超时/429/5xx 可重试,4xx 不重试 |
| 非幂等重试 | 先确认结果,或使用幂等键 |
| 排查顺序 | 状态码 → Content-Type → 响应体 |
| 动手验证 | curl -i 刷出四段,-v 看请求头,-X POST 试方法不匹配 |
下一章
方法和状态码是"信封上的字",下一章拆开信封看内容:请求头里到底有哪些必填项、Content-Type 写错会怎样、JSON 有哪几种类型、为什么中文会变成 \u4f60\u597d。