首页 > Golang > Go教程

GolangRESTAPI错误处理指南

时间：2025-11-03 09:00:53 169浏览收藏

欢迎各位小伙伴来到golang学习网，相聚于此都是缘哈哈哈！今天我给大家带来《Golang REST API错误处理全攻略》，这篇文章主要讲到等等知识，如果你对Golang相关的知识非常感兴趣或者正在自学，都可以关注我，我会持续更新相关文章！当然，有什么建议也欢迎在评论留言提出！一起学习！

定义统一错误响应格式，使用中间件recover panic，结合自定义错误类型与validator库校验，实现分层错误处理，确保API健壮性与一致性。

Golang如何在REST API中处理错误响应_Golang API错误处理方法汇总

在构建 RESTful API 时，错误处理是保障接口健壮性和用户体验的关键环节。Golang 虽然没有异常机制，但通过返回 error 类型和良好的结构设计，可以实现清晰、统一的错误响应。以下是几种常见且实用的 Golang API 错误处理方法。

定义统一的错误响应格式

为了让前端或其他调用方更容易理解错误信息，应定义一致的 JSON 响应结构。

例如：

{
  "error": {
    "code": "invalid_request",
    "message": "请求参数不合法",
    "details": "缺少必填字段 email"
  },
  "status": 400
}

对应 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 更加稳定和易维护。

以上就是《GolangRESTAPI错误处理指南》的详细内容，更多关于golang,错误处理,中间件,RESTAPI,统一响应格式的资料请关注golang学习网公众号！

golang 错误处理中间件 RESTAPI 统一响应格式