别再只会 if err != nil：Go error 从错误链到工程实战详解

简介

Go 代码里最常见的错误处理大概是这样：

1result, err := doSomething()
2if err != nil {
3	return err
4}
5

这几行代码不难，真正容易出问题的是后面的选择：

1应该新建错误，还是包装原错误？
2应该使用 ==，还是 errors.Is？
3什么时候需要自定义错误类型？
4错误应该在哪一层记录日志？
5多个清理操作同时失败，应该返回哪一个错误？
6普通错误、panic 和 recover 到底怎么分工？
7

Go 没有把错误处理藏进异常机制，而是把错误当成普通值显式传递。

这套设计看起来重复，却带来一个直接好处：函数签名会明确说明操作可能失败，调用方也能在失败发生的位置决定返回、重试、降级还是终止。

一句话概括：

1error 不只是错误文本，它还是可以分类、包装、传递和组合的值。
2

error 到底是什么

error 是 Go 内置的接口类型，定义非常简单：

1type error interface {
2	Error() string
3}
4

任何类型只要实现了 Error() string，就实现了 error 接口。

1package main
2
3import "fmt"
4
5type ValidationError struct {
6	Field   string
7	Message string
8}
9
10func (e *ValidationError) Error() string {
11	return fmt.Sprintf("字段 %s：%s", e.Field, e.Message)
12}
13
14func validateName(name string) error {
15	if name == "" {
16		return &ValidationError{Field: "name", Message: "不能为空"}
17	}
18	return nil
19}
20
21func main() {
22	err := validateName("")
23	fmt.Println(err)
24}
25

输出：

1字段 name：不能为空
2

ValidationError 没有声明实现某个接口。Go 使用隐式接口实现，只要方法集合满足要求，就可以作为 error 返回。

nil 表示操作成功

函数通常把 error 放在最后一个返回值：

1func divide(a, b int) (int, error) {
2	if b == 0 {
3		return 0, errors.New("除数不能为 0")
4	}
5	return a / b, nil
6}
7

约定很明确：

• err == nil：操作成功，其他返回值可以使用
• err != nil：操作失败，先处理错误

完整示例：

1package main
2
3import (
4	"errors"
5	"fmt"
6)
7
8func divide(a, b int) (int, error) {
9	if b == 0 {
10		return 0, errors.New("除数不能为 0")
11	}
12	return a / b, nil
13}
14
15func main() {
16	result, err := divide(12, 3)
17	if err != nil {
18		fmt.Println("计算失败：", err)
19		return
20	}
21
22	fmt.Println("计算结果：", result)
23}
24

输出：

1计算结果： 4
2

错误分支尽早返回，可以减少嵌套：

1data, err := loadData()
2if err != nil {
3	return err
4}
5
6result, err := parseData(data)
7if err != nil {
8	return err
9}
10
11return saveResult(result)
12

正常流程保持在左侧，错误处理紧跟在可能失败的调用后面，这就是 Go 项目里常见的写法。

创建错误的三种常见方式

errors.New：固定错误文本

errors.New 适合创建不需要动态参数的简单错误：

1err := errors.New("用户名不能为空")
2

完整示例：

1package main
2
3import (
4	"errors"
5	"fmt"
6)
7
8func checkAge(age int) error {
9	if age < 0 {
10		return errors.New("年龄不能小于 0")
11	}
12	return nil
13}
14
15func main() {
16	if err := checkAge(-1); err != nil {
17		fmt.Println(err)
18	}
19}
20

fmt.Errorf：带动态信息

错误信息需要带上文件名、用户 ID 或参数值时，使用 fmt.Errorf：

1return fmt.Errorf("用户 %d 不存在", userID)
2

这里仅仅是格式化文本，还没有形成错误链。

1package main
2
3import "fmt"
4
5func findUser(id int64) error {
6	return fmt.Errorf("用户 %d 不存在", id)
7}
8
9func main() {
10	fmt.Println(findUser(1001))
11}
12

输出：

1用户 1001 不存在
2

自定义错误：携带结构化信息

