Go-错误的处理和传递

发表于 2025-11-19 分类于 Go

Go语言优雅错误处理指南

概述

本文档详细讲解如何在Go语言项目中实现优雅的错误处理机制，特别是在Gin框架的Handler-Service-DAO分层架构中。

核心原则

1. 错误是值，不是异常

Go语言将错误视为普通返回值，这要求开发者显式处理每个可能的错误。

2. 添加上下文信息

错误在传递过程中应该携带足够的上下文信息，便于问题定位。

3. 统一错误响应

API应该返回统一格式的错误响应，方便客户端处理。

分层错误处理架构

项目结构

project/
├── response/
│   └── response.go
├── errors/
│   └── business.go
├── handler/
│   └── user_handler.go
├── service/
│   └── user_service.go
├── dao/
│   └── user_dao.go
└── model/
└── user.go

为什么需要分层错误处理？

各层职责和错误处理策略

层级	职责	错误处理策略	为什么这样设计
DAO层	数据访问，纯技术操作	返回原始错误或基础业务错误	DAO层不应该关心业务逻辑，只负责技术错误
Service层	业务逻辑处理	将技术错误转换为业务错误，添加业务上下文	Service层理解业务含义，知道如何包装错误
Handler层	HTTP请求处理	捕获所有错误，转换为HTTP响应	Handler层是系统边界，需要统一响应格式

错误传递的哲学

DAO层保持纯粹：只处理数据访问相关错误，不添加业务语义
Service层添加业务语义：将技术错误翻译成业务人员能理解的错误
Handler层统一格式化：将错误转换为客户端能理解的格式

源码实现

1. 统一响应包 (response/response.go)

package response

import (
"net/http"

    "github.com/gin-gonic/gin"
)

type Response struct {
Code    int         `json:"code"`
Message string      `json:"message"`
Data    interface{} `json:"data,omitempty"`
Error   string      `json:"error,omitempty"`
}

func Success(c *gin.Context, data interface{}) {
c.JSON(http.StatusOK, Response{
Code:    0,
Message: "success",
Data:    data,
})
}

func Error(c *gin.Context, code int, message string) {
c.JSON(http.StatusOK, Response{
Code:    code,
Message: message,
})
}

func InternalError(c *gin.Context, err error) {
c.Error(err)
c.JSON(http.StatusOK, Response{
Code:    500,
Message: "内部服务器错误",
})
}

func BadRequest(c *gin.Context, message string) {
c.JSON(http.StatusOK, Response{
Code:    400,
Message: message,
})
}

func NotFound(c *gin.Context, message string) {
c.JSON(http.StatusOK, Response{
Code:    404,
Message: message,
})
}

设计理由：统一响应格式确保客户端始终收到结构一致的响应，便于错误处理和用户体验优化。

2. 业务错误定义 (errors/business.go)

package errors

import "fmt"

const (
CodeUserNotFound = 10001
CodeInvalidParam = 10002
CodeDBError      = 10003
)

type BusinessError struct {
Code    int
Message string
Err     error
}

func (e *BusinessError) Error() string {
if e.Err != nil {
return fmt.Sprintf("业务错误[%d]: %s, 原因: %v", e.Code, e.Message, e.Err)
}
return fmt.Sprintf("业务错误[%d]: %s", e.Code, e.Message)
}

func (e *BusinessError) Unwrap() error {
return e.Err
}

func NewBusinessError(code int, message string) *BusinessError {
return &BusinessError{
Code:    code,
Message: message,
}
}

func WrapBusinessError(code int, message string, err error) *BusinessError {
return &BusinessError{
Code:    code,
Message: message,
Err:     err,
}
}

var (
ErrUserNotFound = NewBusinessError(CodeUserNotFound, "用户不存在")
ErrInvalidParam = NewBusinessError(CodeInvalidParam, "参数错误")
)

设计理由：自定义错误类型可以携带丰富的上下文信息（错误码、消息、原始错误），支持错误链追踪。

3. 数据模型 (model/user.go)

package model

type User struct {
ID     int64  `json:"id"`
Name   string `json:"name"`
Email  string `json:"email"`
Status string `json:"status"`
}

4. DAO层 (dao/user_dao.go)

package dao

import (
"database/sql"
"fmt"

    "your-project/errors"
    "your-project/model"
)

