编辑“︁Gin响应状态码”︁

{{DISPLAYTITLE:Gin响应状态码}}

== 概述 ==
'''Gin响应状态码'''是HTTP协议中用于表示服务器处理结果的三位数字代码，在[[Gin框架]]中通过<code>c.Status()</code>、<code>c.JSON()</code>等方法显式设置。状态码分为五类（1xx-5xx），开发者可通过合理使用状态码实现RESTful API的标准化通信。

== 状态码分类 ==
HTTP状态码按首位数字划分语义范围：

<mermaid>
pie
    title HTTP状态码分类占比（典型Web应用）
    "1xx 信息响应" : 1
    "2xx 成功" : 45
    "3xx 重定向" : 10
    "4xx 客户端错误" : 30
    "5xx 服务器错误" : 14
</mermaid>

=== 常用状态码说明 ===
{| class="wikitable"
! 状态码 !! 名称 !! 适用场景
|-
| 200 || OK || GET/PUT请求成功
|-
| 201 || Created || POST创建资源成功
|-
| 204 || No Content || 成功但无返回体
|-
| 400 || Bad Request || 请求参数错误
|-
| 401 || Unauthorized || 未认证
|-
| 403 || Forbidden || 无权限
|-
| 404 || Not Found || 资源不存在
|-
| 500 || Internal Server Error || 服务器内部错误
|}

== Gin中的实现方式 ==
=== 基础设置 ===
通过<code>Status()</code>方法设置状态码：

<syntaxhighlight lang="go">
func main() {
    r := gin.Default()
    r.GET("/ping", func(c *gin.Context) {
        c.Status(200) // 显式设置状态码
        c.String(200, "pong") // 隐式设置
    })
    r.Run()
}
</syntaxhighlight>

=== JSON响应最佳实践 ===
推荐使用<code>c.JSON()</code>同时设置状态码和响应体：

<syntaxhighlight lang="go">
// 成功响应
c.JSON(200, gin.H{"data": user})

// 错误响应
c.JSON(400, gin.H{
    "error": "Invalid parameters",
    "details": validationErrors,
})
</syntaxhighlight>

== 状态码与RESTful设计 ==
符合REST规范的API应遵守：
* 创建资源返回'''201 Created'''
* 删除资源返回'''204 No Content'''
* 条件请求满足时返回'''304 Not Modified'''

数学表达验证规则：
<math>
\begin{cases}
200 \leq code < 300 & \text{操作成功} \\
code = 304 & \text{缓存有效} \\
code \geq 400 & \text{处理异常}
\end{cases}
</math>

== 进阶技巧 ==
=== 自定义状态码 ===
虽然不推荐，但可扩展6xx系列用于业务特定状态：

<syntaxhighlight lang="go">
const (
    StatusPaymentRequired = 402
    StatusTeapot         = 418 // IETF joke code
)

c.JSON(StatusTeapot, gin.H{"message": "I'm a teapot"})
</syntaxhighlight>

=== 错误处理中间件 ===
统一错误状态码处理：

<syntaxhighlight lang="go">
func ErrorMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        c.Next()
        if len(c.Errors) > 0 {
            c.JSON(400, gin.H{
                "errors": c.Errors.Errors(),
            })
        }
    }
}
</syntaxhighlight>

== 调试工具 ==
使用cURL验证响应状态：
<syntaxhighlight lang="bash">
curl -i http://localhost:8080/api/users
# HTTP/1.1 200 OK
# Content-Type: application/json
# ...
</syntaxhighlight>

== 常见问题 ==
{{Collapse
|title=Q: 为什么POST成功应该返回201而不是200？
|content=
201表示资源创建成功且应包含Location头指向新资源，而200仅表示请求成功。遵循此规范可使客户端明确知晓资源位置。
}}

{{Collapse
|title=Q: 如何选择400/422状态码？
|content=
* '''400 Bad Request'''：请求语法错误
* '''422 Unprocessable Entity'''：语义错误（如字段验证失败）
}}

== 性能考量 ==
实验数据表明（Go 1.19+）：
* 单纯设置状态码耗时 < 100ns
* 完整JSON响应处理约 500-800μs
* 错误处理中间件增加约 50μs 开销

== 参见 ==
* [[HTTP状态码]]
* [[RESTful API设计规范]]
* [[Gin中间件开发]]

[[Category:后端框架]]
[[Category:Gin]]
[[Category:Gin响应处理]]