如果调用方需要读取错误码、字段名、重试时间等信息，应定义错误类型，而不是解析错误字符串。

1type RateLimitError struct {
2	RetryAfter time.Duration
3}
4
5func (e *RateLimitError) Error() string {
6	return fmt.Sprintf("请求过于频繁，%s 后重试", e.RetryAfter)
7}
8

错误文本适合阅读，结构化字段适合程序判断。

错误文本不是错误身份

下面两个错误的文本相同，但不是同一个错误值：

1first := errors.New("not found")
2second := errors.New("not found")
3
4fmt.Println(first == second)
5

输出：

1false
2

因此，不能在判断时临时创建一个同文本错误：

1if errors.Is(err, errors.New("not found")) {
2	// 通常匹配不到
3}
4

需要稳定识别的错误，应复用同一个变量：

1var ErrNotFound = errors.New("not found")
2

这种包级错误值通常称为哨兵错误。

哨兵错误：表示稳定的错误类别

哨兵错误适合表达调用方需要识别的固定状态：

1var (
2	ErrNotFound   = errors.New("not found")
3	ErrConflict   = errors.New("conflict")
4	ErrPermission = errors.New("permission denied")
5)
6

完整示例：

1package main
2
3import (
4	"errors"
5	"fmt"
6)
7
8var ErrUserNotFound = errors.New("user not found")
9
10func findUser(id int64) error {
11	if id != 1001 {
12		return ErrUserNotFound
13	}
14	return nil
15}
16
17func main() {
18	err := findUser(2002)
19	if errors.Is(err, ErrUserNotFound) {
20		fmt.Println("返回 404")
21		return
22	}
23
24	if err != nil {
25		fmt.Println("返回 500")
26	}
27}
28

导出的哨兵错误会成为包的公开契约。调用方一旦依赖 ErrUserNotFound，后续修改时就要继续维护这个语义。

只想返回一段说明，不希望调用方依赖错误类别时，普通错误文本通常已经够用。

为什么要包装错误

底层函数返回的错误往往缺少业务上下文。

例如：

1file does not exist
2

只看这句话，不知道读取了哪个文件，也不知道发生在哪个业务流程。

可以使用 %w 包装原错误：

1return fmt.Errorf("读取配置 %q: %w", filename, err)
2

包装后同时保留两部分信息：

1外层上下文：读取配置 "app.json"
2底层原因：file does not exist
3

完整示例：

1package main
2
3import (
4	"errors"
5	"fmt"
6	"os"
7)
8
9func readConfig(filename string) ([]byte, error) {
10	data, err := os.ReadFile(filename)
11	if err != nil {
12		return nil, fmt.Errorf("读取配置 %q: %w", filename, err)
13	}
14	return data, nil
15}
16
17func main() {
18	_, err := readConfig("missing.json")
19	if err == nil {
20		return
21	}
22
23	fmt.Println(err)
24	if errors.Is(err, os.ErrNotExist) {
25		fmt.Println("配置文件不存在，加载默认配置")
26	}
27}
28

输出类似：

1读取配置 "missing.json": open missing.json: no such file or directory
2配置文件不存在，加载默认配置
3

%w 和 %v 的差别非常重要：

1fmt.Errorf("读取配置失败: %v", err) // 只拼接文本
2fmt.Errorf("读取配置失败: %w", err) // 包装错误，保留错误链
3

两者打印出来可能很像，但只有 %w 能让 errors.Is、errors.As 继续识别底层错误。

错误链是怎么形成的

使用 %w 包装后，外层错误会提供：

1Unwrap() error
2

可以把单链错误理解成：

1HTTP 层错误
2    ↓ Unwrap
3Service 层错误
4    ↓ Unwrap
5Repository 层错误
6    ↓ Unwrap
7ErrNotFound
8

示例：

