在 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，防止服务崩溃并返回标准错误：

Motiff妙多是一款AI驱动的界面设计工具，定位为“AI时代设计工具”

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)
    })
}

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

4. 区分业务错误与系统错误

实际项目中建议定义常见错误类型，如：

• 参数错误（400）：请求参数缺失或格式错误
• 权限不足（403）：用户无权访问资源
• 资源未找到（404）：ID 对应记录不存在
• 服务器错误（500）：数据库查询失败等

每种错误对应不同的 Code 和 Message，前端可根据 Code 做不同处理，比如跳转登录页或重试。

基本上就这些。只要从结构定义、响应封装、中间件防护三方面入手，就能在 Golang Web 项目中实现清晰、可控、统一的 error 返回规范。