《Go Cookbook CN》系列 03：Go错误处理全维度解析

约 4959 字大约 17 分钟

2026-04-02

本文聚焦Go语言核心特性之一的错误处理机制，从基础认知到实战落地，全方位拆解Go错误处理的设计理念、标准范式与进阶技巧。无论你是刚接触Go的新手，还是需要规范错误处理逻辑的开发者，学完本文都能掌握Go错误处理的完整体系，从根本上理解Go为何摒弃异常、如何优雅处理错误，以及在不同场景下的最佳实践。

【本篇核心收获】

理解Go语言「错误≠异常」的核心设计理念，掌握函数返回错误、显式检查错误的标准编程范式
掌握简化重复错误处理的实用技巧（辅助函数、Must模式），在保证可读性的前提下减少冗余代码
学会创建自定义错误（字符串型、结构体实现error接口），携带更多错误上下文信息
掌握错误包装/解包的方法，以及使用errors.Is/errors.As精准检查特定错误的技巧
理解panic/recover的执行逻辑与适用场景，掌握捕获系统中断信号实现优雅退出的方法

3.0 概述

Alexander Pope 在《An Essay on Criticism》中写道：犯错是人之常情。软件由人类编写，因此必然会出错。优雅地从错误中恢复，是错误处理的核心——当程序进入未预料或无法满足正常流程的情况时，错误处理定义了应如何恢复。

程序员常将错误处理视为繁琐的、事后才考虑的工作，这本身就是一个错误。正如测试是软件质量的重要部分，从错误中恢复也应是良好软件设计的一部分。在 Go 语言中，错误处理被高度重视，尽管其方式并不传统：标准库errors包提供了许多操作错误的函数，但 Go 的大部分错误处理是语言内置特性或编程惯用法的一部分。

3.0.1 错误不是异常

在 Python、Java 等语言中，错误处理通过异常机制实现：异常是表示错误的对象，问题出现时被「抛出」，调用函数通过try/catch（Python 为try/except）捕获和处理。

Go 的做法截然不同：它没有异常机制，取而代之的是「错误（error）」——错误是表示意外情况的内置类型。与「抛出」异常不同，Go 中会创建并返回一个错误给调用者，这是本质区别：

函数不会「抛出」异常，你无法预知函数是否/会抛出何种异常，只能用try/catch包围可能出错的代码；
错误是函数有意返回的，目的是让调用者显式检查并单独处理。

熟悉异常的程序员可能觉得 Go 错误处理繁琐——每次函数调用后都需显式检查错误值并处理。你可以忽略错误，但 Go 编程习惯要求认真对待错误，唯一可普遍接受忽略错误的情况是：你真的不关心操作的返回结果。

func guess(number uint) (answer bool, err error) {
    if number > 99 {
        err = errors.New("Number is larger than 100")
    }
    // 检查猜测是否正确
    return answer, err
}

创建错误的两种常见方式：

errors.New：仅用字符串创建错误，适用于简单场景；
fmt.Errorf：支持格式化错误字符串，还能包装其他错误（详见 3.4 节）。

// 格式化错误字符串
err = fmt.Errorf("Number %d is larger than 100", number)

2. 调用函数：检查错误

Go 的核心原则：不要忽略错误。处理错误的标准方法是将错误视为普通返回值处理：

str := "123456789"
num, err := strconv.ParseInt(str, 10, 64)
if err != nil {
    // 处理错误（如日志记录、返回上层、触发panic等）
}

strconv.ParseInt返回转换后的整数num和错误err：err为nil则正常，否则需处理。

忽略错误的风险

你可以故意忽略错误（将错误赋值给匿名变量_）：

num, _ := strconv.ParseInt(str, 10, 64)

这是合法语法，编译器不会报错，但代码质量工具（linter）、IDE 或代码审查会指出问题——忽略错误常被视为不负责任的做法，避坑提示：除非明确不关心操作结果，否则禁止忽略错误。

3. Go 为何选择此方式？

异常看似更简单（可分组语句统一处理），但存在明显缺陷：

若无恰当的try/catch块，极易遗漏异常；
过多语句放入一个try/catch块，会混淆「哪个语句可能抛出何种异常」。

使用错误而非异常的核心优势：错误可像普通值一样在程序正常流程中传递、处理，开发者必须显式检查和处理错误，让错误处理逻辑成为代码不可或缺的一部分。

func unmarsh() (person Person) {
    r, err := http.Get("https://swapi.dev/api/people/1")
    if err != nil {
        // 处理错误
    }
    defer r.Body.Close()
    data, err := io.ReadAll(r.Body)
    if err != nil {
        // 处理错误
    }
    err = json.Unmarshal(data, &person)
    if err != nil {
        // 处理错误
    }
    return person
}

上述代码有三处重复的错误检查逻辑，可通过以下方式简化：

方式1：通用辅助函数

封装check函数统一处理错误，可添加日志、通用恢复逻辑，甚至传入自定义处理函数：

func helperUnmarsh() (person Person) {
    r, err := http.Get("https://swapi.dev/api/people/1")
    check(err, "Calling SW people API")
    defer r.Body.Close()

    data, err := io.ReadAll(r.Body)
    check(err, "Read JSON from response")

    err = json.Unmarshal(data, &person)
    check(err, "Unmarshalling")
    return person
}

