1 / 4概念
Error
读完能设计一条从产生到上报的错误链,判断该用哨兵错误、自定义类型还是包装,并说清包的导出面为什么是一种长期契约。错误处理与包边界是同一件事:错误在哪一层被翻译,边界就画在哪一层。
1 概念
1.1 一句话定义
error 是一个只有 Error() string 方法的接口;错误通过返回值传播,用 %w、errors.Is、errors.As、errors.Join 保留和判断原因;包是导出的最小单位,导出标识符即公开 API。
1.2 它解决什么问题
- 失败可判断:哨兵与自定义类型让调用方按语义分支,而不是比较字符串。
- 原因可保留:包装链保存底层错误,日志能还原现场。
- 崩溃可控:panic 与 recover 限制在进程或 goroutine 边界。
- 依赖可约束:
internal/与导入图阻止越界依赖和循环。 - 契约可演化:导出面与弃用注释让升级可预期。
1.3 不属于本页的内容
| 主题 | 去哪 |
|---|---|
go.mod、版本解析与构建 | Go Toolchain |
| goroutine 内错误传播与取消 | Goroutines and Channels |
| HTTP 错误响应与状态码 | Gin / Echo |
| 接口机制与方法集 | Interfaces and Generics |
| 静态检查与 lint 规则 | Code Quality |
1.4 关键术语
| 术语 | 含义 | 容易混淆的点 |
|---|---|---|
error | 只有 Error 方法的接口 | 不是异常,也没有栈帧展开语义 |
| 哨兵错误 | 包级 ErrX 变量 | 用 errors.Is 比较,不用 == 比较包装后的值 |
| 自定义错误 | 实现 error 的结构体 | 指针接收者更常见 |
| 包装 | %w 或 Unwrap | 只有 %w 建立标准链 |
errors.Is | 沿链比较目标 | 不是字符串包含 |
errors.As | 沿链查找类型 | 目标必须是非 nil 指针 |
errors.Join | 合并多个错误 | 全为 nil 时返回 nil |
| panic | 展开当前 goroutine 的栈 | 不是跨 goroutine 异常 |
| recover | 在 defer 中恢复 | 只能恢复同一 goroutine |
internal | 限制导入范围 | 不是访问控制或加密 |
2 机制
2.1 心智模型
错误是值,包装是链表;包的导出面是契约,internal/ 是这条契约的围栏。 每层包装新增一个节点,errors.Is 与 errors.As 沿 Unwrap 走链;跨包边界时把底层错误翻译成对外错误,同时保留原因供日志。包边界一旦发布,增删导出标识符都要按兼容性处理。
2.2 机制拆解
- error 接口:任何实现
Error() string的类型都是 error;error 变量可为 nil,也可装一个 nil 指针。 - 哨兵错误:包级
var ErrX = errors.New(...),用errors.Is判断;适合调用方需要稳定分支的条件。 - 自定义类型:结构体携带字段,指针接收者实现 error;用
errors.As取回;Unwrap暴露原因。 %w包装:fmt.Errorf("...: %w", err)建立链;多个%w产生多叉链;%v只拼文本,不建立链。- Is、As、Join:
Is比较目标值或调用自定义Is;As按类型赋值;Join合并多个错误并忽略 nil。 - panic 与 recover:panic 只用于程序错误;recover 必须在
defer中直接调用;恢复后函数正常返回。 - 包设计:一个包一个职责,导出面窄;接口定义在消费方;
internal/阻止父树之外导入。 - 兼容性:新增导出标识符通常兼容;给接口加方法、删字段、改签名是破坏性变更。
2.3 完整枚举
Go 的错误处理原语,这是完整集合:
| 原语 | 用途 | 规则与边界 |
|---|---|---|
errors.New | 创建哨兵错误 | 文本固定,不带上下文 |
fmt.Errorf 加 %w | 包装并附加上下文 | 每个 %w 建一条链 |
fmt.Errorf 加 %v | 只生成文本 | 不建立链,Is 不可达 |
| 自定义 error 类型 | 携带结构化字段 | 实现 Error,可选 Unwrap |
errors.Is | 判断链上是否有目标 | 支持自定义 Is 方法 |
errors.As | 取链上某个类型 | 目标必须是非 nil 指针 |
errors.Unwrap | 取单层原因 | 单链有效,多叉链返回 nil |
errors.Join | 合并多个错误 | Go 1.20 起;实现 Unwrap() []error |
panic | 终止当前 goroutine | 只用于不可恢复错误 |
recover | 恢复 panic | 只在 defer 中有效 |
2.4 关键数字与量级
| 指标 | 量级 | 说明 |
|---|---|---|
| error 接口值 | 16 B | 两个 word |
| 包装链深度 | 每层 1 个 error | 过深难读 |
errors.Is 复杂度 | O(链长) | 热路径避免深链 |
| panic 展开 | 微秒到毫秒级 | 不适合做控制流 |
| 日志字段 | 百字节级 | 过长会被截断 |
| HTTP 映射 | 4xx / 5xx | 对外只暴露稳定码 |
internal/ 边界 | 路径段 | 以 internal 的父目录为根 |
| 导入环 | 编译期报错 | 不能靠运行时绕过 |
3 实践
3.1 最小示例
示例让一个包内函数分别产生哨兵错误与字段错误,在聚合层用 errors.Join 合并,在调用方用 Is 与 As 判断;另一个函数把除零 panic 转成 error。
package main
import (
"errors"
"fmt"
)
var (
ErrNotFound = errors.New("not found")
ErrInvalid = errors.New("invalid input")
)
type FieldError struct {
Field string
Err error
}
func (e *FieldError) Error() string { return e.Field + ": " + e.Err.Error() }
func (e *FieldError) Unwrap() error { return e.Err }
type Repo struct{ data map[string]string }
func (r *Repo) Get(id string) (string, error) {
if id == "" {
return "", &FieldError{Field: "id", Err: ErrInvalid}
}
v, ok := r.data[id]
if !ok {
return "", fmt.Errorf("get %q: %w", id, ErrNotFound)
}
return v, nil
}
func load(r *Repo, ids []string) (map[string]string, error) {
out := make(map[string]string)
var errs []error
for _, id := range ids {
v, err := r.Get(id)
if err != nil {
errs = append(errs, err)
continue
}
out[id] = v
}
return out, errors.Join(errs...)
}
func divide(a, b int) (q int, err error) {
defer func() {
if p := recover(); p != nil {
err = fmt.Errorf("divide panic: %v", p)
}
}()
return a / b, nil
}
func main() {
repo := &Repo{data: map[string]string{"u1": "ada", "u2": "lin"}}
got, err := load(repo, []string{"u1", "u2", "u3", ""})
fmt.Println(got) // map[u1:ada u2:lin]
fmt.Println(errors.Is(err, ErrNotFound), errors.Is(err, ErrInvalid)) // true true
var fe *FieldError
fmt.Println(errors.As(err, &fe), fe.Field) // true id
_, err = divide(1, 0)
fmt.Println(err) // divide panic: runtime error: integer divide by zero
}
追踪:load 对 u3 得到包装了 ErrNotFound 的错误,对空字符串得到 FieldError,它包装了 ErrInvalid。errors.Join 把两个错误合成一个多叉链;errors.Is 分别沿两条分支找到哨兵;errors.As 在第二条分支取出 *FieldError,fe.Field 为 id。divide 在 defer 中捕获除零 panic,转成普通 error 返回。
3.2 常用操作与参数
| 操作 | 命令 / API | 说明 |
|---|---|---|
| 创建哨兵 | errors.New("...") | 放在包级变量 |
| 带上下文包装 | fmt.Errorf("ctx: %w", err) | 每层只加一句上下文 |
| 判断哨兵 | errors.Is(err, ErrX) | 不要比较字符串 |
| 取类型 | errors.As(err, &target) | target 是非 nil 指针 |
| 合并 | errors.Join(errs...) | nil 被忽略 |
| 取单层原因 | errors.Unwrap(err) | 只取第一个 |
| 自定义判断 | func (e *E) Is(target error) bool | 谨慎使用,保持语义 |
| 恢复 | defer func() { recover() }() | 同一 goroutine |
| 标记弃用 | // Deprecated: use X. | 至少保留一个发布周期 |
| 限制导入 | internal/ | 只允许父树导入 |
3.3 标准流程
- 在产生错误的地方给出稳定标识:哨兵或自定义类型。
- 每跨一层只加一条上下文,用
%w保留原因。 - 在服务边界把错误映射成错误码、对外文案和可重试性。
- 日志记录完整链,对外只暴露安全信息。
- panic 只留在进程或 goroutine 入口,recover 后转成 error。
- 包只导出必要符号;不稳定的实现移入
internal/。 - 删除或改名导出标识符前先加弃用注释,破坏性变更走主版本。
3.4 与相邻技术的组合
- Interfaces and Generics:
error是单方法接口;errors.As依赖具体类型的指针接收者。 - Goroutines and Channels:子 goroutine 的错误通过 channel 或 errgroup 回到父级。
- Gin / Echo:handler 只返回领域错误,中间件统一映射状态码。
- Go Toolchain:
go vet检查 printf 动词与错误格式,staticcheck补充规则。 - Code Quality:错误码表与日志字段规范属于质量门禁的一部分。
3.5 选型维度
| 维度 | 取值 | 影响 |
|---|---|---|
| 错误粒度 | 哨兵 / 类型 / 包装 | 调用方判断方式 |
| 包装深度 | 每层 / 只在边界 | 可读性与可追溯性 |
| 对外暴露 | 完整原因 / 稳定码 | 安全与兼容 |
| 崩溃策略 | panic / error | 进程稳定性 |
| 包边界 | 导出 / internal | 依赖约束 |
| 版本策略 | 兼容新增 / 主版本 | 升级成本 |
3.6 决策规则
- 可预期的失败返回 error;不可恢复的编程错误才 panic。
- 调用方需要分支的条件用哨兵;需要携带字段的用自定义类型。
- 每层包装只加一句上下文,不要把整条链拼成字符串。
- 只在真正需要判断的边界使用
%w;否则%v更安全。 - 对外错误码与文案应稳定;内部原因只进日志。
- 包的导出面宜小;不为“以后可能用”提前导出。
- 破坏性变更走主版本,先弃用再删除。
3.7 替代方案对比
| 方案 | 优势 | 代价 | 适用 |
|---|---|---|---|
| 哨兵错误 | 比较简单 | 无法携带上下文 | 稳定条件 |
| 自定义类型 | 可带字段 | 类型多、耦合 | 领域错误 |
%w 包装 | 保留原因 | 暴露内部类型 | 跨层传播 |
errors.Join | 汇总多个失败 | 信息量大 | 批量操作 |
| panic/recover | 强制中断 | 难测试、跨 goroutine 失效 | 启动期致命错误 |
| 错误码 | 对外稳定 | 需维护映射 | API 边界 |
3.8 何时不该用
- 不要用字符串包含判断错误。
- 不要为每个函数造一个错误类型。
- 不要用 panic 表达业务分支。
- 不要在包初始化时做可能失败的 I/O。
- 不要把内部错误原样透传给客户端。
4 边界
4.1 典型故障
| 症状 | 根因 | 处理 |
|---|---|---|
| 日志里错误丢失原因 | 包装时用了 %v | 改用 %w 并记录链 |
errors.Is 永远为假 | 包装没有建立链 | 检查格式动词 |
errors.As panic | 目标不是指针或为 nil | 传 &target |
| 接口非 nil 的错误判空失败 | 返回了 nil 指针 | 返回 nil 接口 |
| goroutine panic 导致进程退出 | recover 不在该 goroutine | 在入口 defer recover |
| 导入环 | 包互相依赖 | 抽公共包或反向注入 |
| 外部能导入内部实现 | 缺少 internal/ | 移动目录 |
| 升级后编译失败 | 删除或改了导出签名 | 弃用周期加主版本 |
4.2 反模式
| 做法 | 后果 | 替代 |
|---|---|---|
全用 errors.New 不包装 | 丢失调用链 | 用 %w 加一层上下文 |
| 每层重复打印日志 | 日志重复 | 只在边界记录一次 |
| recover 后不记录 | 失败消失 | 记录并转成 error |
巨型 util 包 | 依赖混乱 | 按职责拆包 |
4.3 可观测信号
按错误码分组的比率、errors.Is 与 errors.As 未命中的计数、包装链深度分布、panic 次数与恢复次数、5xx 与 4xx 比例、日志中重复错误消息的比例、go list -deps 的包依赖规模、go vet 与 staticcheck 的报告数。
4.4 安全 / 性能 / 一致性边界
- 信息边界:原始错误可能含路径、SQL、主机名;对外只给稳定码与安全文案。
- panic 边界:recover 只对同一 goroutine 有效;其他 goroutine 的 panic 仍会终止进程。
- 兼容边界:导出标识符是 API;给接口加方法会破坏所有实现方。
- 初始化边界:
init不能返回错误;失败只能 panic,宜改用显式构造函数。 - 依赖边界:
internal/只约束导入路径,不提供运行时隔离。