定义统一错误响应格式，使用中间件recover panic，结合自定义错误类型与validator库校验，实现分层错误处理，确保API健壮性与一致性。
在构建 RESTful API 时，错误处理是保障接口健壮性和用户体验的关键环节。Golang 虽然没有异常机制，但通过返回 error 类型和良好的结构设计，可以实现清晰、统一的错误响应。以下是几种常见且实用的 Golang API 错误处理方法。
定义统一的错误响应格式
为了让前端或其他调用方更容易理解错误信息，应定义一致的 JSON 响应结构。
例如：
{
"error": {
"code": "invalid_request",
"message": "请求参数不合法",
"details": "缺少必填字段 email"
},
"status": 400
}
对应 Go 结构体：
立即学习“go语言免费学习笔记（深入）”；
type Error struct {
Code string `json:"code"`
Message string `json:"message"`
Details string `json:"details,omitempty"`
}
type ErrorResponse struct {
Error Error `json:"error"`
Status int `json:"status"`
}
在返回错误时，使用 json.NewEncoder(w).Encode() 输出标准格式，确保所有错误都遵循这一约定。
使用中间件集中处理 panic 和未捕获错误
Go 的 HTTP 服务一旦发生 panic，可能导致整个服务崩溃。使用中间件 recover 请求中的 panic，并返回 500 错误。
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", err)
w.WriteHeader(500)
json.NewEncoder(w).Encode(ErrorResponse{
Error: Error{
Code: "internal_error",
Message: "服务器内部错误",
},
Status: 500,
})
}
}()
next.ServeHTTP(w, r)
})
}
将此中间件包裹在路由处理函数外层，可防止程序因意外崩溃。
自定义错误类型与错误判断
在业务逻辑中，常需要区分不同类型的错误（如数据库未找到、权限不足等）。可通过定义自定义错误类型提升控制精度。
type AppError struct {
Code string
Message string
Status int
}
func (e AppError) Error() string {
return e.Message
}
在 handler 中判断是否为 AppError，并据此返回对应状态码：
if err != nil {
var appErr AppError
if errors.As(err, &appErr) {
w.WriteHeader(appErr.Status)
json.NewEncoder(w).Encode(ErrorResponse{
Error: Error{Code: appErr.Code, Message: appErr.Message},
Status: appErr.Status,
})
return
}
// 默认 500 错误
w.WriteHeader(500)
json.NewEncoder(w).Encode(ErrorResponse{
Error: Error{Code: "internal_error", Message: "未知错误"},
Status: 500,
})
}
结合 validator 库提前拦截无效请求
使用如 go-playground/validator 等库对输入进行校验，可在进入业务逻辑前就返回错误。
type CreateUserRequest struct {
Email string `json:"email" validate:"required,email"`
Age int `json:"age" validate:"gte=0,lte=120"`
}
// 校验示例
if err := validate.Struct(req); err != nil {
var ve validator.ValidationErrors
if errors.As(err, &ve) {
w.WriteHeader(400)
json.NewEncoder(w).Encode(ErrorResponse{
Error: Error{
Code: "validation_failed",
Message: "参数校验失败",
Details: formatValidationErrors(ve),
},
Status: 400,
})
return
}
}
提前校验能减少无效处理流程，提升 API 可靠性。
基本上就这些。关键是统一格式、分层处理、避免 panic 泄露，并让错误信息对调用方有意义。不复杂但容易忽略细节。合理使用 error 封装和中间件，能让 API 更加稳定和易维护。
