应使用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，不要省略。
立即学习“go语言免费学习笔记（深入）”；
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 中间件。