type UserDAO struct {
db *sql.DB
}

func NewUserDAO(db *sql.DB) *UserDAO {
return &UserDAO{db: db}
}

func (d *UserDAO) GetUserByID(userID int64) (*model.User, error) {
const query = "SELECT id, name, email, status FROM users WHERE id = ? AND deleted = 0"

    var user model.User
    err := d.db.QueryRow(query, userID).Scan(&user.ID, &user.Name, &user.Email, &user.Status)
    
    if err != nil {
        if err == sql.ErrNoRows {
            return nil, errors.ErrUserNotFound
        }
        return nil, fmt.Errorf("查询用户失败 (ID: %d): %w", userID, err)
    }
    
    return &user, nil
}

func (d *UserDAO) CreateUser(user *model.User) error {
const query = "INSERT INTO users (name, email) VALUES (?, ?)"

    result, err := d.db.Exec(query, user.Name, user.Email)
    if err != nil {
        return fmt.Errorf("创建用户失败: %w", err)
    }
    
    userID, err := result.LastInsertId()
    if err != nil {
        return fmt.Errorf("获取用户ID失败: %w", err)
    }
    
    user.ID = userID
    return nil
}

DAO层错误传递策略：

遇到sql.ErrNoRows时返回业务错误ErrUserNotFound，因为”用户不存在”是业务逻辑的一部分
其他数据库错误使用%w包装，保留原始错误信息但添加上下文
不直接返回HTTP状态码，因为DAO层不应该知道HTTP协议

5. Service层 (service/user_service.go)

package service

import (
"your-project/dao"
"your-project/errors"
"your-project/model"
)

type UserService struct {
userDAO *dao.UserDAO
}

func NewUserService(userDAO *dao.UserDAO) *UserService {
return &UserService{userDAO: userDAO}
}

type CreateUserRequest struct {
Name  string `json:"name" binding:"required"`
Email string `json:"email" binding:"required,email"`
}

func (s *UserService) GetUser(userID int64) (*model.User, error) {
if userID <= 0 {
return nil, errors.WrapBusinessError(
errors.CodeInvalidParam,
"用户ID必须大于0",
nil,
)
}

    user, err := s.userDAO.GetUserByID(userID)
    if err != nil {
        var businessErr *errors.BusinessError
        if errors.As(err, &businessErr) {
            return nil, err
        }
        
        return nil, errors.WrapBusinessError(
            errors.CodeDBError,
            "获取用户信息失败",
            err,
        )
    }
    
    if user.Status == "banned" {
        return nil, errors.NewBusinessError(10004, "用户已被封禁")
    }
    
    return user, nil
}

func (s *UserService) CreateUser(req *CreateUserRequest) (*model.User, error) {
if req.Name == "" {
return nil, errors.WrapBusinessError(
errors.CodeInvalidParam,
"用户名不能为空",
nil,
)
}

    if len(req.Name) < 2 || len(req.Name) > 20 {
        return nil, errors.WrapBusinessError(
            errors.CodeInvalidParam,
            "用户名长度必须在2-20个字符之间",
            nil,
        )
    }
    
    user := &model.User{
        Name:  req.Name,
        Email: req.Email,
    }
    
    if err := s.userDAO.CreateUser(user); err != nil {
        return nil, errors.WrapBusinessError(
            errors.CodeDBError,
            "创建用户失败",
            err,
        )
    }
    
    return user, nil
}

Service层错误传递策略：

进行业务参数验证，将无效参数转换为业务错误
使用errors.As()检查错误类型，如果是业务错误直接传递
将DAO层的技术错误包装为业务错误，添加业务语义
实现业务规则验证（如用户状态检查）
不涉及HTTP概念，保持业务逻辑的纯粹性

6. Handler层 (handler/user_handler.go)

package handler

import (
"net/http"
"strconv"

    "github.com/gin-gonic/gin"

    "your-project/errors"
    "your-project/response"
    "your-project/service"
)

type UserHandler struct {
userService *service.UserService
}

func NewUserHandler(userService *service.UserService) *UserHandler {
return &UserHandler{userService: userService}
}

func (h *UserHandler) GetUser(c *gin.Context) {
userIDStr := c.Param("id")
userID, err := strconv.ParseInt(userIDStr, 10, 64)
if err != nil {
response.BadRequest(c, "无效的用户ID")
return
}

    user, err := h.userService.GetUser(userID)
    if err != nil {
        h.handleError(c, err)
        return
    }
    
    response.Success(c, user)
}

