Go语言错误处理最佳实践与自定义错误

Go错误处理哲学

Go语言的错误处理机制是其最具争议的特性之一。不同于Java的异常捕获或Rust的Result类型，Go采用显式的错误返回值模式。这种设计虽然增加了代码量，但强制开发者直面错误，使错误处理路径清晰可见，避免了异常隐藏带来的意外。

错误处理与其他语言对比

标准错误处理模式

基本错误处理

// 标准错误检查模式
func ReadConfig(path string) (*Config, error) {
    data, err := os.ReadFile(path)
    if err != nil {
        return nil, fmt.Errorf("read config file: %w", err)
    }
    
    var cfg Config
    if err := json.Unmarshal(data, &cfg); err != nil {
        return nil, fmt.Errorf("parse config: %w", err)
    }
    
    return &cfg, nil
}

卫语句模式（减少嵌套）

// 优化前：深层嵌套
func ProcessOrder(order *Order) error {
    if order != nil {
        if order.UserID != "" {
            user, err := GetUser(order.UserID)
            if err == nil {
                if user.Active {
                    // 处理订单...
                    return nil
                }
            }
        }
    }
    return errors.New("invalid order")
}

// 优化后：卫语句提前返回
func ProcessOrder(order *Order) error {
    if order == nil {
        return errors.New("order is nil")
    }
    
    if order.UserID == "" {
        return errors.New("user ID is empty")
    }
    
    user, err := GetUser(order.UserID)
    if err != nil {
        return fmt.Errorf("get user: %w", err)
    }
    
    if !user.Active {
        return errors.New("user is inactive")
    }
    
    // 处理订单...
    return nil
}

错误包装与链

import "errors"

// Go 1.13+ 使用 %w 包装错误
func ConnectDB(addr string) (*DB, error) {
    conn, err := net.Dial("tcp", addr)
    if err != nil {
        return nil, fmt.Errorf("connect to %s: %w", addr, err)
    }
    // ...
}

// 错误链检查
func IsConnectionError(err error) bool {
    // 使用 errors.Is 检查错误链中的特定错误
    if errors.Is(err, net.ErrClosed) {
        return true
    }
    
    // 使用 errors.As 提取特定类型的错误
    var netErr net.Error
    if errors.As(err, &netErr) && netErr.Timeout() {
        return true
    }
    
    return false
}

自定义错误类型

标准error接口仅提供Error() string方法，但在实际开发中，我们经常需要携带更多上下文信息，如错误码、HTTP状态码、堆栈等。

基础自定义错误

// 定义应用错误类型
type AppError struct {
    Code    string // 错误码，如 "AUTH_001"
    Message string // 用户友好的错误消息
    Err     error  // 底层错误
}

func (e *AppError) Error() string {
    if e.Err != nil {
        return fmt.Sprintf("[%s] %s: %v", e.Code, e.Message, e.Err)
    }
    return fmt.Sprintf("[%s] %s", e.Code, e.Message)
}

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

// 使用示例
func Authenticate(token string) (*User, error) {
    claims, err := parseToken(token)
    if err != nil {
        return nil, &AppError{
            Code:    "AUTH_001",
            Message: "无效的认证令牌",
            Err:     err,
        }
    }
    // ...
}

带堆栈的错误

import (
    "fmt"
    "runtime"
    "strings"
)

// StackError 带堆栈信息的错误
type StackError struct {
    Msg   string
    Stack []string
    Cause error
}

func NewStackError(msg string) *StackError {
    return &StackError{
        Msg:   msg,
        Stack: captureStack(2), // 跳过当前函数和NewStackError
    }
}

func WrapStackError(err error, msg string) *StackError {
    return &StackError{
        Msg:   msg,
        Stack: captureStack(2),
        Cause: err,
    }
}

func (e *StackError) Error() string {
    if e.Cause != nil {
        return fmt.Sprintf("%s: %v", e.Msg, e.Cause)
    }
    return e.Msg
}

func (e *StackError) Unwrap() error {
    return e.Cause
}

func (e *StackError) Format(f fmt.State, verb rune) {
    switch verb {
    case 'v':
        if f.Flag('+') {
            fmt.Fprintf(f, "%s\n", e.Msg)
            fmt.Fprintf(f, "Stack trace:\n")
            for _, line := range e.Stack {
                fmt.Fprintf(f, "    %s\n", line)
            }
            if e.Cause != nil {
                fmt.Fprintf(f, "Caused by: %+v", e.Cause)
            }
            return
        }
        fallthrough
    case 's':
        fmt.Fprint(f, e.Error())
    }
}

func captureStack(skip int) []string {
    var stack []string
    for i := skip; ; i++ {
        pc, file, line, ok := runtime.Caller(i)
        if !ok {
            break
        }
        fn := runtime.FuncForPC(pc)
        stack = append(stack, fmt.Sprintf("%s\n    %s:%d", fn.Name(), file, line))
    }
    return stack
}

领域特定错误类型

// 定义领域错误类型
type ValidationError struct {
    Field   string
    Value   interface{}
    Rule    string
    Message string
}

func (e *ValidationError) Error() string {
    return fmt.Sprintf("validation failed for field '%s': %s", e.Field, e.Message)
}

