3、Go 错误处理基础：error 接口、errors.New、fmt.Errorf、自定义错误类型

在 Go 语言中，错误处理是构建健壮业务接口的核心环节。与 Java 或 Python 的异常机制不同，Go 采用显式的错误返回值设计。本章将深入剖析 Go 错误处理的基础设施，为后续实现业务接口错误码断言奠定坚实的理论基础。

3.1 error 接口：一切错误的源头

Go 语言通过一个预定义的接口类型 error 来统一表示错误。任何实现了该接口的类型都可以作为错误值传递。

// Go 标准库中的 error 接口定义
type error interface {
    Error() string
}

该接口仅包含一个 Error() 方法，返回一个描述错误信息的字符串。这意味着，只要一个类型实现了 Error() string 方法，它就自动满足了 error 接口，可以被当作错误处理。

3.2 errors.New：快速创建简单错误

标准库 errors 包提供了 New 函数，用于创建一个仅包含静态文本信息的错误。这是创建简单、无上下文错误的最直接方式。

package main

import (
    "errors"
    "fmt"
)

func main() {
    err := errors.New("用户未找到")
    if err != nil {
        fmt.Println(err.Error()) // 输出：用户未找到
    }
}

errors.New 内部返回一个指向 errorString 结构体的指针，该结构体实现了 error 接口。由于返回的是指针，每次调用 errors.New 即使传入相同的字符串，也会产生不同的错误实例，这在进行错误比较时需要留意。

3.3 fmt.Errorf：带格式化信息的错误

当需要在错误信息中嵌入动态数据（如用户 ID、订单号）时，fmt.Errorf 是比 errors.New 更合适的选择。它支持 fmt 包的格式化动词，可以构建更丰富的错误描述。

package main

import (
    "fmt"
)

func findUser(userID int) error {
    return fmt.Errorf("用户 %d 未找到", userID)
}

func main() {
    err := findUser(1001)
    if err != nil {
        fmt.Println(err) // 输出：用户 1001 未找到
    }
}

3.4 自定义错误类型：携带业务上下文

对于复杂的业务场景，仅靠字符串描述远远不够。自定义错误类型允许我们在错误中携带结构化数据，例如错误码、HTTP 状态码、内部错误原因等。这是实现业务接口错误码断言的关键技术。

package main

import "fmt"

// BusinessError 自定义业务错误类型
type BusinessError struct {
    Code    int    // 业务错误码
    Message string // 用户可读的错误消息
    Err     error  // 内部原始错误（可选）
}

// Error 实现 error 接口
func (e *BusinessError) Error() string {
    return fmt.Sprintf("业务错误 [Code=%d]: %s", e.Code, e.Message)
}

// Unwrap 支持错误链（Go 1.13+）
func (e *BusinessError) Unwrap() error {
    return e.Err
}

func processOrder(orderID string) error {
    // 模拟一个数据库错误
    dbErr := fmt.Errorf("数据库连接超时")
    return &BusinessError{
        Code:    1001,
        Message: "订单处理失败",
        Err:     dbErr,
    }
}

func main() {
    err := processOrder("ORD-2024-001")
    if err != nil {
        fmt.Println(err)
        // 输出：业务错误 [Code=1001]: 订单处理失败

        // 使用类型断言获取自定义错误信息
        var bizErr *BusinessError
        if errors.As(err, &bizErr) {
            fmt.Printf("错误码: %d\n", bizErr.Code)
            fmt.Printf("内部原因: %v\n", bizErr.Err)
        }
    }
}

上述代码展示了自定义错误类型的核心优势：

• 结构化数据： 通过 Code 字段携带业务错误码，便于前端或 API 网关进行精确处理。
• 错误链： 通过 Unwrap 方法保留原始错误，便于日志记录和根因分析。
• 类型断言： 调用方可以使用 errors.As 或类型断言来提取自定义错误中的详细信息。

3.5 三种错误创建方式对比

3.6 错误处理最佳实践

1. 总是检查错误： 不要使用 _ 忽略错误，除非你明确知道该错误可以安全忽略。
2. 尽早返回错误： 使用 if err != nil { return err } 模式，避免深层嵌套。
3. 包装错误以添加上下文： 使用 fmt.Errorf("操作失败: %w", err) 在错误传播过程中添加信息。
4. 为业务错误定义专用类型： 在 BFF 层，为每个业务域定义清晰的错误码和错误类型。
5. 避免在错误消息中包含敏感信息： 错误消息可能会被记录到日志或返回给客户端，注意保护用户隐私和系统安全。