1. 从一次线上故障说起为什么状态码值得单独拎出来总结前阵子帮一个朋友排查他们新上线的接口问题现象很怪前端页面一直转圈控制台里偶尔蹦出一个200偶尔又是一个304但用户看到的就是数据没更新。他第一反应是后端挂了查了服务日志一切正常数据库连接池也稳得很。最后定位下来问题出在一个很多人都会忽略的地方——缓存协商。浏览器发了带If-None-Match的请求服务端老老实实回了304 Not Modified但前端代码里只判断了status 200才去解析响应体304的响应体是空的于是解析逻辑直接抛错页面就卡住了。这个案例特别典型。HTTP 状态码这东西几乎每个做网络、做浏览器、做前端的人都知道但真正能把三位数字背后的语义、缓存机制、重定向链路、错误边界讲清楚的人并不多。大多数人停留在200 成功、404 找不到、500 服务器错误这三板斧上一旦遇到301和302的区别、304的触发条件、401和403的边界、502和504的排查方向就开始凭感觉猜。这篇总结就是冲着这个痛点来的。我会把状态码按语义分类拆开讲每一类里挑出真正会在开发和运维中碰到的成员讲清楚它的触发条件、典型场景、排查思路和容易踩的坑。不管你是刚接触 HTTP 的新手还是写了几年业务代码想补一补底层认知的老手都能从里面找到能直接用的东西。尤其是前端同学很多玄学 bug的根子其实就在状态码的语义理解上。2. 状态码的五大家族先建立分类直觉再抠细节在逐个拆解之前得先建立一个整体框架。HTTP 状态码是三位数字第一位数字决定了它属于哪个家族这个分类不是随便定的它直接对应了请求处理的不同阶段和责任方。首位数字类别核心含义责任方倾向1xx信息性请求已收到继续处理协议层/服务端2xx成功请求被成功接收、理解、接受服务端3xx重定向需要进一步动作才能完成请求客户端/浏览器4xx客户端错误请求有语法错误或无法完成客户端5xx服务端错误服务器处理请求失败服务端这个分类最大的价值在于快速定位责任方。看到 4xx先怀疑请求本身——参数、路径、鉴权、请求头看到 5xx先怀疑服务端——代码异常、依赖超时、资源耗尽。这个直觉能帮你省下大量排查时间。2.1 为什么第一位数字比后两位更重要很多人记状态码是死记硬背404是找不到403是禁止访问背完就忘。但如果你理解了分类逻辑即使碰到一个没见过的状态码比如429你也能立刻判断这是 4xx是客户端侧的问题再看语义是Too Many Requests那就是请求太频繁被限流了。反过来5035xx 家族服务端暂时不可用多半是过载或维护。我个人的经验是先记家族再记成员。家族决定了你的第一反应方向成员决定了具体动作。这个顺序比按数字大小背要高效得多。2.2 状态码不是孤立的它和请求方法、响应头强绑定有个容易被忽略的点状态码的语义往往要结合请求方法和响应头一起看。比如同样是405 Method Not Allowed它一定伴随着一个Allow响应头告诉你这个资源支持哪些方法。再比如304它必须和ETag或Last-Modified配合才有意义单独看一个304你根本不知道缓存是怎么协商的。所以后面讲每个状态码时我会尽量把相关的请求头、响应头一起带上这样你看到的不只是一个数字而是一整套交互过程。3. 2xx 成功家族200 不是唯一答案201、204、206 各有各的用武之地2xx 家族看起来最简单其实坑不少。很多前端代码只认200结果遇到201、204、206就懵了。这一章把几个高频成员讲透。3.1 200 OK最熟悉但也最容易被滥用200表示请求成功响应体里带着资源。它是用得最多的状态码但也是最容易被滥用的。我见过不少接口无论业务成功还是失败一律返回200然后在响应体里塞一个{ code: 500, msg: xxx }。这种做法在早期前后端不分离的时代很常见但在 RESTful 风格和现代前端框架下它会让HTTP 层的语义完全失效。为什么这么说因为浏览器、CDN、网关、监控系统都是靠状态码来判断请求结果的。你全返回200监控系统就看不到错误率CDN 可能缓存了本该报错的响应前端的统一错误拦截器也失效了。正确的做法是业务错误用 4xx系统错误用 5xx成功才用 2xx。响应体里的业务码可以作为补充但不应该替代 HTTP 状态码。提示如果你接手的老系统就是万物皆 200别急着全改先在网关层做一层状态码映射把明显的错误场景纠正过来再逐步推进业务代码改造。3.2 201 Created 与 204 No Content写操作的两个标准答案201用在资源创建成功的场景典型就是 POST 新建一条记录。它通常会带一个Location响应头指向新创建资源的 URL。这个细节很多人不知道但对 API 设计很有用——客户端拿到Location就能直接跳转或引用新资源不用再拼一次 URL。204表示请求成功但没有响应体。它最常见的场景是 DELETE 删除成功或者 PUT 更新成功但不需要返回内容。这里有个实操坑有些前端请求库在收到204时会尝试JSON.parse空响应体直接报错。所以如果你的接口会返回204前端一定要做判断别无条件解析。// 前端处理 204 的正确姿势 const res await fetch(/api/user/1, { method: DELETE }); if (res.status 204) { // 没有响应体直接当成功处理 return { success: true }; } if (res.ok) { return await res.json(); }3.3 206 Partial Content断点续传和视频拖动的幕后功臣206是很多人听过但没细究过的状态码。它表示服务端只返回了资源的一部分配合Range请求头使用。你在网页上看视频能随意拖动进度条、下载大文件能断点续传背后就是206在支撑。它的工作流程是这样的客户端发请求时带上Range: bytes0-1023表示只要前 1024 字节服务端如果支持就返回206并在响应头里带上Content-Range: bytes 0-1023/5000告诉客户端这次给了哪一段、总大小是多少。如果服务端不支持 Range就会忽略这个头返回完整的200。排查下载或视频播放问题时如果发现拖动进度条后重新从头加载多半是服务端没正确处理Range头或者 CDN 把206响应给缓存错了。这个点在做媒体类应用时特别值得注意。4. 3xx 重定向家族301、302、303、307、308 的区别一次讲清楚3xx 是状态码里最容易混淆的一族。很多人只知道301 永久、302 临时但 303、307、308 一出来就分不清了。这一章把重定向的语义和方法保持问题讲透这是理解这一族的关键。4.1 重定向的本质客户端要再发一次请求先明确一个概念重定向不是服务端帮你跳转而是服务端告诉客户端你要的资源不在这去另一个地址拿。客户端收到 3xx 后会读取Location响应头然后再发一次请求到新地址。这个过程对用户可能是无感的但网络层面确实发生了两次请求。理解这一点很重要因为它解释了为什么重定向会影响性能——每一次重定向都是一次额外的往返。重定向链越长延迟越高。做性能优化时减少不必要的重定向是一个常被忽略的点。4.2 301 与 308永久重定向但方法处理不同301 Moved Permanently表示资源永久迁移到新地址。浏览器和搜索引擎会记住这个映射下次直接访问新地址。它最典型的场景是域名迁移或URL 结构永久调整。但301有个历史遗留问题很多客户端在收到301后会把 POST 请求改成 GET。这在语义上是不严谨的因为用户明明发的是 POST。为了解决这个问题308 Permanent Redirect被引入它和301一样是永久重定向但严格保持原请求方法。POST 还是 POST不会被降级成 GET。4.3 302、303、307临时重定向的三兄弟302 Found是最早的临时重定向但它的方法处理行为在历史上很混乱不同浏览器实现不一致。于是后来拆出了两个更明确的状态码303 See Other明确要求客户端用GET方法去访问新地址。它常用在 POST 提交后跳转到结果页的场景避免用户刷新时重复提交表单。307 Temporary Redirect明确要求保持原请求方法。POST 提交到新地址还是 POST。302现在基本被当作临时重定向的通用选择但如果你对方法保持有严格要求应该用307或303来表达明确意图。状态码永久/临时方法是否保持典型场景301永久历史上可能变 GET域名迁移、URL 永久调整302临时行为不统一通用临时跳转303临时强制变 GETPOST 后跳转结果页307临时严格保持需要保持方法的临时跳转308永久严格保持需要保持方法的永久跳转4.4 304 Not Modified缓存协商的核心也是前端 bug 高发区304严格来说不算重定向它属于 3xx 但语义是资源没变用你本地的缓存。它的触发条件是客户端发请求时带了If-None-Match对应ETag或If-Modified-Since对应Last-Modified服务端比对后发现资源没变化就返回304不带响应体。这就是文章开头那个 bug 的根源。304的响应体是空的前端如果无脑解析 JSON 就会炸。正确的处理是304时直接使用本地缓存不要尝试解析响应体。// 处理 304 的推荐写法 if (res.status 304) { // 使用缓存数据不要解析 body return getFromCache(url); }还有一个实操经验304在浏览器 DevTools 的 Network 面板里Size 列会显示from disk cache或from memory cache看到这个就说明缓存生效了。如果你在调试接口时发现改了后端代码但前端没更新先检查是不是304在作怪可以在 DevTools 里勾选Disable cache临时绕过。5. 4xx 客户端错误家族从 400 到 429每一个都是排查线索4xx 家族是前端和 API 调试中最常打交道的。它的核心含义是问题出在请求这一侧但具体是参数问题、鉴权问题还是频率问题需要逐个分辨。5.1 400 Bad Request最笼统的你请求有问题400是个兜底的客户端错误表示服务端认为请求本身有问题但没法用更具体的状态码表达。常见原因包括请求体 JSON 格式错误、必填参数缺失、参数类型不对、请求头格式异常。排查400的第一步是看响应体。好的 API 会在响应体里说明具体哪个字段有问题。如果响应体是空的那就得靠抓包对比——把请求的原始报文拿出来逐字段检查。我常用的方法是先用 Postman 或 curl 复现确认是请求构造问题还是服务端校验逻辑问题。注意有些网关在请求体过大或格式非法时也会返回400这时候要看是不是Content-Length和实际 body 长度不一致或者Content-Type没设对。5.2 401 与 403认证和授权的边界别搞混这两个状态码经常被混用但语义完全不同401 Unauthorized未认证。你没提供身份凭证或者凭证无效/过期。它必须带一个WWW-Authenticate响应头告诉客户端该怎么认证。403 Forbidden已认证但无权限。服务端知道你是谁但你没资格访问这个资源。举个生活化的例子401就像你进大楼没刷卡门禁不让你进403就像你刷了卡进了大楼但想进某个机房时发现你的权限不够。这个区别对前端处理很重要。收到401通常应该跳转登录页或刷新 token收到403应该提示无权限而不是傻乎乎地跳登录。我见过不少项目把403也当401处理结果用户明明登录着却被反复踢到登录页体验极差。5.3 404 与 405找不到资源和方法不对404 Not Found是最广为人知的状态码表示资源不存在。但要注意它有时候会被滥用——有些服务端为了安全把403也伪装成404避免暴露资源是否存在。所以排查404时先确认 URL 拼写、路径参数、路由配置再考虑是不是被故意隐藏了。405 Method Not Allowed表示资源存在但你用的 HTTP 方法不对。比如一个只支持 GET 的接口你发了 POST。它一定会带Allow响应头列出支持的方法。看到405直接看Allow头就知道该怎么改了。5.4 429 Too Many Requests限流的标准表达429表示客户端在短时间内发了太多请求被服务端限流了。它通常会带Retry-After响应头告诉你多久之后可以重试。这个状态码在对接第三方 API 时特别常见很多开放平台都用它来做配额控制。处理429的正确姿势是读取Retry-After做退避重试而不是立刻重发。无脑重试只会让情况更糟甚至触发更严格的封禁。前端如果遇到429应该给用户一个友好的提示而不是让请求一直失败。// 处理 429 的退避重试示例 async function requestWithRetry(url, options, maxRetry 3) { for (let i 0; i maxRetry; i) { const res await fetch(url, options); if (res.status ! 429) return res; const retryAfter parseInt(res.headers.get(Retry-After) || 1, 10); await new Promise(r setTimeout(r, retryAfter * 1000)); } throw new Error(请求过于频繁请稍后再试); }6. 5xx 服务端错误家族500、502、503、504 的排查方向完全不同5xx 家族表示问题出在服务端但具体是应用代码、网关、还是上游依赖需要仔细分辨。这一章把几个高频成员和它们的排查路径讲清楚。6.1 500 Internal Server Error应用层异常的通用表达500是最笼统的服务端错误表示服务端处理请求时抛了未预期的异常。它可能是空指针、数据库连接失败、代码逻辑 bug也可能是依赖服务返回了异常数据。排查500的核心是看服务端日志。前端能做的很有限最多是把请求的完整信息URL、参数、请求头、时间戳提供给后端方便定位。有个经验如果500是偶发的多半和并发、资源竞争或某个特定参数有关如果是必现的那基本就是代码逻辑问题复现路径很清晰。6.2 502 与 504网关视角的两个超时/失败这两个状态码经常一起出现但原因不同502 Bad Gateway网关如 Nginx、负载均衡从上游服务器收到了无效响应。可能是上游进程崩了、端口没监听、返回了非法报文。504 Gateway Timeout网关等待上游响应超时。上游还活着但处理太慢超过了网关配置的超时时间。排查方向也不一样。502先看上游服务是否存活、端口是否正常、有没有 OOM 被杀504先看上游服务的处理耗时、有没有慢查询、网关的超时配置是否合理。状态码含义首要排查方向502网关收到无效响应上游进程存活、端口监听、报文合法性504网关等待上游超时上游处理耗时、慢查询、超时配置6.3 503 Service Unavailable过载或维护的标准表达503表示服务端暂时无法处理请求通常是过载或正在维护。它常带Retry-After头告诉客户端多久后重试。这个状态码在服务降级、灰度发布、限流熔断场景中很常用。从运维角度503是一个优雅的错误——它明确告诉调用方我现在不行但等会儿可能行比直接500要友好。做高可用设计时合理使用503配合Retry-After能让客户端做出更聪明的重试决策。7. 状态码在真实项目中的组合玩法与避坑清单前面按家族拆完了这一章讲几个跨状态码的实战话题这些是文档里不会写、但实际项目中一定会碰到的。7.1 缓存链路中的 200、304 与 CDN 行为一个请求经过浏览器缓存、CDN、网关、应用服务每一层都可能对状态码做处理。最典型的问题是CDN 缓存了200响应但源站后来返回404CDN 却还在吐旧的200。这类问题排查起来很头疼因为你在本地怎么测都是对的。我的经验是明确哪些状态码可以被 CDN 缓存。一般来说200、301、304可以缓存4xx、5xx默认不缓存。如果你的接口返回404却被缓存了检查 CDN 的缓存规则把错误状态码排除掉。另外Cache-Control响应头比状态码本身更能决定缓存行为两者要一起看。7.2 前端统一错误拦截器该怎么写现代前端项目基本都会封装一个请求库统一处理状态码。这里有个设计原则按家族分流按成员细化。function handleResponse(res) { if (res.status 200 res.status 300) { return res.status 204 ? null : res.json(); } if (res.status 304) { return getFromCache(res.url); } if (res.status 401) { redirectToLogin(); throw new Error(未登录); } if (res.status 403) { throw new Error(无权限访问); } if (res.status 429) { throw new Error(请求过于频繁请稍后再试); } if (res.status 500) { reportToMonitor(res); throw new Error(服务异常请稍后重试); } throw new Error(请求失败${res.status}); }这个拦截器的关键点是204和304要特殊处理不能无脑解析 body401和403要区分对待5xx要上报监控。这些细节决定了错误处理的健壮性。7.3 那些容易被忽略的边界情况最后列几个我在实际项目中踩过的坑都是和状态码相关的重定向后的状态码用fetch时默认会自动跟随重定向你拿到的最终状态码是最后一跳的。如果想看中间的重定向需要设置redirect: manual。CORS 预检失败跨域请求的 OPTIONS 预检如果失败浏览器可能报一个模糊的错误实际底层可能是403或405。排查时要看 Network 面板里的 OPTIONS 请求。状态码 0这不是标准 HTTP 状态码而是浏览器在请求根本没发出去如网络中断、被拦截时给的一个特殊值。看到status 0先查网络和跨域配置。1xx 的少见场景100 Continue和101 Switching Protocols在日常开发中很少直接接触但做 WebSocket 升级或大文件上传时会碰到知道它们的存在能帮你少走弯路。状态码这套东西说到底是一套约定俗成的沟通语言。服务端用它告诉客户端发生了什么客户端用它决定接下来做什么。把这套语言用准确了前后端协作会顺畅很多排查问题也能少绕很多弯。我自己这些年最大的体会就是别把状态码当成可有可无的装饰它是 HTTP 协议里信息密度最高的部分之一。每次遇到奇怪的线上问题先静下心来看看状态码往往答案就藏在那个三位数字里。