// 批量验证错误
type ValidationErrors []*ValidationError

func (es ValidationErrors) Error() string {
    var msgs []string
    for _, e := range es {
        msgs = append(msgs, e.Error())
    }
    return strings.Join(msgs, "; ")
}

// 使用示例
func ValidateUser(u *User) error {
    var errs ValidationErrors
    
    if u.Name == "" {
        errs = append(errs, &ValidationError{
            Field:   "name",
            Rule:    "required",
            Message: "name is required",
        })
    }
    
    if u.Age < 0 || u.Age > 150 {
        errs = append(errs, &ValidationError{
            Field:   "age",
            Value:   u.Age,
            Rule:    "range",
            Message: "age must be between 0 and 150",
        })
    }
    
    if len(errs) > 0 {
        return errs
    }
    return nil
}

错误码体系设计

在微服务架构中，统一的错误码体系对于问题定位和服务间协作至关重要。

package errcode

// 错误码格式：服务_模块_序号
// 例如：USER_AUTH_001 表示用户服务的认证模块第1个错误

// 通用错误 (0-999)
const (
    ErrUnknown        = "SYS_000"
    ErrInternal       = "SYS_001"
    ErrInvalidParam   = "SYS_002"
    ErrUnauthorized   = "SYS_003"
    ErrForbidden      = "SYS_004"
    ErrNotFound       = "SYS_005"
    ErrTimeout        = "SYS_006"
    ErrRateLimit      = "SYS_007"
)

// 用户服务错误 (1000-1999)
const (
    ErrUserNotFound      = "USER_001"
    ErrUserExists        = "USER_002"
    ErrInvalidPassword   = "USER_003"
    ErrUserDisabled      = "USER_004"
)

// 认证错误 (1100-1199)
const (
    ErrTokenInvalid      = "AUTH_001"
    ErrTokenExpired      = "AUTH_002"
    ErrTokenRevoked      = "AUTH_003"
    ErrMFARequired       = "AUTH_004"
)

// CodedError 带错误码的错误类型
type CodedError struct {
    Code       string
    Message    string
    HTTPStatus int
    Details    map[string]interface{}
    Cause      error
}

func New(code, message string) *CodedError {
    return &CodedError{
        Code:    code,
        Message: message,
        Details: make(map[string]interface{}),
    }
}

func (e *CodedError) Error() string {
    return fmt.Sprintf("[%s] %s", e.Code, e.Message)
}

func (e *CodedError) WithHTTPStatus(status int) *CodedError {
    e.HTTPStatus = status
    return e
}

func (e *CodedError) WithDetail(key string, value interface{}) *CodedError {
    e.Details[key] = value
    return e
}

func (e *CodedError) WithCause(err error) *CodedError {
    e.Cause = err
    return e
}

func (e *CodedError) Unwrap() error {
    return e.Cause
}

// 预定义错误实例
var (
    ErrUserNotFoundInstance = New(ErrUserNotFound, "用户不存在").
                WithHTTPStatus(404)
    
    ErrInvalidTokenInstance = New(ErrTokenInvalid, "认证令牌无效").
                WithHTTPStatus(401)
)

错误码与HTTP状态映射

错误处理最佳实践

1. 不要忽略错误

// 错误示例：忽略错误
file, _ := os.Open("config.json") // 危险！

// 正确做法：显式处理
file, err := os.Open("config.json")
if err != nil {
    return fmt.Errorf("open config: %w", err)
}
defer file.Close()

2. 错误信息要提供上下文

// 不好的错误信息
return err

// 好的错误信息：包含操作和关键参数
return fmt.Errorf("failed to connect to database %s at %s: %w", dbName, addr, err)

3. 使用Sentinel Error（谨慎）

// 定义包级别的错误变量
var ErrNotFound = errors.New("resource not found")
var ErrAlreadyExists = errors.New("resource already exists")

// 使用 errors.Is 检查
if errors.Is(err, ErrNotFound) {
    // 处理未找到的情况
}

4. 优雅降级与错误隔离

func GetUserWithFallback(userID string) (*User, error) {
    // 先尝试从缓存获取
    user, err := cache.Get(userID)
    if err == nil {
        return user, nil
    }
    
    // 缓存未命中，从数据库获取
    user, err = db.Get(userID)
    if err != nil {
        // 记录错误但返回友好消息
        log.Printf("db error: %v", err)
        return nil, fmt.Errorf("service temporarily unavailable")
    }
    
    // 回填缓存（异步）
    go cache.Set(userID, user)
    
    return user, nil
}

总结

Go的错误处理机制虽然初看繁琐，但通过合理的设计和模式应用，可以构建出健壮、可维护的错误处理体系。关键要点包括：

• 拥抱显式：接受if err != nil的模式，它是Go哲学的一部分
• 上下文为王：每个错误包装层都添加上下文，形成清晰的错误链
• 类型化错误：在需要区分处理时使用自定义错误类型
• 统一错误码：在微服务架构中建立统一的错误码规范
• 工具辅助：使用errcheck、staticcheck等工具检查未处理的错误

好的错误处理不仅能让程序更健壮，还能大大提升运维效率。当生产环境出现问题时，一条清晰的错误链往往能让问题的定位和解决时间从小时缩短到分钟。