2. HTTP 状态码基础：2xx、3xx、4xx、5xx 状态码详解

做接口调试，第一件事就是看懂状态码。

它就像服务器的「表情」——200 是笑脸，5xx 就是崩溃大哭。尤其是权限和超时问题，基本都集中在 401、403 和 504 这三个码上。

我个人习惯，先不看响应体，先瞄一眼状态码。很多时候，码对了，问题就解决了一半。

2.1 2xx 成功家族：一切正常

2xx 意味着服务器接收、理解了请求，并且处理了。最常见的是 200，但别忽略其他几个。

2.2 3xx 重定向家族：换个地方找我

3xx 表示服务器说「你要的东西不在这，去别处看看」。接口调试里，最常见的坑是 302。

• 301 Moved Permanently：资源永久迁移了。下次直接用新 URL。
• 302 Found：临时跳转。我遇到过接口文档写的 URL 是旧的，服务器返回 302 跳到了新地址，但客户端没 follow 重定向，导致报错。
• 304 Not Modified：资源没变化，直接用本地缓存。这在优化性能时很有用。

嗯，调试时如果看到 3xx，别急着说接口坏了，先检查一下请求 URL 是不是对的。

2.3 4xx 客户端错误家族：我的锅？不，是你的锅

4xx 表示你发的请求有问题。权限问题基本上都藏在这。

401 Unauthorized：你没登录，或者登录过期了

401 的意思是「你是谁？我不认识你」。服务器压根儿不知道你的身份。常见的两种情况：

• 没带 ：请求头里没有 Authorization 字段。
• 过期：时间戳超了，或者签名不对。

调试方法：先检查请求头里有没有 。有的话，把 拿到 JWT 解码器里看一眼过期时间。

403 Forbidden：你有身份，但没权限

403 的意思是「我知道你是谁，但你不配看这个资源」。和 401 的关键区别就是：

• 401：认证失败（没登录）。
• 403：认证成功但授权失败（权限不足）。

调试 403 时，我建议先看这几样东西：

1. 用户角色或权限组有没有对应接口的访问权限。
2. 资源所属部门（比如只能看自己部门的订单）。
3. IP 白名单或黑名单限制。

其他常见 4xx

2.4 5xx 服务器错误家族：服务器炸了

5xx 表示你的请求没错，但服务器内部出了毛病。超时问题基本都归 504 管。

504 Gateway Timeout：上游响应超时

这个是今天的重点之一。504 出现在网关（Nginx、API Gateway）上。网关把请求转发给后端服务，等了 N 秒没收到回复，索性返回 504。

为什么会这样？

• 后端服务处理太慢，超过了网关的超时设置（通常是 5s、10s 或 30s）。
• 后端服务挂了，连接不上。
• 数据库查询太慢，比如全表扫描、死锁。
• 第三方 API 调用卡住了。

调试思路：

1. 先确认是哪个环节超时。看网关日志里的 upstream 响应时间。
2. 用 curl -w "@time.txt" 或类似工具测试后端接口的直接响应时间。
3. 如果是数据库慢查询，打开慢查询日志，看看耗时长的 SQL。
4. 检查网关的超时设置（proxy_read_timeout、proxy_connect_timeout）。

其他常见 5xx

2.5 知识框架：状态码调试地图

下面这张图总结了本章的核心逻辑——从收到响应码开始，如何快速定位问题方向。你想想看，以后碰到任何状态码，都可以对照这张图走一遍流程。

2.6 小结：调试时的快速对照表

最后，我整理了一个快速对照表。调试时直接拿来用就好。