定义统一错误类型AppError并结合中间件捕获、日志记录与响应格式化，通过Wrap函数将HandlerFunc转为http.HandlerFunc，在返回错误时统一输出JSON格式，同时使用zap等库结构化记录上下文信息，生产环境隐藏敏感细节，确保所有错误走统一处理通道，提升可维护性与用户体验。
在Go项目中实现统一错误处理策略，关键是通过集中化、结构化和可追溯的方式管理错误，提升代码可维护性和用户体验。核心思路是定义统一的错误类型、使用中间件或拦截机制捕获错误，并结合日志记录与响应格式化。
定义统一的错误类型
使用自定义错误结构体，包含状态码、消息、错误级别等字段，便于后续处理。
type AppError struct {
Code int <font color="#888">// 业务或HTTP状态码</font>
Message string <font color="#888">// 用户可读信息</font>
Detail string <font color="#888">// 内部详细信息（如调试用）</font>
Err error <font color="#888">// 原始错误，用于日志追溯</font>
}
func (e *AppError) Error() string {
if e.Err != nil {
return e.Message + ": " + e.Err.Error()
}
return e.Message
}
构造快捷函数方便创建不同级别的错误：
func NewBadRequest(msg string, err error) *AppError {
return &AppError{Code: 400, Message: msg, Err: err}
}
func NewInternalError(err error) *AppError {
return &AppError{Code: 500, Message: "系统内部错误", Detail: err.Error(), Err: err}
}
在HTTP服务中使用中间件统一捕获
对于Web应用，可通过中间件拦截处理器中的panic和错误返回，统一输出格式。
立即学习“go语言免费学习笔记（深入）”；
type HandlerFunc func(w http.ResponseWriter, r *http.Request) *AppError包装标准handler：
将返回*AppError的函数转为http.HandlerFunc，自动处理成功与失败响应。
func Wrap(h HandlerFunc) http.HandlerFunc {
return func(w http.ResponseWriter, r *http.Request) {
if err := h(w, r); err != nil {
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(err.Code)
json.NewEncoder(w).Encode(map[string]interface{}{
"code": err.Code,
"message": err.Message,
})
log.Printf("error: %v", err)
}
}
}
使用示例：
http.HandleFunc("/api/user", Wrap(func(w http.ResponseWriter, r *http.Request) *AppError {
if r.Method != "GET" {
return NewBadRequest("仅支持GET请求", nil)
}
// ...业务逻辑
return nil <font color="#888">// 表示无错误</font>
}))
结合日志与错误追踪
统一记录错误日志，建议包含时间、路径、用户标识（如有）、错误堆栈等上下文信息。
- 使用第三方库如
zap或logrus结构化输出日志 - 对严重错误触发告警（邮件、钉钉、Sentry等）
- 开发环境可返回详细错误，生产环境隐藏敏感细节
例如：
if err != nil {
logger.Error("user query failed",
zap.String("path", r.URL.Path),
zap.String("uid", getUserID(r)),
zap.Error(err.Err))
return NewInternalError(nil) <font color="#888">// 不暴露内部细节给前端</font>
}
基本上就这些。通过结构体封装错误、中间件统一响应、日志集中记录，就能在Golang项目中建立起清晰可控的错误处理体系。关键是避免裸写fmt.Errorf和panic，让所有错误都走统一通道。不复杂但容易忽略。