func check(err error, msg string) {
    if err != nil {
        log.Println("Error encountered:", msg)
        // 执行通用的错误处理操作（如日志、告警、默认值赋值等）
    }
}

方式2：Must 模式（标准库借鉴）

标准库text/template包的template.Must模式：包装返回「值+错误」的函数，错误非nil则触发panic。可封装通用must函数：

func must(param any, err error) any {
    if err != nil {
        panic(err) // 或自定义错误处理逻辑
    }
    return param
}

使用must函数简化代码：

func mustUnmarsh() (person Person) {
    r := must(http.Get("https://swapi.dev/api/people/1")).(*http.Response)
    defer r.Body.Close()
    data := must(io.ReadAll(r.Body)).([]byte)
    must(nil, json.Unmarshal(data, &person))
    return person
}

避坑提示：Must 模式虽简化代码，但会降低可读性（需强制类型转换），且panic会终止程序（除非用recover捕获），仅适用于「错误不可恢复、必须终止」的场景。

// 简单字符串错误
err := errors.New("Syntax error in the code")

// 格式化字符串错误（携带上下文）
err := fmt.Errorf("Syntax error in the code at line %d", line)

方式2：实现 error 接口（带附加信息）

builtin包定义的error接口仅包含一个方法：

type error interface {
    Error() string
}

任何拥有Error() string方法的类型，都可作为error使用。通过结构体实现该接口，可携带更多错误信息：

示例1：基础自定义错误

// 通信错误自定义类型
type CommsError struct{}
func (m CommsError) Error() string {
    return "An error happened during data transfer."
}

示例2：带附加信息的自定义错误

// 语法错误结构体（携带行、列信息）
type SyntaxError struct {
    Line int // 错误行号
    Col  int // 错误列号
}

// 实现Error接口，返回格式化错误信息
func (err *SyntaxError) Error() string {
    return fmt.Sprintf("Error at line %d, column %d", err.Line, err.Col)
}

读取自定义错误的附加信息

使用类型断言提取自定义错误的附加字段：

if err != nil {
    // 类型断言检查是否为SyntaxError
    err, ok := err.(*SyntaxError)
    if ok {
        // 使用错误的附加信息（如打印行号、列号）
        log.Printf("Syntax error at line %d, column %d", err.Line, err.Col)
    } else {
        // 处理其他类型错误
    }
}

避坑提示：直接类型断言（err.(*SyntaxError)）若失败会触发panic，需用「断言+ok」的方式安全检查。

// 原始错误
err1 := errors.New("Oops something happened.")
// 包装错误（添加上下文）
err2 := fmt.Errorf("An error was encountered when calling API - %w", err1)

使用errors.Unwrap解包，提取原始错误：

originalErr := errors.Unwrap(err2) // originalErr == err1

方式2：自定义结构体包装（更灵活）

通过结构体字段保存原始错误，需实现Error和Unwrap方法：

// 连接错误结构体（携带主机、端口、原始错误）
type ConnectionError struct {
    Host string
    Port int
    Err  error // 保存被包装的原始错误
}

// 实现Error接口：返回带上下文的错误信息
func (err *ConnectionError) Error() string {
    return fmt.Sprintf("Connection error to %s:%d - %v", err.Host, err.Port, err.Err)
}

// 实现Unwrap方法：返回原始错误（支持errors.Unwrap/Is/As）
func (err *ConnectionError) Unwrap() error {
    return err.Err
}

// 定义自定义错误值
var ApiErr error = errors.New("Error trying to get data from API")

// 返回该错误的函数
func connectAPI() error {
    return ApiErr
}

// 检查错误是否为ApiErr
err := connectAPI()
if err != nil {
    if errors.Is(err, ApiErr) {
        log.Println("处理API错误：", err)
    }
}

即使错误被包装，errors.Is仍能递归检查：

// 返回包装了ApiErr的ConnectionError
func connect() error {
    return &ConnectionError{
        Host: "localhost",
        Port: 8080,
        Err:  ApiErr,
    }
}

// 仍能匹配到ApiErr
err := connect()
if err != nil {
    if errors.Is(err, ApiErr) {
        log.Println("处理API错误（包装后）：", err)
    }
}

2. errors.As：检查错误类型是否匹配

用于检查错误是否为指定类型，支持递归检查包装错误链：

err := connect()
if err != nil {
    var connErr *ConnectionError
    // 检查错误是否为*ConnectionError类型（成功则赋值给connErr）
    if errors.As(err, &connErr) {
        log.Printf("无法连接到 %s:%d，原始错误：%v", connErr.Host, connErr.Port, connErr.Err)
    }
}

避坑提示：errors.As的第二个参数必须是「错误类型的指针」，否则会返回false。

立即停止当前函数的正常执行；
执行当前函数中所有defer延迟函数；
向上冒泡到调用者，重复步骤1-2，直到整个程序以非零退出码终止。

示例：正常执行流程

package main
import "fmt"