1package main
2
3import (
4	"errors"
5	"fmt"
6)
7
8var ErrRecordNotFound = errors.New("record not found")
9
10func queryUser(id int64) error {
11	return fmt.Errorf("查询 user_id=%d: %w", id, ErrRecordNotFound)
12}
13
14func loadProfile(id int64) error {
15	if err := queryUser(id); err != nil {
16		return fmt.Errorf("加载用户资料: %w", err)
17	}
18	return nil
19}
20
21func main() {
22	err := loadProfile(1001)
23	fmt.Println(err)
24	fmt.Println(errors.Is(err, ErrRecordNotFound))
25	fmt.Println(errors.Unwrap(err))
26}
27

输出：

1加载用户资料: 查询 user_id=1001: record not found
2true
3查询 user_id=1001: record not found
4

errors.Unwrap 只拆一层。业务判断通常不需要手动循环解包，直接使用 errors.Is 或 errors.As 即可。

errors.Is：判断错误值和错误类别

直接使用 == 只能比较当前错误值：

1err == ErrNotFound
2

错误被包装后，外层错误不再等于哨兵错误：

1wrapped := fmt.Errorf("查询失败: %w", ErrNotFound)
2
3fmt.Println(wrapped == ErrNotFound)            // false
4fmt.Println(errors.Is(wrapped, ErrNotFound))   // true
5

errors.Is 会沿错误树向下检查：

• 当前错误是否等于目标错误
• 当前错误是否实现自定义的 Is(error) bool
• 当前错误能否通过 Unwrap 继续展开

因此，只要错误可能被包装，就优先使用：

1if errors.Is(err, ErrNotFound) {
2	// 按未找到处理
3}
4

不要比较错误文本：

1if err.Error() == "record not found" {
2	// 文本稍有变化就失效
3}
4

错误文本用于展示和日志，errors.Is 用于程序分支。

errors.As：提取错误链中的具体类型

哨兵错误适合表达固定类别，自定义错误类型适合携带额外字段。

1package main
2
3import (
4	"errors"
5	"fmt"
6)
7
8type ValidationError struct {
9	Field   string
10	Value   any
11	Message string
12}
13
14func (e *ValidationError) Error() string {
15	return fmt.Sprintf("字段 %s 的值 %v 不合法：%s", e.Field, e.Value, e.Message)
16}
17
18func validateAge(age int) error {
19	if age < 0 || age > 150 {
20		return &ValidationError{
21			Field:   "age",
22			Value:   age,
23			Message: "必须在 0 到 150 之间",
24		}
25	}
26	return nil
27}
28
29func register(age int) error {
30	if err := validateAge(age); err != nil {
31		return fmt.Errorf("注册校验失败: %w", err)
32	}
33	return nil
34}
35
36func main() {
37	err := register(200)
38
39	var validationErr *ValidationError
40	if errors.As(err, &validationErr) {
41		fmt.Printf("field=%s, value=%v, message=%s\n",
42			validationErr.Field,
43			validationErr.Value,
44			validationErr.Message,
45		)
46	}
47}
48

输出：

1field=age, value=200, message=必须在 0 到 150 之间
2

直接类型断言只检查最外层动态类型：

1validationErr, ok := err.(*ValidationError)
2

如果错误已经被 %w 包装，通常会断言失败。

errors.As 会遍历错误链，更适合提取可能被包装的自定义错误。

目标变量的写法要与错误类型一致：

1var target *ValidationError
2if errors.As(err, &target) {
3	// target 的类型是 *ValidationError
4}
5

自定义错误同时保留底层原因

自定义错误不仅可以保存业务字段，也可以实现 Unwrap 保留底层错误：

1package main
2
3import (
4	"errors"
5	"fmt"
6)
7
8var ErrInsufficientBalance = errors.New("insufficient balance")
9
10type PaymentError struct {
11	OrderID int64
12	Code    string
13	Err     error
14}
15
16func (e *PaymentError) Error() string {
17	return fmt.Sprintf("订单 %d 支付失败，code=%s: %v", e.OrderID, e.Code, e.Err)
18}
19
20func (e *PaymentError) Unwrap() error {
21	return e.Err
22}
23
24func pay(orderID int64) error {
25	return &PaymentError{
26		OrderID: orderID,
27		Code:    "BALANCE_NOT_ENOUGH",
28		Err:     ErrInsufficientBalance,
29	}
30}
31
32func main() {
33	err := pay(9001)
34
35	if errors.Is(err, ErrInsufficientBalance) {
36		fmt.Println("提示余额不足")
37	}
38
39	var paymentErr *PaymentError
40	if errors.As(err, &paymentErr) {
41		fmt.Printf("order_id=%d, code=%s\n", paymentErr.OrderID, paymentErr.Code)
42	}
43}
44

