GolangRESTAPI返回码设计规范

编程并不是一个机械性的工作，而是需要有思考，有创新的工作，语法是固定的，但解决问题的思路则是依靠人的思维，这就需要我们坚持学习和更新自己的知识。今天golang学习网就整理分享《Golang REST API返回码设计与状态码规范》，文章讲解的知识点主要包括，如果你对Golang方面的知识点感兴趣，就不要错过golang学习网，在这可以对大家的知识积累有所帮助，助力开发能力的提升。

应使用201而非200创建资源成功时；400用于客户端参数错误，500仅限服务端不可预期故障；需封装统一响应结构，区分httpCode与业务code；panic须用中间件recover并返回标准错误响应。

HTTP 状态码该用 200 还是 201？什么时候必须用 400 而不是 500

REST API 的状态码不是装饰，而是客户端理解响应性质的第一依据。Go 中用 http.StatusOK、http.StatusCreated 等常量写死返回码，比硬写数字更安全，也避免语义错位。

常见误用：创建资源成功却返回 200（应为 201）；参数校验失败返回 500（应为 400）；未登录时返回 404（应为 401 或 403，取决于是否暴露资源存在性）。

• 200：通用成功，适用于 GET、PUT、DELETE 成功且无新资源生成
• 201：POST 创建成功，且响应体中应含 Location 头指向新资源 URI
• 204：DELETE 或 PUT 成功但无响应体（如删除后不返回任何 JSON）
• 400：客户端数据错误（JSON 格式错、字段类型不符、必填字段缺失）
• 401：认证失败（token 缺失、过期、签名无效），需返回 WWW-Authenticate 头
• 403：认证通过但权限不足（如普通用户调管理员接口）
• 404：资源不存在，且服务端确认该路径/ID 不合法（注意：不要用它隐藏“无权访问”）
• 422：语义验证失败（如 email 格式正确但已被注册），适合配合 JSON Schema 或自定义规则校验
• 500：仅当服务端 panic、DB 连接崩、磁盘满等不可预期错误才用；其他如依赖服务超时建议用 503

要不要封装统一的 JSON 响应结构？字段怎么取名

Go 的 HTTP handler 里直接 json.NewEncoder(w).Encode(...) 很快，但缺乏一致性。建议封装一个基础响应结构，避免每个 handler 都重复写 code、message、data。

关键点：不要叫 status（易与 HTTP 状态码混淆），推荐用 code 表业务码，httpCode 表 HTTP 状态码；message 必须是面向前端/调用方的提示，不能是日志级错误堆栈；data 字段在失败时设为 null，不要省略。

type Response struct {
    Code    int         `json:"code"`
    Message string      `json:"message"`
    Data    interface{} `json:"data,omitempty"`
}

func WriteSuccess(w http.ResponseWriter, data interface{}) {
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(http.StatusOK)
    json.NewEncoder(w).Encode(Response{Code: 0, Message: "success", Data: data})
}

func WriteError(w http.ResponseWriter, httpCode, bizCode int, msg string) {
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(httpCode)
    json.NewEncoder(w).Encode(Response{Code: bizCode, Message: msg, Data: nil})
}

业务错误码（bizCode）怎么设计才不和 HTTP 码冲突又便于前端处理

HTTP 状态码只表达“通信层/协议层”结果，业务逻辑错误（如“余额不足”、“订单已取消”）必须靠自定义 code 字段传递。它和 HTTP 码正交：比如支付失败，HTTP 仍返回 400，但 code 是 1001；数据库异常导致下单失败，HTTP 返回 500，code 可设为 5001。

推荐分段设计：1xxx 表参数/输入错误，2xxx 表业务规则拒绝，3xxx 表资源状态冲突（如并发修改），5xxx 表系统级失败。所有码需集中定义在 const 块或枚举文件中，禁止散落在 handler 里 magic number。

• 避免用 0 表示失败（容易被前端忽略判断）
• 不要把数据库错误码（如 MySQL 1062）直接透传给前端
• 敏感信息（如“密码错误次数已达上限”）需脱敏，前端看到的 message 应和日志中的 detail 分离
• 前端可通过 code 做精确分支，比如 code === 2001 弹支付失败页，code === 2002 跳余额充值页

中间件里如何统一拦截 panic 并转成标准错误响应

Go HTTP server 遇到 panic 默认会返回 500 + 空白页，既不友好也不符合规范。必须用中间件 recover，并主动写入标准错误响应。

注意：recover 只捕获当前 goroutine 的 panic，若 handler 启了新 goroutine（如 go fn()），需在子 goroutine 内单独 recover；日志中必须保留完整 stack trace，但响应体绝不暴露。

func Recovery() gin.HandlerFunc {
    return func(c *gin.Context) {
        defer func() {
            if err := recover(); err != nil {
                const msg = "internal server error"
                log.Printf("PANIC: %+v\n%s", err, debug.Stack())
                c.AbortWithStatusJSON(http.StatusInternalServerError, Response{
                    Code:    5000,
                    Message: msg,
                    Data:    nil,
                })
            }
        }()
        c.Next()
    }
}

真正难的是区分“可预期错误”和“panic”。比如数据库查询返回 sql.ErrNoRows 是正常流程，不应 panic；而 nil pointer dereference 才是必须 recover 的。别把业务错误兜底全扔给 recovery 中间件。

今天关于《GolangRESTAPI返回码设计规范》的内容就介绍到这里了，是不是学起来一目了然！想要了解更多关于的内容请关注golang学习网公众号！