func A() {
    defer fmt.Println("defer on A")
    fmt.Println("A")
    B() // A 调用 B
    fmt.Println("end of A")
}

func B() {
    defer fmt.Println("defer on B")
    fmt.Println("B")
    C() // B 调用 C
    fmt.Println("end of B")
}

func C() {
    defer fmt.Println("defer on C")
    fmt.Println("C")
    fmt.Println("end of C")
}

func main() {
    defer fmt.Println("defer on main")
    fmt.Println("main")
    A() // main 调用 A
    fmt.Println("end of main")
}

执行结果：

main
A
B
C
end of C
defer on C
end of B
defer on B
end of A
defer on A
end of main
defer on main

示例：触发 panic 后的流程

修改C函数，在执行中调用panic：

func C() {
    defer fmt.Println("defer on C")
    fmt.Println("C")
    panic("panic called in C") // 触发panic
    fmt.Println("end of C") // 不会执行
}

执行结果：

main
A
B
C
defer on C // C的延迟函数执行
defer on B // B的延迟函数执行
defer on A // A的延迟函数执行
defer on main // main的延迟函数执行
panic: panic called in C // 程序终止并打印panic信息

避坑提示：panic会终止程序（除非用recover捕获），仅适用于「程序无法继续运行」的严重错误（如配置文件缺失、初始化失败），禁止用于普通业务错误。

正常执行时返回nil；
panic触发后，返回传递给panic的参数，并停止panic的传播。

示例：捕获 panic 并恢复程序

修改 3.6 节的示例，在B函数中添加defer函数捕获panic：

package main
import "fmt"

func A() {
    defer fmt.Println("defer on A")
    B()
    fmt.Println("end of A") // panic恢复后会执行
}

func B() {
    defer dontPanic() // 延迟调用恢复函数
    fmt.Println("B")
    C()
    fmt.Println("end of B") // panic触发后不会执行
}

func C() {
    defer fmt.Println("defer on C")
    fmt.Println("C")
    panic("panic called in C") // 触发panic
    fmt.Println("end of C")
}

// 恢复panic的函数
func dontPanic() {
    err := recover()
    if err != nil {
        fmt.Println("panic called but everything is ok now:", err)
    } else {
        fmt.Println("defer on B")
    }
}

func main() {
    defer fmt.Println("defer on main")
    fmt.Println("main")
    A()
    fmt.Println("end of main") // panic恢复后会执行
}

执行结果：

main
A
B
C
defer on C
panic called but everything is ok now: panic called in C // 捕获panic
end of A // 程序恢复执行
defer on A
end of main
defer on main

适用场景

第三方包触发panic，但你不希望程序终止；
单个 goroutine 出错，需停止该 goroutine 但保留主程序（如 Web 服务器的请求处理 goroutine）。

避坑提示：recover仅在defer函数中有效，直接调用recover（非延迟执行）会返回nil，无法捕获panic。

package main

import (
    "log"
    "os"
    "os/signal"
    "syscall"
    "time"
)

func main() {
    // 1. 创建通道接收信号（缓冲大小1，避免阻塞）
    ch := make(chan os.Signal, 1)
    
    // 2. 注册要捕获的信号：os.Interrupt（Ctrl+C）、syscall.SIGTERM（kill命令）
    signal.Notify(ch, os.Interrupt, syscall.SIGTERM)
    
    // 3. 启动goroutine等待信号
    go func() {
        // 阻塞等待信号
        sig := <-ch
        log.Printf("收到信号：%v，开始优雅退出...", sig)
        
        // 4. 执行清理逻辑（如关闭文件、释放连接、保存状态）
        log.Println("清理资源：关闭数据库连接...")
        log.Println("清理资源：保存程序状态...")
        
        // 5. 退出程序
        os.Exit(0)
    }()

    // 模拟程序正常运行
    log.Println("程序运行中，按Ctrl+C退出...")
    for {
        time.Sleep(1 * time.Second)
        log.Println("程序正常执行中...")
    }
}

关键说明

signal.Notify：将指定信号转发到通道ch，若第二个参数为空，则转发所有信号；
信号处理逻辑需放在 goroutine 中，避免阻塞主程序；
清理逻辑需简洁、快速，避免耗时操作（信号处理有时间限制）。

模块小结

本模块核心：通过os/signal包捕获中断信号，在 goroutine 中执行清理逻辑，实现程序优雅退出，避免强制终止导致资源泄漏、数据丢失。

【本篇核心知识点速记】

核心理念：Go 用「返回 error」替代「抛出异常」，要求显式检查错误，不轻易忽略；
基础操作：编写函数时按惯例返回错误（最后一个返回值），调用函数时检查err != nil；
简化重复处理：用辅助函数（check）封装通用逻辑，Must 模式仅适用于严重错误；
自定义错误：简单场景用errors.New/fmt.Errorf，复杂场景用结构体实现error接口；
错误检查：errors.Is检查错误值，errors.As检查错误类型，支持包装错误链；
panic/recover：panic用于严重错误，recover需在defer中使用，可恢复程序执行；
中断处理：用os/signal包捕获 Ctrl+C 等信号，在 goroutine 中执行清理逻辑，优雅退出。