输出：

1提示余额不足
2order_id=9001, code=BALANCE_NOT_ENOUGH
3

这时同一个错误同时支持两种判断：

• errors.Is 判断底层错误类别
• errors.As 读取外层结构化信息

errors.Join：合并多个错误

有些操作可能同时产生多个错误。

例如关闭多个资源、批量校验多个字段、并行执行多个任务。只返回最后一个错误，会把前面的错误丢掉。

Go 1.20 增加了 errors.Join：

1joined := errors.Join(firstErr, secondErr)
2

它有几个特点：

• 忽略传入的 nil
• 所有参数都是 nil 时返回 nil
• 错误文本通常按换行连接
• errors.Is 和 errors.As 可以遍历每个分支

批量校验示例：

1package main
2
3import (
4	"errors"
5	"fmt"
6	"strings"
7)
8
9var (
10	ErrNameRequired     = errors.New("name is required")
11	ErrPasswordTooShort = errors.New("password is too short")
12	ErrEmailInvalid     = errors.New("email is invalid")
13)
14
15type RegisterRequest struct {
16	Name     string
17	Email    string
18	Password string
19}
20
21func validate(request RegisterRequest) error {
22	var errs []error
23
24	if strings.TrimSpace(request.Name) == "" {
25		errs = append(errs, ErrNameRequired)
26	}
27	if !strings.Contains(request.Email, "@") {
28		errs = append(errs, ErrEmailInvalid)
29	}
30	if len(request.Password) < 8 {
31		errs = append(errs, ErrPasswordTooShort)
32	}
33
34	return errors.Join(errs...)
35}
36
37func main() {
38	err := validate(RegisterRequest{
39		Name:     "",
40		Email:    "invalid-email",
41		Password: "123",
42	})
43
44	if err == nil {
45		fmt.Println("校验通过")
46		return
47	}
48
49	fmt.Println(err)
50	fmt.Println("邮箱错误：", errors.Is(err, ErrEmailInvalid))
51	fmt.Println("密码错误：", errors.Is(err, ErrPasswordTooShort))
52}
53

输出：

1name is required
2email is invalid
3password is too short
4邮箱错误： true
5密码错误： true
6

errors.Join 形成的是错误树，不再只是单链。

它实现的是：

1Unwrap() []error
2

而 errors.Unwrap 只处理 Unwrap() error，不会返回 errors.Join 的子错误。判断合并错误时，应直接使用 errors.Is 和 errors.As。

一个 fmt.Errorf 可以包装多个错误

现代 Go 允许一个 fmt.Errorf 格式串包含多个 %w：

1err := fmt.Errorf("保存失败，写入错误: %w，关闭错误: %w", writeErr, closeErr)
2

这同样会形成多分支错误树，errors.Is 和 errors.As 可以检查其中任意分支。

如果只是把多个独立错误汇总起来，errors.Join 通常更直接。

如果还需要在一条错误文本中说明每个错误对应的操作，多个 %w 更有表达力。

实战一：读取并解析配置

下面的 demo 串起文件读取、JSON 解析、错误包装和错误分类。

