统一错误处理提升Golang Web API可维护性与一致性，含结构化响应、中间件panic捕获、自定义AppError、封装响应函数及日志集成。
在构建 Golang Web API 时，统一错误处理能提升代码可维护性、增强接口一致性，并让前端更容易解析错误信息。通过集中管理错误，你可以避免重复的错误判断和响应逻辑，同时便于记录日志、追踪问题。
定义统一的错误响应格式
为了前后端协作顺畅，所有 API 接口应返回结构一致的错误响应体。通常包含状态码、错误消息和可选的详细信息。
{
"success": false,
"message": "资源未找到",
"error": {
"code": "NOT_FOUND",
"details": "用户ID不存在"
}
}
对应 Go 结构体可以这样定义：
type ErrorResponse struct {
Success bool `json:"success"`
Message string `json:"message"`
Error ErrorDetail `json:"error,omitempty"`
}
type ErrorDetail struct {
Code string `json:"code"`
Details string `json:"details,omitempty"`
}
使用中间件捕获和处理错误
Go 的 net/http 不自带异常机制，但可以通过中间件配合 panic 和 recover 实现全局错误拦截。你也可以在 handler 中主动调用统一响应函数。
立即学习“go语言免费学习笔记（深入）”；
创建一个错误处理中间件：
func ErrorHandler(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 recovered: %v", err)
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(http.StatusInternalServerError)
json.NewEncoder(w).Encode(ErrorResponse{
Success: false,
Message: "服务器内部错误",
Error: ErrorDetail{
Code: "INTERNAL_ERROR",
Details: fmt.Sprintf("%v", err),
},
})
}
}()
next.ServeHTTP(w, r)
})
}
将中间件应用到路由：
mux := http.NewServeMux()
mux.Handle("/api/user/", ErrorHandler(http.HandlerFunc(getUserHandler)))
log.Fatal(http.ListenAndServe(":8080", mux))
自定义错误类型与主动返回错误
除了捕获 panic，你还需要在业务逻辑中主动返回语义清晰的错误。为此可以定义应用级错误类型。
type AppError struct {
Code string
Message string
Err error
}
func (e AppError) Error() string {
return e.Message
}
在 handler 中使用：
func getUserHandler(w http.ResponseWriter, r *http.Request) {
userID := r.URL.Query().Get("id")
if userID == "" {
respondWithError(w, http.StatusBadRequest, "MISSING_USER_ID", "用户ID不能为空")
return
}
user, err := db.GetUser(userID)
if err != nil {
if errors.Is(err, sql.ErrNoRows) {
respondWithError(w, http.StatusNotFound, "USER_NOT_FOUND", "指定用户不存在")
return
}
respondWithError(w, http.StatusInternalServerError, "DB_ERROR", "数据库查询失败")
return
}
respondWithJSON(w, http.StatusOK, map[string]interface{}{
"success": true,
"data": user,
})
}
封装响应函数：
func respondWithError(w http.ResponseWriter, status int, code, message string) {
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(status)
json.NewEncoder(w).Encode(ErrorResponse{
Success: false,
Message: message,
Error: ErrorDetail{
Code: code,
Details: message,
},
})
}
func respondWithJSON(w http.ResponseWriter, status int, payload interface{}) {
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(status)
json.NewEncoder(w).Encode(payload)
}
集成日志与监控
统一错误处理不仅是返回客户端信息，还应记录关键错误用于排查。可以在 respondWithError 或中间件中加入日志输出。
例如使用 zap 或 logrus 记录错误堆栈和请求上下文：
logger.Error("Request failed",
zap.String("method", r.Method),
zap.String("url", r.URL.String()),
zap.String("error_code", code),
zap.Error(appErr.Err))
结合 tracing ID 可进一步提升调试效率。
基本上就这些。通过结构化错误响应、中间件拦截、自定义错误类型和统一响应函数，你能有效管理 Golang Web API 中的所有错误路径。不复杂但容易忽略细节，比如状态码映射和日志上下文。做好了，API 会更健壮、更易维护。
