Golang统一错误处理技巧分享

在Go语言Web服务开发中，统一错误处理至关重要，它能显著提升代码可维护性、增强API的稳定性，并方便客户端理解错误。本文分享一种简洁有效的Golang统一错误处理技巧，核心在于定义统一的错误类型`AppError`，包含状态码和消息，并通过中间件`ErrorHandler`集中处理所有错误。通过自定义`HandlerFunc`返回error，由中间件统一输出JSON格式错误响应，避免了在业务逻辑中重复编写错误处理代码，使得错误响应格式统一，方便接入日志系统或监控工具。这种方法尤其适合中小型Web服务，并为后续的错误码国际化、日志追踪等功能扩展奠定基础。

定义统一错误类型AppError并结合中间件实现集中处理，通过自定义HandlerFunc返回error，由ErrorHandler中间件统一输出JSON格式错误响应，避免重复代码，提升可维护性与API稳定性。

在Go语言开发的Web服务中，统一错误处理能提升代码可维护性、增强API的稳定性，并让客户端更容易理解错误原因。直接在每个Handler中写错误处理逻辑会导致重复代码，也不利于全局监控和日志记录。以下是实现统一错误处理的核心思路和实用方法。

定义统一的错误类型

使用自定义错误类型可以标准化错误输出，便于JSON响应和状态码管理。

type AppError struct {
    Code  int        `json:"code"`
    Message string    `json:"message"`
}

这样可以在返回时统一结构：

func (e *AppError) Error() string {
    return e.Message
}

例如：

ErrNotFound = &AppError{Code: 404, Message: "资源未找到"}

使用中间件统一捕获错误

通过包装Handler函数，将返回值设为 error 类型，把错误传递到中间件处理。

type HandlerFunc func(http.ResponseWriter, *http.Request) error

然后定义一个适配器，把自定义的 HandlerFunc 转成标准的 http.HandlerFunc：

func ErrorHandler(h HandlerFunc) http.HandlerFunc {
    return func(w http.ResponseWriter, r *http.Request) {
        if err := h(w, r); err != nil {
            if appErr, ok := err.(*AppError); ok {
                http.Error(w, fmt.Sprintf(`{"code":%d,"message":"%s"}`, appErr.Code, appErr.Message), appErr.Code)
            } else {
                http.Error(w, `{"code":500,"message":"服务器内部错误"}`, 500)
                log.Printf("Internal error: %v", err)
            }
        }
    }
}

这样你的业务Handler就可以返回 error，由中间件统一处理：

func GetUser(w http.ResponseWriter, r *http.Request) error {
    id := r.URL.Query().Get("id")
    if id == "" {
        return &AppError{Code: 400, Message: "缺少用户ID"}
    }
    // 模拟查不到用户
    return ErrNotFound
}

注册路由时使用包装函数

在 main 函数或路由设置中，使用 ErrorHandler 包装你的处理函数：

http.HandleFunc("/user", ErrorHandler(GetUser))

这样所有错误都会被集中处理，响应格式统一，也方便接入日志系统或监控工具（如 Sentry、Prometheus）。

关键点总结：

• 定义结构化错误类型，包含状态码和消息
• 使用返回 error 的 HandlerFunc 替代原始 http.HandlerFunc
• 通过中间件拦截错误并输出标准JSON
• 避免在业务逻辑中直接调用 http.Error
• 可扩展支持错误码国际化、日志追踪等

基本上就这些。这种方式简洁有效，适合中小型Web服务，也能为后续扩展打下基础。

今天关于《Golang统一错误处理技巧分享》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！