1package main
2
3import (
4	"encoding/json"
5	"errors"
6	"fmt"
7	"os"
8)
9
10type Config struct {
11	Address string [`json:"address"`](https://xplanc.org/primers/document/zh/03.HTML/EX.HTML%20%E5%85%83%E7%B4%A0/EX.address.md)
12	Port    int    `json:"port"`
13}
14
15func loadConfig(filename string) (Config, error) {
16	data, err := os.ReadFile(filename)
17	if err != nil {
18		return Config{}, fmt.Errorf("读取配置文件 %q: %w", filename, err)
19	}
20
21	var config Config
22	if err := json.Unmarshal(data, &config); err != nil {
23		return Config{}, fmt.Errorf("解析配置文件 %q: %w", filename, err)
24	}
25
26	if config.Address == "" {
27		return Config{}, errors.New("配置 address 不能为空")
28	}
29	if config.Port <= 0 || config.Port > 65535 {
30		return Config{}, fmt.Errorf("配置 port 超出范围: %d", config.Port)
31	}
32
33	return config, nil
34}
35
36func main() {
37	config, err := loadConfig("app.json")
38	if err != nil {
39		switch {
40		case errors.Is(err, os.ErrNotExist):
41			fmt.Println("配置文件不存在")
42		case errors.Is(err, os.ErrPermission):
43			fmt.Println("没有读取配置文件的权限")
44		default:
45			var syntaxErr *json.SyntaxError
46			if errors.As(err, &syntaxErr) {
47				fmt.Printf("JSON 第 %d 字节附近存在语法错误\n", syntaxErr.Offset)
48				return
49			}
50			fmt.Println("加载配置失败：", err)
51		}
52		return
53	}
54
55	fmt.Printf("配置加载成功：%s:%d\n", config.Address, config.Port)
56}
57

这个例子体现了分层处理方式：

1底层负责返回具体原因。
2中间层使用 %w 增加操作上下文。
3边界层使用 Is 或 As 决定最终动作。
4

实战二：统一 HTTP 错误响应

业务层不应该到处拼 HTTP JSON，也不应该把数据库错误原文直接返回给客户端。

可以定义应用错误，在 HTTP 边界统一映射：

1package main
2
3import (
4	"encoding/json"
5	"errors"
6	"fmt"
7	"net/http"
8	"net/http/httptest"
9)
10
11var ErrUserNotFound = errors.New("user not found")
12
13type AppError struct {
14	Status  int
15	Code    string
16	Message string
17	Err     error
18}
19
20func (e *AppError) Error() string {
21	return fmt.Sprintf("%s: %v", e.Code, e.Err)
22}
23
24func (e *AppError) Unwrap() error {
25	return e.Err
26}
27
28func getUser(id string) error {
29	if id == "" {
30		return &AppError{
31			Status:  http.StatusBadRequest,
32			Code:    "INVALID_ARGUMENT",
33			Message: "id 不能为空",
34			Err:     errors.New("empty user id"),
35		}
36	}
37
38	return fmt.Errorf("查询用户 id=%s: %w", id, ErrUserNotFound)
39}
40
41func writeError(w http.ResponseWriter, err error) {
42	status := http.StatusInternalServerError
43	code := "INTERNAL_ERROR"
44	message := "服务暂时不可用"
45
46	var appErr *AppError
47	switch {
48	case errors.As(err, &appErr):
49		status = appErr.Status
50		code = appErr.Code
51		message = appErr.Message
52	case errors.Is(err, ErrUserNotFound):
53		status = http.StatusNotFound
54		code = "USER_NOT_FOUND"
55		message = "用户不存在"
56	}
57
58	w.Header().Set("Content-Type", "application/json")
59	w.WriteHeader(status)
60	_ = json.NewEncoder(w).Encode(map[string]string{
61		"code":    code,
62		"message": message,
63	})
64}
65
66func handler(w http.ResponseWriter, r *http.Request) {
67	if err := getUser(r.URL.Query().Get("id")); err != nil {
68		writeError(w, err)
69		return
70	}
71	w.WriteHeader(http.StatusNoContent)
72}
73
74func main() {
75	request := httptest.NewRequest(http.MethodGet, "/user?id=1001", nil)
76	recorder := httptest.NewRecorder()
77
78	handler(recorder, request)
79
80	fmt.Println("status:", recorder.Code)
81	fmt.Print("body: ", recorder.Body.String())
82}
83