Go Web接口错误如何返回_Go RESTful错误响应规范

必须自定义结构化错误响应体，统一状态码、字段命名与语义，使用ErrorResponse结构体（含code、message、details），封装writeError函数确保Content-Type、WriteHeader顺序及Details安全，并通过中间件recover panic转为标准错误响应。

go Web 接口返回错误时，http.Error 或裸 WriteHeader + Write 无法满足 restful 错误响应的可读性、一致性与客户端解析需求。必须自定义结构化错误响应体，并统一状态码、字段命名和语义。

定义标准错误响应结构体

RESTful 错误响应应包含机器可读的 code（业务错误码）、人类可读的 message、可选的 details（如字段校验失败信息）以及符合 HTTP 语义的状态码。避免用字符串拼接或 map 直接序列化。

推荐定义如下结构：

type ErrorResponse struct {     Code    int    `json:"code"`     Message string `json:"message"`     Details any    `json:"details,omitempty"` }

注意：Code 是业务错误码（如 1001 表示参数缺失），不是 HTTP 状态码；HTTP 状态码由 http.ResponseWriter.WriteHeader 单独设置。

常见错误：把 http.StatusUnprocessableEntity 直接赋给结构体的 Code 字段，导致前端混淆业务码和协议码。

在 handler 中统一写入错误响应

不要在每个 handler 里重复 json.Marshal + WriteHeader + Write。封装一个 writeError 工具函数，确保 Content-Type、状态码、JSON 序列化行为一致。

关键点：

• 始终显式设置 w.Header().Set("Content-Type", "application/json; charset=utf-8")
• 先调用 w.WriteHeader(statusCode)，再写 body；顺序颠倒会导致状态码被忽略
• 对 Details 字段做 nil 判断，避免输出 "details": NULL 或 panic

示例：

func writeError(w http.ResponseWriter, statusCode int, code int, message string, details any) {     w.Header().Set("Content-Type", "application/json; charset=utf-8")     w.WriteHeader(statusCode)     json.NewEncoder(w).Encode(ErrorResponse{         Code:    code,         Message: message,         Details: details,     }) }  // 使用 writeError(w, http.StatusbadRequest, 1002, "email format invalid", map[string]string{"email": "must contain @"})

区分 HTTP 状态码与业务错误码的映射逻辑

HTTP 状态码反映请求/响应层面的协议语义（如 400 Bad Request、401 Unauthorized、404 Not Found），而业务错误码用于后端服务间或前端埋点归因。二者不可混用，但需有合理映射关系。

例如：

• 参数校验失败 → http.StatusBadRequest（400） + 业务码 1001
• 资源不存在 → http.StatusNotFound（404） + 业务码 2001
• 权限不足 → http.StatusForbidden（403） + 业务码 3001
• 内部服务异常 → http.StatusInternalServerError（500） + 业务码 5001

避免把所有错误都返回 500，这会让前端无法区分是用户输错还是系统挂了。

中间件中捕获 panic 并转为标准错误响应

Go HTTP server 默认 panic 会返回空白 500 响应，无任何错误上下文。应在顶层中间件中 recover 并转换为 ErrorResponse。

注意：

• recover 后需手动设置 http.StatusInternalServerError
• 日志中必须记录 panic stack，否则无法定位问题
• 不要将敏感信息（如数据库连接串、路径）直接暴露在 message 中

示例中间件片段：

func recoverMiddleware(next http.Handler) http.Handler {     return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {         defer func() {             if err := recover(); err != nil {                 log.Printf("PANIC in %s %s: %+v", r.Method, r.URL.Path, err)                 writeError(w, http.StatusInternalServerError, 5001, "internal error", nil)             }         }()         next.ServeHTTP(w, r)     }) }

真正难处理的是异步 goroutine 中的 panic —— 它不会被这个中间件捕获，需要单独加 recover 或改用带上下文的同步调用。