2. 基础错误模式：if err != nil 模式、错误检查的常见陷阱、函数返回错误的约定

在 Go 语言中，错误处理不是通过异常机制，而是通过显式的返回值传递。这种设计哲学强制开发者将错误视为函数签名的第一等公民，从而在代码层面消除“未捕获异常”的隐患。本章将深入剖析 Go 最基础的错误处理模式——if err != nil，并揭示其背后的常见陷阱与函数返回约定。

2.1 if err != nil 模式：Go 的“显式错误哲学”

Go 语言约定：任何可能失败的函数，其最后一个返回值必须是 error 类型。调用方必须检查该值是否为 nil，以决定后续流程。这种模式贯穿整个标准库和第三方代码，是 Go 代码最显著的特征之一。

核心原则： 错误是值（Error is a value），不是控制流。开发者可以像处理普通数据一样比较、传递、包装错误。

以下是一个典型的文件读取示例，展示了 if err != nil 的标准用法：

func readConfig(path string) ([]byte, error) {
    data, err := os.ReadFile(path)
    if err != nil {
        // 错误路径：立即返回或处理
        return nil, fmt.Errorf("读取配置文件失败: %w", err)
    }
    // 正常路径：继续业务逻辑
    return data, nil
}

func main() {
    config, err := readConfig("/etc/app/config.yaml")
    if err != nil {
        log.Fatalf("无法启动应用: %v", err)
    }
    // 使用 config 继续执行...
}

这种模式的优势在于：

  • 显式性：错误路径和正常路径在代码层面清晰分离，没有隐藏的异常栈展开。
  • 可组合性：错误可以像普通值一样被包装、传递、记录，便于构建错误链。
  • 编译期保证：未使用的变量会导致编译错误，强制开发者至少声明 _ 忽略错误，而非无意识地吞掉。

2.2 错误检查的常见陷阱

尽管 if err != nil 模式看似简单，但在实际业务代码中，开发者经常落入以下陷阱。下表总结了最常见的 5 类错误及其后果：

陷阱类别 典型代码 后果
1. 错误被静默忽略 result, _ := doSomething() 业务逻辑在错误状态下继续执行，导致数据不一致或后续 panic
2. 错误检查位置错误 if err != nil { return } 写在资源使用之后 资源泄漏（文件句柄、数据库连接未关闭）
3. 错误被多次包装 每层都使用 fmt.Errorf 但未使用 %w，或重复包装 错误链断裂，errors.Is / errors.As 无法穿透
4. 错误与正常值混用 函数返回部分有效数据 + 非 nil 错误 调用方不确定数据是否可用，导致逻辑混乱
5. 错误比较使用 == if err == io.EOF 而非 errors.Is 当错误被包装后，直接比较失效，导致条件判断错误
⚠️ 陷阱 1 特别警示： 使用 _ 忽略错误是 Go 中最危险的模式之一。在业务代码中，除非你明确知道该错误“绝对不可能发生”且“发生后也无影响”，否则永远不要使用 _ 忽略错误。即使对于日志记录这样的“非关键”操作，也应该至少记录错误信息。

以下代码展示了陷阱 2（资源泄漏）的典型场景：

// ❌ 错误：在 defer 之前检查错误，导致文件未关闭
func readFirstLine(path string) (string, error) {
    f, err := os.Open(path)
    if err != nil {
        return "", err
    }
    // 正确做法：defer f.Close() 应该紧跟在 os.Open 之后
    scanner := bufio.NewScanner(f)
    if scanner.Scan() {
        return scanner.Text(), nil
    }
    // 如果这里发生错误，f 永远不会被关闭
    return "", scanner.Err()
}

// ✅ 正确：defer 立即注册，确保无论哪个分支返回都会执行
func readFirstLineFixed(path string) (string, error) {
    f, err := os.Open(path)
    if err != nil {
        return "", err
    }
    defer f.Close()  // 立即注册，确保资源释放

    scanner := bufio.NewScanner(f)
    if scanner.Scan() {
        return scanner.Text(), nil
    }
    return "", scanner.Err()
}

2.3 函数返回错误的约定

Go 社区经过多年实践，形成了一套关于函数返回错误的约定。这些约定虽然不是语言强制，但被广泛认为是编写可维护 Go 代码的基础。

2.3.1 返回值顺序与类型约定

  • 错误永远是最后一个返回值：func DoSomething() (result Type, err error)。这是 Go 的通用惯例，所有标准库和第三方库都遵守。
  • 成功时 error 必须为 nil：如果函数执行成功，err 必须返回 nil，且其他返回值有效。
  • 失败时其他返回值应为零值：当函数返回非 nil 错误时，其他返回值应该设置为对应的零值（nil、0、"" 等），避免调用方误用。
