1. Go 错误处理基础：error 接口、errors.New、fmt.Errorf 的基本用法

在 Go 语言中，错误处理不是通过异常机制实现的，而是通过显式的返回值传递。这种设计哲学要求开发者将错误视为普通值，在每个可能出错的调用点主动检查。本章从最底层的 error 接口开始，逐步构建你对 Go 错误处理体系的理解。

1.1 error 接口：一切错误的根类型

Go 语言内置的 error 是一个预声明接口，定义在标准库的 builtin 包中。任何实现了该接口的类型都可以作为错误值传递。

// error 接口定义（builtin 包）
type error interface {
    Error() string
}

这个接口只有一个方法 Error() string，返回错误的描述字符串。这意味着：任何拥有 Error() string 方法的类型都自动满足 error 接口，无需显式声明 implements。

1.2 errors.New：创建最简单的错误

errors.New 是标准库提供的最基础错误构造函数。它接收一个字符串参数，返回一个包含该字符串的 error 值。

import "errors"

var ErrNotFound = errors.New("record not found")
var ErrPermission = errors.New("permission denied")

func FindUser(id int) (User, error) {
    if id <= 0 {
        return User{}, ErrNotFound
    }
    // ... 正常查找逻辑
}

使用 errors.New 创建的错误值具有以下特性：

1.3 fmt.Errorf：带格式的错误构造

当错误信息需要包含动态值时，fmt.Errorf 是比 errors.New 更灵活的选择。它支持 fmt 包的格式化动词，允许将变量嵌入错误描述中。

import "fmt"

func OpenFile(path string) (*os.File, error) {
    f, err := os.Open(path)
    if err != nil {
        return nil, fmt.Errorf("open file %s: %w", path, err)
    }
    return f, nil
}

fmt.Errorf 支持三种格式化行为：

• %s / %v：将值格式化为字符串，返回一个新的错误，不保留原始错误链。
• %w（Go 1.13+）：将错误包装进新错误，保留原始错误以便后续通过 errors.Is 或 errors.As 解包。
• %+v（配合 github.com/pkg/errors）：输出带调用栈的详细错误。

1.4 三种构造方式的对比

1.5 错误处理的基本模式

Go 社区形成了两种主流的错误处理模式，理解它们的差异有助于你在不同场景下做出正确选择。

// 模式一：哨兵错误（Sentinel Error）
var ErrNoRows = errors.New("sql: no rows in result set")

func QueryRow(db *sql.DB, id int) (Row, error) {
    // ...
    if err == sql.ErrNoRows {
        return Row{}, ErrNoRows
    }
    // ...
}

// 模式二：错误类型（Error Type）
type ValidationError struct {
    Field   string
    Message string
}

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

func Validate(input string) error {
    if len(input) == 0 {
        return &ValidationError{Field: "input", Message: "cannot be empty"}
    }
    return nil
}

1.6 错误处理的核心流程

下面的 SVG 图展示了 Go 错误处理从创建到消费的完整生命周期，帮助你建立全局视角。

1.7 报表场景中的错误处理示例

在报表系统中，错误处理需要兼顾可读性和可追踪性。以下是一个典型的报表生成函数，展示了三种构造方式的协同使用。

package report

import (
    "errors"
    "fmt"
)

// 哨兵错误：定义领域内已知的失败场景
var (
    ErrNoData      = errors.New("report: no data available for the given period")
    ErrInvalidDate = errors.New("report: invalid date range")
)

// ReportError 自定义错误类型：携带额外上下文
type ReportError struct {
    Code    int
    Message string
    Err     error
}

func (e *ReportError) Error() string {
    return fmt.Sprintf("report error [%d]: %s", e.Code, e.Message)
}

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

// GenerateReport 报表生成函数
func GenerateReport(start, end string) ([]byte, error) {
    if start > end {
        return nil, fmt.Errorf("%w: start=%s end=%s", ErrInvalidDate, start, end)
    }

    data, err := fetchData(start, end)
    if err != nil {
        return nil, &ReportError{
            Code:    1001,
            Message: "failed to fetch report data",
            Err:     err,
        }
    }

    if len(data) == 0 {
        return nil, ErrNoData
    }

    return renderReport(data)
}

1.8 常见错误处理反模式