func (h *UserHandler) CreateUser(c *gin.Context) {
var req service.CreateUserRequest
if err := c.ShouldBindJSON(&req); err != nil {
response.BadRequest(c, "请求参数格式错误")
return
}

    user, err := h.userService.CreateUser(&req)
    if err != nil {
        h.handleError(c, err)
        return
    }
    
    response.Success(c, user)
}

func (h *UserHandler) handleError(c *gin.Context, err error) {
var businessErr *errors.BusinessError
if errors.As(err, &businessErr) {
response.Error(c, businessErr.Code, businessErr.Message)
return
}

    response.InternalError(c, err)
}

Handler层错误处理策略：

处理HTTP特定错误（参数解析、数据绑定）
统一的错误处理入口handleError
区分业务错误和系统错误，分别处理
将错误转换为统一的HTTP响应格式
记录错误日志（在生产环境中可能隐藏内部错误细节）

7. 主程序 (main.go)

package main

import (
"database/sql"
"log"

    "github.com/gin-gonic/gin"
    _ "github.com/go-sql-driver/mysql"

    "your-project/dao"
    "your-project/handler"
    "your-project/service"
)

func main() {
db, err := sql.Open("mysql", "user:password@/dbname")
if err != nil {
log.Fatal("数据库连接失败:", err)
}
defer db.Close()

    userDAO := dao.NewUserDAO(db)
    userService := service.NewUserService(userDAO)
    userHandler := handler.NewUserHandler(userService)

    r := gin.Default()
    
    r.GET("/users/:id", userHandler.GetUser)
    r.POST("/users", userHandler.CreateUser)
    
    log.Println("服务器启动在 :8080")
    r.Run(":8080")
}

错误处理流程示例

成功流程

请求: GET /users/123
↓ Handler: 解析参数，调用service.GetUser(123)
↓ Service: 参数验证，调用dao.GetUserByID(123)  
↓ DAO: 执行SQL，返回用户数据
↑ Service: 返回用户数据
↑ Handler: response.Success(c, user)
响应: { "code": 0, "message": "success", "data": { ... } }

错误流程（用户不存在）

请求: GET /users/999
↓ Handler: 解析参数，调用service.GetUser(999)
↓ Service: 参数验证，调用dao.GetUserByID(999)
↓ DAO: SQL返回ErrNoRows，返回errors.ErrUserNotFound
↑ Service: 传递errors.ErrUserNotFound
↑ Handler: h.handleError → response.Error(10001, "用户不存在")
响应: { "code": 10001, "message": "用户不存在" }

错误流程（数据库连接失败）

请求: GET /users/123
↓ Handler: 解析参数，调用service.GetUser(123)
↓ Service: 参数验证，调用dao.GetUserByID(123)
↓ DAO: 数据库连接失败，返回原始错误
↑ Service: 包装为业务错误"获取用户信息失败"
↑ Handler: h.handleError → response.InternalError
响应: { "code": 500, "message": "内部服务器错误" }

各层错误传递的设计哲学

1. 关注点分离 (Separation of Concerns)

DAO层只关心数据访问技术细节
Service层只关心业务逻辑和规则
Handler层只关心HTTP协议和用户交互

2. 错误信息 enrichment（丰富化）

错误在向上传递过程中不断添加上下文信息：

DAO: “查询失败”
Service: “获取用户信息失败：查询失败”
Handler: HTTP 500 + 日志记录

3. 错误类型转换

将底层技术错误转换为高层业务概念：

sql.ErrNoRows → ErrUserNotFound → HTTP 404
sql.ErrConnDone → ErrDBError → HTTP 500

4. 防御性编程

每层都进行适当的验证，尽早失败，避免错误传播到不合适的层级。

最佳实践总结

分层处理：各司其职，避免层间职责混淆
错误包装：使用错误链保留完整上下文
统一格式：客户端友好的错误响应格式
适当日志：在适当层级记录适当详情的日志
错误分类：区分可预期业务错误和意外系统错误

通过这种架构，可以实现清晰、可维护的错误处理机制，提高代码质量和系统稳定性。

Claran's blog

随笔.5

2025.11.15

2025.11.22

2025.11.23

2025.11.24