2、HTTP状态码概述：HTTP状态码分类（1xx-5xx）、常见状态码含义、在Web服务中的角色

HTTP状态码是服务器对客户端请求的响应标识，三位数字编码承载了请求处理结果的核心语义。在Go Web服务开发中，正确选择与返回状态码，是构建可维护、可调试API的基础能力。本章系统梳理状态码分类体系、常见状态码含义及其在Web服务中的角色定位。

2.1 状态码分类体系（1xx-5xx）

HTTP/1.1协议将状态码按首位数字划分为五大类别，每一类代表一种响应性质：

2.2 常见状态码含义详解

以下是在Web服务开发中最高频出现的状态码，按分类逐一说明其语义与使用约束：

2xx 成功类

• 200 OK — 标准成功响应，GET请求查询成功、POST请求同步处理完成时使用。
• 201 Created — 资源创建成功，通常配合 Location 头部返回新资源URI。
• 204 No Content — 请求成功但无返回体，常用于DELETE操作或批量更新。
• 206 Partial Content — 范围请求成功，支持断点续传与分片下载。

3xx 重定向类

• 301 Moved Permanently — 资源永久迁移，搜索引擎会更新索引。
• 302 Found — 临时重定向，后续请求仍使用原URI。
• 304 Not Modified — 条件请求未变更，配合 ETag 或 Last-Modified 实现缓存验证。
• 307 Temporary Redirect — 临时重定向，保证请求方法不变（POST不会变成GET）。

4xx 客户端错误类

• 400 Bad Request — 通用请求格式错误，如JSON解析失败、必填字段缺失。
• 401 Unauthorized — 未提供有效认证凭证，需引导客户端重新登录。
• 403 Forbidden — 已认证但无权限，不应暴露资源是否存在。
• 404 Not Found — 资源不存在，注意与410 Gone（资源已永久删除）区分。
• 405 Method Not Allowed — 请求方法不被允许，响应应包含 Allow 头部。
• 409 Conflict — 资源当前状态与请求冲突，如版本号不匹配、唯一索引重复。
• 422 Unprocessable Entity — 语义错误，请求体格式正确但业务逻辑校验失败。
• 429 Too Many Requests — 速率限制触发，应包含 Retry-After 头部。

5xx 服务器错误类

• 500 Internal Server Error — 通用服务器内部错误，Go中未捕获的panic默认返回此码。
• 502 Bad Gateway — 上游服务返回无效响应，常见于反向代理场景。
• 503 Service Unavailable — 服务暂时过载或维护中，建议包含 Retry-After。
• 504 Gateway Timeout — 上游服务超时未响应。

2.3 状态码在Web服务中的角色

状态码在Web服务中承担三个核心角色，直接影响API的可观测性与客户端体验：

1. 协议语义契约 — 状态码是HTTP协议层面的标准化信号，客户端（浏览器、移动端、其他服务）依赖状态码决定下一步行为。例如，收到401自动弹出登录页，收到429自动退避重试。
2. 错误分类与监控 — 在服务端，状态码是监控与告警的核心指标。4xx比例突增通常意味着客户端兼容性问题或攻击行为；5xx比例突增则触发即时告警，代表服务稳定性受损。
3. API设计规范 — 良好的状态码映射能显著降低客户端对接成本。例如，统一使用422表示校验错误，而非混用400/422/500，让客户端错误处理逻辑更简洁。

2.4 状态码选择决策流程

以下SVG图展示了在Go Web服务中，从接收到请求到返回响应时，状态码选择的决策路径：

2.5 常见状态码速查表

以下表格汇总了Go Web服务开发中最常用的20个状态码，包含语义、HTTP方法适用性与典型返回场景：

2.6 状态码在Go Web服务中的映射原则

在Go Web服务中，将业务错误映射为HTTP状态码时，应遵循以下三条核心原则：

• 语义精确原则 — 优先使用最精确的状态码。例如，资源不存在用404而非400；权限不足用403而非401。精确的状态码让客户端无需解析响应体即可理解错误性质。
• 安全最小化原则 — 在认证与授权场景中，避免暴露过多信息。例如，用户不存在时返回“401 Unauthorized”而非“404 Not Found”，防止攻击者通过状态码枚举有效用户。
• 一致性原则 — 同一业务错误在整个服务中映射为同一状态码。例如，所有校验错误统一使用422，而非在部分接口中使用400、部分使用422。一致性降低客户端对接成本。

// 推荐：使用常量
http.Error(w, "resource not found", http.StatusNotFound)

// 不推荐：硬编码数字
http.Error(w, "resource not found", 404)

2.7 状态码与错误响应体结构

状态码仅表示请求处理结果的大类，详细的错误信息应通过响应体传递。以下SVG图展示了标准错误响应体的推荐结构：

type ErrorResponse struct {
    Code    string   `json:"code"`
    Message string   `json:"message"`
    Details []string `json:"details,omitempty"`
    TraceID string   `json:"trace_id,omitempty"`
}

2.8 本章小结