Golang API接口错误处理规范与示例-Golang-PHP中文网

Golang API接口错误处理规范与示例

P粉602998670

发布： 2025-10-09 17:11:01

原创

870人浏览过

答案：Go API 错误处理应统一响应格式、使用自定义错误类型区分业务错误、通过中间件捕获 panic，并在校验失败时返回字段级错误信息，确保一致性与可维护性。

golang api接口错误处理规范与示例

在 Go 语言开发 API 接口时，良好的错误处理机制是保障系统健壮性和可维护性的关键。合理的错误设计能让调用方清晰理解问题所在，同时便于日志追踪和监控报警。以下是常见的 Golang API 错误处理规范与实用示例。

统一错误响应格式

API 返回的错误信息应结构一致，方便前端或客户端解析。建议使用 JSON 格式返回错误，并包含状态码、错误消息和可选的详细信息。

定义统一的响应结构：

type ErrorResponse struct {
    Code    int    `json:"code"`
    Message string `json:"message"`
    Detail  string `json:"detail,omitempty"`
}

func writeError(w http.ResponseWriter, code int, message, detail string) {
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(code)
    json.NewEncoder(w).Encode(ErrorResponse{
        Code:    code,
        Message: message,
        Detail:  detail,
    })
}

登录后复制

使用自定义错误类型区分业务错误

Go 的 error 是接口类型，可通过实现自定义错误增强语义。在 API 层，区分系统错误和业务错误有助于精准响应。

立即学习“go语言免费学习笔记（深入）”；

例如定义业务错误类型：

type AppError struct {
    Code    int
    Message string
    Err     error
}

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

// 预定义常见错误
var (
    ErrUserNotFound = &AppError{Code: 404, Message: "用户不存在"}
    ErrInvalidInput = &AppError{Code: 400, Message: "请求参数无效"}
)

登录后复制

在处理函数中判断错误类型并返回对应 HTTP 状态：

易笔AI论文

专业AI论文生成，免费生成论文大纲，在线生成选题/综述/开题报告等论文模板

103

查看详情

func getUserHandler(w http.ResponseWriter, r *http.Request) {
    userID := r.URL.Query().Get("id")
    if userID == "" {
        writeError(w, 400, "缺少用户ID", "query param 'id' is required")
        return
    }

    user, err := userService.Get(userID)
    if err != nil {
        if errors.Is(err, ErrUserNotFound) {
            writeError(w, 404, err.Error(), "")
            return
        }
        // 其他错误视为服务器内部错误
        log.Printf("获取用户失败: %v", err)
        writeError(w, 500, "服务器内部错误", "")
        return
    }

    json.NewEncoder(w).Encode(user)
}

登录后复制

中间件集中处理 panic 和未知错误

为避免因未捕获的 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\n%s", err, debug.Stack())
                writeError(w, 500, "服务器内部错误", "panic occurred")
            }
        }()
        next.ServeHTTP(w, r)
    })
}

登录后复制

将中间件应用于路由：

mux := http.NewServeMux()
mux.HandleFunc("/user", getUserHandler)

log.Fatal(http.ListenAndServe(":8080", RecoverMiddleware(mux)))

登录后复制

验证错误返回具体字段信息

对于表单或 JSON 输入校验失败，应返回具体出错字段，帮助调用方快速定位问题。

扩展 ErrorResponse 支持字段级错误：

type FieldError struct {
    Field   string `json:"field"`
    Reason  string `json:"reason"`
}

type ValidationErrorResponse struct {
    Code    int          `json:"code"`
    Message string       `json:"message"`
    Errors  []FieldError `json:"errors,omitempty"`
}

登录后复制

校验示例：

func createUserHandler(w http.ResponseWriter, r *http.Request) {
    var input struct {
        Name  string `json:"name"`
        Email string `json:"email"`
    }

    if err := json.NewDecoder(r.Body).Decode(&input); err != nil {
        writeError(w, 400, "请求体解析失败", err.Error())
        return
    }

    var fieldErrors []FieldError
    if input.Name == "" {
        fieldErrors = append(fieldErrors, FieldError{Field: "name", Reason: "不能为空"})
    }
    if !strings.Contains(input.Email, "@") {
        fieldErrors = append(fieldErrors, FieldError{Field: "email", Reason: "邮箱格式无效"})
    }

    if len(fieldErrors) > 0 {
        w.Header().Set("Content-Type", "application/json")
        w.WriteHeader(400)
        json.NewEncoder(w).Encode(ValidationErrorResponse{
            Code:    400,
            Message: "输入验证失败",
            Errors:  fieldErrors,
        })
        return
    }

    // 处理创建逻辑...
}

登录后复制

基本上就这些。通过统一格式、自定义错误、中间件防护和字段级反馈，可以让 Go 编写的 API 错误处理更清晰可靠。关键是保持一致性，让所有错误路径都遵循相同模式。

以上就是Golang API接口错误处理规范与示例的详细内容，更多请关注php中文网其它相关文章！