第 7 章错误处理 on Go 语言原本

7.1 问题的演化

Mon, 01 Jan 0001 00:00:00 +0000

7.1 问题的演化

在 6.3 里我们已经把那道分水岭画了出来：如何处理错误，是语言设计的一处根本抉择。异常派（C++、Java、Python）用 try/catch 把错误路径从正常逻辑里抽走，主干干净，代价是错误路径变得隐式，可能从任意调用点抛出；值派（Go、Rust、以及 C 的返回码传统）把错误当作普通返回值显式传递，啰嗦，但每一条错误路径都白纸黑字、无处可藏。Go 选了值派，只为「真正异常」保留一个轻量的 panic/recover。这一节要讲的，是这个选择落地之后，「错误作为值」这一主张本身又经历了怎样的演化：从一个只能打印的字符串，长成一棵可以被程序逐层追问「你到底是不是那个错误」的树。

7.1.1 错误即值

Go 把错误定义成一个内建接口，全部的约定只有一个方法：

// src/builtin/builtin.go
type error interface {
	Error() string
}

任何实现了 Error() string 的类型，都可以当作 error 传递。它不是一种特殊的语言构造，而是一个再普通不过的接口值，能赋值、能比较、能放进切片、能作为字段、能跨 channel 传递。这正是 Rob Pike 在《Errors are values》里反复强调的一句话：错误是值，而值可以被编程。程序员不是被动地「捕获」一个从天而降的异常，而是主动地拿一个值去做判断、包装、传播或吞下。

这个主张在函数签名上有一处固定的体现：错误总是作为最后一个返回值显式交还给调用方。

f, err := os.Open(name)
if err != nil {
	return err
}
defer f.Close()
// 使用 f

满屏的 if err != nil 常被诟病啰嗦，但它恰是值派的代价与收益的同一面：错误既然是值，就必须像别的值一样被显式接住，编译器不会替你把它偷偷送到别处。这与 6.3 里 Go 的整体气质一脉相承，显式优于隐式。把错误降格为一个一方法接口，换来的是最大的自由：标准库不需要预先规定一套错误等级体系，任何人都能用最贴合自己场景的类型去实现 error，从一个字符串常量，到一个携带行号、文件名、底层系统调用号的结构体。代价是这份自由把责任也一并交还给了用户，怎样定义错误、怎样让调用方能可靠地辨认它，都得自己安排。这一节余下的篇幅，讲的就是 Go 社区与标准库为这份责任摸索出的答案。

7.2 错误值检查

Mon, 01 Jan 0001 00:00:00 +0000

7.2 错误值检查

错误一旦在调用链里向上传播，处理它的代码与产生它的代码往往隔着许多层。这就带来一个朴素却棘手的问题：拿到一个层层传上来的 error，调用方如何判断「它到底是不是某个特定的错误」，又如何从中取回当初那个携带了上下文的具体错误值？这一节回答的就是这件事，以及 Go 为此在 errors 包里立下的那套约定。

最朴素的错误就是一句话。errors.New 把一个字符串包成 error，内部只是 errorString 这一极简实现：

package errors

type errorString struct              { s string }
func (e *errorString) Error() string { return e.s }

func New(text string) error { return &errorString{text} }

实践中常把它和 fmt.Sprintf 拼起来用，凑出一句带变量的错误消息。可一旦错误被压成字符串，它的「可处理性」便几乎归零：调用方只能拿这句话去和别的字符串比对，无从知道它的来源，也无从取回原始的错误值。Go 1.13 在 errors 包里补上的 Unwrap、Is、As，以及 go1.26 新增的泛型 AsType，要解决的正是这个「错误一旦上浮便不可追问」的困境。它们的共同前提，是先把错误串成一条可以回溯的链。

7.2.1 错误传播链：从单层包装到错误树

要让上层能追问下层，错误就不能在传播时丢掉来历。fmt.Errorf 用 %w 动词做到这一点：它在生成新错误消息的同时，把被包装的原始错误存了下来，使新错误「记得」自己是从谁来的。单个 %w 产出的是一个实现了 Unwrap() error 的 wrapError，多个 %w 则产出实现了 Unwrap() []error 的 wrapErrs：

7.3 错误格式与上下文

Mon, 01 Jan 0001 00:00:00 +0000

7.3 错误格式与上下文

一个好的错误，不只是「出错了」，而是能告诉人：在做什么的时候、因为什么、出了什么错。问题的演化（7.1）与值检查（7.2）给了我们传递与检视错误的机制，这一节谈机制之上的工程实践，错误的文本应当怎么写、上下文如何沿调用链一层层累积、以及当人写的文字不够用时，栈轨迹与结构化日志如何按需补上。贯穿其间的，是 Go 在错误信息上的一个总体倾向：人写的语义上下文，优于机器采的栈轨迹。

7.3.1 `Error() string` 的约定

error 接口只要求一个方法：

1
2
3

type error interface {
    Error() string
}

围绕这唯一的方法，Go 社区形成了一套不成文却处处可见的风格约定：错误字符串首字母小写、结尾不加标点。约定背后的原因很实际。错误极少独立出现，它们几乎总是被层层包装、首尾相接，拼成一条更长的字符串。设想三层调用各自补一句上下文，最终用户看到的是：

read config: open /etc/app.conf: permission denied

这是三段错误用 : 拼接而成的一条因果链。若每一段都按句子的写法首字母大写、末尾加句号，拼起来便成了「Read config: Open /etc/app.conf: Permission denied.」，一串大写字母与句号散落在句子中间，读起来支离破碎。小写、无尾标点的片段，才能顺畅地嵌进任意位置，串成一条连贯的链。这条约定细小，却是 Go 错误信息能层层拼接而不失可读的前提。