💡 最佳实践： 如果函数在失败时仍能返回部分有效数据（例如网络读取部分成功），请使用命名返回值或文档明确说明。但大多数情况下，保持“全有或全无”的约定更安全。

2.3.2 错误信息的构建约定

错误信息应该遵循以下原则：

原则 说明 示例
小写开头 错误信息不以大写字母开头，不以标点结尾 "user not found" 而非 "User not found."
包含上下文 错误信息应包含导致错误的输入或状态 "user 'alice' not found in database"
使用 %w 包装 包装下层错误时使用 fmt.Errorf("...: %w", err) fmt.Errorf("读取用户失败: %w", err)
避免敏感信息 不要将密码、令牌等敏感信息放入错误字符串 使用 "认证失败" 而非 "密码 'xxx' 错误"

2.3.3 错误类型的选择

根据业务场景，选择不同的错误表示方式：

  • 哨兵错误（Sentinel Error）：使用 var ErrNotFound = errors.New("not found") 定义包级错误变量。适用于调用方需要精确判断错误类型的场景。
  • 自定义错误类型：实现 error 接口的结构体，携带额外字段（如错误码、HTTP 状态码）。适用于需要传递结构化错误信息的场景。
  • 不透明错误（Opaque Error）：只返回 error 接口，不暴露内部细节。适用于中间层，调用方只需知道“出错了”，无需区分具体类型。

以下 SVG 图展示了 Go 函数返回错误的完整流程与约定：

Go 函数返回错误流程与约定 函数调用 执行业务逻辑 是否出错？ 是 (err != nil) 返回零值 + 非 nil error 错误约定 • 错误为最后一个返回值 • 失败时其他返回值设为零值 • 使用 %w 包装下层错误 否 (err == nil) 返回有效值 + nil 成功约定 • error 必须为 nil • 所有返回值均有效 • 调用方可直接使用返回值 调用方必须检查 err if err != nil { /* 处理错误 */ }

2.4 实战：构建一个带错误约定的用户服务

以下代码综合运用了上述约定，构建一个简单的用户查询服务：

package user

import (
    "errors"
    "fmt"
)

// 哨兵错误：包级变量，供调用方精确判断
var (
    ErrNotFound = errors.New("user not found")
    ErrInvalidID = errors.New("invalid user id")
)

// User 用户实体
type User struct {
    ID   int
    Name string
}

// Repository 用户存储接口
type Repository interface {
    FindByID(id int) (*User, error)
}

// Service 用户服务
type Service struct {
    repo Repository
}

// NewService 构造函数
func NewService(repo Repository) *Service {
    return &Service{repo: repo}
}

// GetUser 获取用户：遵循错误约定
func (s *Service) GetUser(id int) (*User, error) {
    // 1. 参数校验：返回哨兵错误
    if id <= 0 {
        return nil, fmt.Errorf("%w: id=%d", ErrInvalidID, id)
    }

    // 2. 调用下层：传递错误
    user, err := s.repo.FindByID(id)
    if err != nil {
        // 3. 包装错误：保留原始错误链
        return nil, fmt.Errorf("查询用户失败: %w", err)
    }

    // 4. 成功：返回有效数据 + nil
    return user, nil
}
💡 关键点： 上述代码严格遵循了“成功时 error 为 nil，失败时返回零值”的约定。调用方可以安全地使用 errors.Is(err, user.ErrNotFound) 来判断错误类型，即使错误被多层包装。

2.5 错误检查的代码风格建议

为了提升代码可读性，建议遵循以下风格：

  • 尽早返回：将错误检查放在函数开头，减少嵌套层级。避免“箭头形”代码。
  • 避免 else 中的错误处理：如果 if err != nil 分支执行 return，则后续代码不需要缩进在 else 中。
  • 使用空白行分隔逻辑块：在错误检查之后、正常逻辑之前插入空行，增强视觉分离。
// ✅ 推荐风格：尽早返回，减少嵌套
func processOrder(id int) error {
    order, err := fetchOrder(id)
    if err != nil {
        return fmt.Errorf("获取订单失败: %w", err)
    }

    // 正常逻辑从这里开始，没有 else 嵌套
    if err := validateOrder(order); err != nil {
        return fmt.Errorf("订单校验失败: %w", err)
    }

    return saveOrder(order)
}

// ❌ 不推荐：深层嵌套
func processOrderBad(id int) error {
    order, err := fetchOrder(id)
    if err != nil {
        return fmt.Errorf("获取订单失败: %w", err)
    } else {
        if err := validateOrder(order); err != nil {
            return fmt.Errorf("订单校验失败: %w", err)
        } else {
            return saveOrder(order)
        }
    }
}
← 上一章 📖 返回目录 下一章 →