Golang Web项目如何输出统一error格式_Golang web error返回结构规范

P粉602998670 2025-11-27 00:00:00 次阅读

定义统一的ErrorResponse结构，包含Code、Message和可选Detail字段；2. 封装writeError函数确保所有错误响应格式一致；3. 使用RecoverMiddleware中间件捕获panic并返回标准错误；4. 区分业务错误与系统错误类型，便于前端根据不同Code处理。

在 Golang Web 项目中，统一的 error 返回格式能提升前后端协作效率、增强 API 可读性，并便于前端统一处理错误。实现这一目标的关键是定义清晰的错误响应结构，并在整个项目中强制使用。

1. 定义统一的 Error 响应结构

建议使用 JSON 格式返回错误信息，包含必要的字段：状态码、错误消息、可选的错误码和详情。例如：

type ErrorResponse struct {
    Code    int    `json:"code"`     // HTTP 状态码或业务错误码
    Message string `json:"message"`  // 用户可读的错误描述
    Detail  string `json:"detail,omitempty"` // 可选，用于开发调试
}

这个结构可以满足大多数场景，前端通过 message 展示提示，后端通过 detail 记录日志或排查问题。

2. 封装错误响应函数

在 handler 层避免直接写 JSON 错误，而是封装一个通用函数，确保所有错误输出一致：

func writeError(w http.ResponseWriter, status int, message, detail string) {
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(status)
    errResp := ErrorResponse{
        Code:    status,
        Message: message,
        Detail:  detail,
    }
    json.NewEncoder(w).Encode(errResp)
}

使用示例：

if user == nil {
    writeError(w, http.StatusNotFound, "用户不存在", "user_id not found")
    return
}

3. 结合中间件统一处理 panic 和未捕获错误

使用中间件捕获 handler 中的 panic，防止服务崩溃并返回标准错误：

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: %v\n", err)
                writeError(w, http.StatusInternalServerError, "服务器内部错误", fmt.Sprintf("%v", err))
            }
        }()
        next.ServeHTTP(w, r)
    })
}

将此中间件注册到路由中，即可保障异常情况下的格式统一。