需要澄清一处常见的说法：检查这条约定的并不是 go vet。历史上它由 golint 负责，golint 归档后，这项检查（编号 ST1005）由 staticcheck 等第三方工具承担。go vet 不管错误字符串的大小写，但它确实有一个与错误相关的检查，针对 log/slog 的结构化日志调用（见 7.3.5）。

7.3.2 在每一个边界补上上下文

错误从底层向上传播时，每经过一个有意义的边界，都该补一句「我当时在干什么」。这正是 %w 包装（7.2）的首要用途，也是 Go 错误处理的核心实践。下面是一段典型的配置加载代码，它在两个不同的失败点各自标注了当时的意图：

7.4 错误语义

Mon, 01 Jan 0001 00:00:00 +0000

7.4 错误语义

7.2 与 7.3 站在错误的调用方一侧，讲清了拿到一个 error 之后如何沿链检查、如何叠加上下文。这一节把视角调到另一侧，站在库作者一侧问一个先于检查的问题：当一个包要把失败暴露给外界时，它应当把错误做成什么形式？是导出一个可比较的值，还是导出一个带字段的类型，抑或什么都不导出？

这并非纯粹的风格之争。错误的形式一旦发布，就成了包的公开契约的一部分，和函数签名一样难以更改。调用方会照着这个形式写下分支逻辑，而这些分支逻辑反过来把调用方与库耦合在了一起。不同的形式，承诺给契约的东西不同，因而日后能改动的自由度也不同。本节把社区里成型的几种做法摆在一起，按「向 API 契约承诺了什么」这条线索逐一称量它们的代价，最后给出一个可操作的取舍次序。

7.4.1 哨兵错误：向契约承诺一个值

最直接的做法是导出一个预先创建好的错误值，让调用方拿它做相等比较。标准库里这样的例子俯拾皆是：

package io

// EOF 是 Read 在没有更多输入时返回的错误。
var EOF = errors.New("EOF")

package sql

// ErrNoRows 在 QueryRow 没有命中任何行时由 Row.Scan 返回。
var ErrNoRows = errors.New("sql: no rows in result set")

调用方据此分支：

row := db.QueryRow("select ...")
if err := row.Scan(&x); errors.Is(err, sql.ErrNoRows) {
    // 查无此行，走业务上的「不存在」分支
}

这类预置的错误值称为哨兵错误（sentinel error）。它简单到近乎透明，是表达「成功之外的一种确定结局」的最省力手段。io.EOF 之所以不算真正的「错误」而更像一个信号，正因为它表达的是「正常读到了流的末端」。

7.5 错误处理的未来

Mon, 01 Jan 0001 00:00:00 +0000

7.5 错误处理的未来

前几节里我们见过 error 接口的朴素、%w 包装与错误链的检视。读者读到这里，心里多半积着一个没有说出口的疑问：if err != nil 这三行模板，年复一年地铺满每个 Go 程序，难道就没有办法收掉吗？这个疑问并不孤单。从 2018 年的 go2 草案到 2025 年的一纸结论，Go 团队为它前后推敲了七年，提出过 check/handle、try、? 等多套语法，又把它们一一收回。本节把这条没有走通的语法之路，与另一条悄然走通的库演进之路，并排摆出来，并交代 Go 团队最终给出的判断：在可见的将来，错误处理不会迎来专门的语法。

理解这个结局，比记住任何一套被否决的语法都重要。它不是搁置，而是一次有据可依的「不做」，背后是 Go 对「显式优于简洁」的一次郑重重申。

7.5.1 被否决的语法尝试

check / handle：2018 年的 go2 草案

错误处理语法化的第一次正式尝试，是 2018 年随「Go 2」蓝图公布的 check/handle 草案。它引入两个关键字：check 是一个表达式，对返回 (T, error) 的调用求值，错误为 nil 时取出 T，否则把控制权交给最近的 handle 块；handle 是一个语句，声明当前函数里检查失败时的善后逻辑。一个典型的文件拷贝在草案下写成这样：

func CopyFile(src, dst string) error {
	handle err {
		return fmt.Errorf("copy %s %s: %v", src, dst, err)
	}

	r := check os.Open(src)     // 失败则跳到上面的 handle
	defer r.Close()

	w := check os.Create(dst)
	handle err {                 // handle 可叠加，后声明的先生效
		w.Close()
		os.Remove(dst)
	}

	check io.Copy(w, r)
	check w.Close()
	return nil
}

它的野心在 handle 链：多个 handle 按声明逆序生效，让人联想到 defer 的栈式语义，能把「出错时回滚」的清理逻辑沿调用顺序层层铺开。代价也正在于此。读者要读懂某一行 check 失败后会发生什么，得在脑子里维护一个 handle 栈，与 defer 栈彼此独立又彼此纠缠。社区普遍反馈它「为省下 if 而引入了一套新的、需要单独学习的控制流」，复杂度未必比它消除的更低。草案最终被判定过于复杂而未进入提案阶段。

第 7 章 错误处理 on Go 语言原本

7.1 问题的演化

7.1 问题的演化

7.1.1 错误即值

7.2 错误值检查

7.2 错误值检查

7.2.1 错误传播链：从单层包装到错误树

7.3 错误格式与上下文

7.3 错误格式与上下文

7.3.1 Error() string 的约定

7.3.2 在每一个边界补上上下文

7.4 错误语义

7.4 错误语义

7.4.1 哨兵错误：向契约承诺一个值

7.5 错误处理的未来

7.5 错误处理的未来

7.5.1 被否决的语法尝试

check / handle：2018 年的 go2 草案

第 7 章错误处理 on Go 语言原本

7.3.1 `Error() string` 的约定