HTTP

HTTP 状态码完全指南（详解版）

一篇面向 Web / 后端 / 前端 / GIS Web 应用开发者 的 HTTP 状态码系统性参考文章。

一、什么是 HTTP 状态码

HTTP 状态码（HTTP Status Code） 是服务器在响应客户端（浏览器、APP、程序）请求时，返回的一个 三位数字，用于说明：

👉 这次请求发生了什么、结果如何、是否需要进一步操作

HTTP 状态码是 HTTP 协议语义的核心组成部分，对于：

  • 前后端接口设计
  • RESTful API 规范
  • 错误处理与调试
  • 网络性能与安全分析

都具有非常重要的意义。

二、HTTP 状态码的五大类

HTTP 状态码按照 首位数字 分为五大类：

分类 范围 含义
1xx 100–199 信息性响应（请求已接收）
2xx 200–299 成功（请求已成功处理）
3xx 300–399 重定向（需要进一步操作）
4xx 400–499 客户端错误
5xx 500–599 服务器错误

三、1xx：信息性状态码（Informational）

表示请求已被接收，正在处理，很少在业务代码中直接使用。

100 Continue

  • 含义：客户端可以继续发送请求体
  • 场景：大文件上传前的确认机制

101 Switching Protocols

  • 含义：服务器同意切换协议
  • 场景：HTTP → WebSocket

四、2xx：成功状态码（Success）

最重要、最常用的一类状态码，表示请求被正确处理。

200 OK

  • 含义：请求成功

  • 场景：

    • GET 查询成功
    • PUT / PATCH 更新成功
GET /api/fields/123
HTTP/1.1 200 OK

201 Created

  • 含义：资源创建成功
  • 场景：POST 新建资源
  • 建议：返回新资源的 URL
POST /api/fields
HTTP/1.1 201 Created
Location: /api/fields/456

202 Accepted

  • 含义：请求已接收，但尚未处理完成

  • 场景：

    • 异步任务
    • 后台计算（如 GIS 插值、模型分析）

204 No Content

  • 含义：请求成功，但无返回内容

  • 场景：

    • 删除成功
    • 仅触发动作的接口
DELETE /api/fields/123
HTTP/1.1 204 No Content

五、3xx：重定向状态码（Redirection）

表示资源位置发生变化，需要客户端采取进一步操作。

301 Moved Permanently

  • 含义：永久重定向

  • 场景：

    • 域名迁移
    • SEO 优化

302 Found

  • 含义：临时重定向（历史遗留）
  • 注意：可能被浏览器当作 GET 请求处理

303 See Other

  • 含义：使用 GET 访问另一个 URI
  • 场景：POST 后跳转页面

304 Not Modified

  • 含义：资源未修改

  • 场景：

    • 浏览器缓存
    • ETag / If-Modified-Since

六、4xx：客户端错误（Client Error）

表示问题出在客户端请求本身。

400 Bad Request

  • 含义：请求格式错误

  • 常见原因：

    • JSON 语法错误
    • 参数缺失

401 Unauthorized

  • 含义：未认证

  • 特点：

    • 需要登录
    • 通常配合 WWW-Authenticate

⚠️ 注意：401 ≠ 权限不足

403 Forbidden

  • 含义：已认证，但无权限

  • 场景：

    • 普通用户访问管理员接口

404 Not Found

  • 含义：资源不存在

  • 场景：

    • URL 错误
    • 资源被删除

405 Method Not Allowed

  • 含义：请求方法不被允许
  • 示例：
POST /api/fields/123
HTTP/1.1 405 Method Not Allowed
Allow: GET, PUT

409 Conflict

  • 含义：资源冲突

  • 场景：

    • 重复创建
    • 乐观锁冲突

422 Unprocessable Entity

  • 含义：语义正确，但业务校验失败

  • 场景：

    • 表单校验
    • 数据规则不满足

七、5xx：服务器错误（Server Error）

表示服务器在处理请求时发生异常。

500 Internal Server Error

  • 含义：服务器内部错误

  • 原因：

    • 未捕获异常
    • 代码 Bug

502 Bad Gateway

  • 含义：上游服务器返回无效响应

  • 场景：

    • 反向代理
    • 微服务调用失败

503 Service Unavailable

  • 含义：服务暂不可用

  • 场景：

    • 服务维护
    • 系统过载

504 Gateway Timeout

  • 含义：上游服务超时

  • 场景：

    • GIS 大规模计算
    • 数据库响应过慢

八、RESTful API 状态码设计建议

1️⃣ 成功不要只用 200

场景 推荐状态码
创建资源 201
删除成功 204
异步处理 202

2️⃣ 错误状态码要“语义准确”

错误场景 正确做法
未登录 401
无权限 403
参数错误 400 / 422
资源不存在 404

3️⃣ 状态码 + 错误信息结构示例

{
  "code": 422,
  "message": "Validation failed",
  "details": {
    "area": "must be greater than 0"
  }
}

九、常见误区总结

❌ 所有错误都返回 200

❌ 用 500 表示业务校验失败

❌ 401 和 403 混用

❌ 前端只判断 code，不看 HTTP 状态码

十、结语

HTTP 状态码不仅是 网络协议的一部分，更是 接口设计质量的重要体现。

一个设计良好的接口，应该做到：

  • 状态码语义清晰
  • 前后端理解一致
  • 错误可定位、可处理