Go 错误处理：errors.New() 与 fmt.Errorf()

在 Go 语言中，错误处理是程序健壮性的核心组成部分。创建错误是日常开发中最频繁的操作之一，而标准库提供了两种主要方式来生成错误值：errors.New() 和 fmt.Errorf()。理解它们的区别并正确使用，是写出健壮 Go 代码的关键一步。

errors.New()：创建静态错误

errors.New() 是 errors 包提供的函数，用于创建一个简单的错误值。当你需要一个固定文本的错误消息时，这是最直接的选择。

基本用法如下：

package main

import (
    "errors"
    "fmt"
)

func divide(a, b int) (int, error) {
    if b == 0 {
        return 0, errors.New("division by zero")
    }
    return a / b, nil
}

func main() {
    result, err := divide(10, 0)
    if err != nil {
        fmt.Println("Error:", err)
    }
}

核心特性：

errors.New() 创建的错误值是不可变的静态字符串。编译器会对相同的错误字符串进行优化处理——当多个地方使用完全相同的错误消息时，Go 编译器会让它们共享同一个底层字符串实例。这种机制称为字符串驻留（string interning），可以减少内存占用并提升比较效率。

// 两个相同的错误会共享同一个实例
err1 := errors.New("database connection failed")
err2 := errors.New("database connection failed")
fmt.Println(err1 == err2) // 输出 true

fmt.Errorf()：创建格式化错误

fmt.Errorf() 是 fmt 包提供的函数，允许在创建错误时进行字符串格式化。当你需要在错误消息中嵌入变量值时，它是最合适的选择。

基本用法如下：

package main

import (
    "fmt"
)

func validateAge(age int) error {
    if age < 0 {
        return fmt.Errorf("invalid age: %d (must be greater than 0)", age)
    }
    return nil
}

func main() {
    err := validateAge(-5)
    if err != nil {
        fmt.Println("Error:", err)
    }
}

核心特性：

fmt.Errorf() 的最大优势在于可以动态嵌入变量值，使错误信息包含更多上下文。例如，当验证用户输入时，你可以将具体的非法值包含在错误消息中，这大大简化了调试工作。

func processOrder(orderID int, quantity int) error {
    if quantity <= 0 {
        return fmt.Errorf("invalid quantity %d for order %d: must be positive", quantity, orderID)
    }
    return nil
}

深入对比：两种方式的差异

错误包装：%w 动词的妙用

fmt.Errorf() 有一个独特的能力：使用 %w 动词可以将底层错误包装起来，同时保留完整的错误链。这是 Go 1.13 引入的重要特性，它让错误溯源成为可能。

错误包装的基本用法：

package main

import (
    "errors"
    "fmt"
)

var ErrNotFound = errors.New("resource not found")

func findUser(id int) error {
    if id <= 0 {
        return fmt.Errorf("invalid user id %d: %w", id, ErrNotFound)
    }
    return nil
}

func main() {
    err := findUser(-1)
    if err != nil {
        fmt.Println("Error message:", err)

        // 检查错误链中是否包含特定错误
        if errors.Is(err, ErrNotFound) {
            fmt.Println("Caught a not-found error from the chain!")
        }

        // 展开错误链查看完整路径
        var target *fmt.Errorf
        if errors.As(err, &target) {
            fmt.Println("Error can be unwrapped:", target)
        }
    }
}

使用 %w 的关键优势：

当底层函数返回错误时，通过 %w 包装后，上层调用者可以使用 errors.Is() 判断错误类型，使用 errors.As() 提取特定错误类型。这种机制构建了一条完整的错误传播链路，让调试时能够追溯错误的真正来源。

func queryDatabase(query string) error {
    return fmt.Errorf("database query failed: %w", ErrNotFound)
}

func handleRequest(req string) error {
    if err := queryDatabase(req); err != nil {
        return fmt.Errorf("request handling failed: %w", err)
    }
    return nil
}

func main() {
    err := handleRequest("SELECT *")
    if err != nil {
        // 沿着错误链向上查找
        if errors.Is(err, ErrNotFound) {
            fmt.Println("Root cause: resource not found")
        }
    }
}

最佳实践指南

实践一：定义包级错误常量

对于可复用的固定错误，使用 errors.New() 在包级别定义常量。这样既保证了错误消息的一致性，也便于在包的多个位置引用。

package database

import "errors"

// 定义包级错误常量
var (
    ErrConnectionClosed = errors.New("database: connection is closed")
    ErrTransactionFailed = errors.New("database: transaction failed")
    ErrDuplicateKey     = errors.New("database: duplicate key violation")
)

func Connect(addr string) error {
    // 模拟连接失败
    return fmt.Errorf("cannot connect to %q: %w", addr, ErrConnectionClosed)
}

实践二：使用哨兵错误进行错误检查

哨兵错误（Sentinel Error）是预先定义的错误值，用于在包边界进行错误类型的精确判断。

package main

import (
    "errors"
    "io"
)

// 定义哨兵错误
var ErrEOF = errors.New("EOF")

func readData(reader io.Reader) error {
    data := make([]byte, 1024)
    _, err := reader.Read(data)
    if err != nil {
        // 返回包装后的哨兵错误
        return fmt.Errorf("read failed: %w", err)
    }
    return nil
}

func main() {
    err := readData(nil)
    if errors.Is(err, io.EOF) {
        fmt.Println("Reached end of file")
    }
}

实践三：避免过度使用 fmt.Errorf()

在性能敏感的代码路径中，如果错误消息是固定的，应该优先使用 errors.New()。因为 fmt.Errorf() 每次调用都会进行字符串格式化，虽然单次开销很小，但在高频调用的场景下会产生可观的累积开销。

// 推荐：在热路径中使用 errors.New()
func validateToken(token string) error {
    if len(token) < 32 {
        return errors.New("token too short")
    }
    return nil
}

// 不推荐：固定消息也使用 fmt.Errorf()
func validateToken(token string) error {
    if len(token) < 32 {
        return fmt.Errorf("token too short")  // 多余的格式化开销
    }
    return nil
}

实践四：在错误中添加有意义的上下文

当需要区分同一类型错误的不同来源时，使用 fmt.Errorf() 添加调用点的上下文信息。

func processPayment(orderID string, amount float64) error {
    if amount <= 0 {
        return fmt.Errorf("payment failed for order %q: invalid amount %.2f", orderID, amount)
    }
    return nil
}

func processRefund(orderID string, amount float64) error {
    if amount <= 0 {
        return fmt.Errorf("refund failed for order %q: invalid amount %.2f", orderID, amount)
    }
    return nil
}

总结

errors.New() 和 fmt.Errorf() 是 Go 错误处理的两大基石。选择的关键在于是否需要动态信息：

• 当错误消息是固定的常量时，使用 errors.New()。它经过编译器优化，性能更好，且支持字符串驻留。

• 当错误消息需要嵌入变量值或包装底层错误时，使用 fmt.Errorf()。它提供了 _%w_ 动词支持错误链追踪。

在实际项目中，合理的错误定义策略能够显著提升代码的可维护性和可调试性。建议在包边界使用哨兵错误配合错误包装，在内部实现中根据需要选择合适的错误创建方式。