Go 语言错误处理:哨兵错误、错误包装与错误链判断的完整做法

举报
XIANG.FAN 发表于 2026/11/09 08:35:41 2026/11/09
【摘要】 本文介绍 Go 语言错误处理的完整做法:用哨兵错误定性、用 fmt.Errorf 的百分之 w 动词包装保留错误链、用 Is 方法判断错误类型、用 As 方法提取结构化错误中的字段,并给出落地检查清单。

在 Go 语言里,错误不是异常,而是一个普通的值。很多服务上线后最难排查的问题,并不是错误本身,而是错误信息在层层传递中被丢掉了上下文:日志里只剩一句“操作失败”,却不知道是哪一层、哪个资源、因为什么原因失败的。本文结合一个订单查询服务的例子,讲清楚哨兵错误、错误包装、Is 方法与 As 方法的正确用法。

一、先定义哨兵错误:让错误可以被识别

哨兵错误就是预先定义好的错误值,调用方可以用它判断错误的类型,而不是去比对错误字符串。字符串一旦改写,判断就失效了;哨兵错误则稳定得多。

package order

import "errors"

var (
    ErrOrderNotFound = errors.New("order not found")
    ErrOrderCanceled = errors.New("order canceled")
)

func GetOrder(id string) (*Order, error) {
    if id == "" {
        return nil, errors.New("order id is empty")
    }
    // 假设这里查询数据库,未查到记录
    return nil, ErrOrderNotFound
}

调用方判断时,不要用 err.Error() == “order not found” 这种写法,而应该用 Is 方法。原因在下一节会讲到:错误一旦被包装,字符串会变长,直接比较字符串就匹配不上了。

二、用 fmt.Errorf 的百分之 w 动词包装错误:保留链路,不丢上下文

Go 1.13 引入的百分之 w 动词,会把原始错误包装进新错误,形成一条错误链。每一层只补充自己知道的信息,不改写原始错误。

func LoadOrder(id string) (*Order, error) {
    order, err := GetOrder(id)
    if err != nil {
        return nil, fmt.Errorf("load order %s: %w", id, err)
    }
    return order, nil
}

func HandleRequest(id string) error {
    _, err := LoadOrder(id)
    if err != nil {
        return fmt.Errorf("handle order request: %w", err)
    }
    return nil
}

最终打印出来的错误是“handle order request: load order 123: order not found”,从外到内完整保留了调用链。排查时一眼就能看到请求处理、加载订单、记录不存在这三层信息。要注意两点:第一,不要用百分之 v 动词包装,它会断开错误链;第二,不要在每一层都把错误重新描述一遍,重复的信息只会让日志更难读。

三、用 Is 方法判断:穿透包装找哨兵错误

Is 方法会沿着错误链逐层解包,只要链上任何一层是目标哨兵错误,就返回 true。即使中间被包装了三次,判断依然成立。

err := HandleRequest("123")
if errors.Is(err, ErrOrderNotFound) {
    // 返回 404,而不是 500
    fmt.Println("订单不存在")
} else if errors.Is(err, ErrOrderCanceled) {
    fmt.Println("订单已取消")
}

这就是在 HTTP 服务里区分 404 和 500 的正确做法:业务语义由哨兵错误携带,表现层只做判断,不解析错误字符串。顺带一提,Is 方法也支持自定义的 Is 方法,如果你的错误类型需要特殊的相等逻辑,可以实现 Is(target error) bool。

四、用 As 方法提取:拿到结构化错误里的字段

有些错误不只是“是哪一类”,还携带了额外信息,比如哪个字段校验失败、重试前要等多久。这时应该定义一个错误类型,再用 As 方法把它从链里取出来。

type ValidationError struct {
    Field   string
    Message string
}

func (e *ValidationError) Error() string {
    return fmt.Sprintf("field %s: %s", e.Field, e.Message)
}

func Validate(order *Order) error {
    if order.Amount <= 0 {
        return &ValidationError{Field: "amount", Message: "金额必须大于 0"}
    }
    return nil
}

// 调用方提取
var verr *ValidationError
if errors.As(err, &verr) {
    fmt.Printf("校验失败的字段是 %s\n", verr.Field)
}

As 方法的目标必须是指针的指针,上面例子里传入的是 &verr,verr 本身是 *ValidationError 类型。写错类型会导致 As 方法返回 false,却没有编译错误,这是新手最容易踩的坑。

五、落地清单:写错误处理时对照检查

第一,底层返回哨兵错误或结构化错误,不要只返回一句含糊的 errors.New。第二,每一层用百分之 w 动词补充本层信息,不要吞掉原始错误,也不要把错误打印后又原样返回造成重复日志。第三,判断错误类型用 Is 方法,提取错误细节用 As 方法,不要比对字符串。第四,错误信息要写给排查的人看:写清“在做什么、操作了哪个资源、失败原因是什么”,而不是只写“失败了”。第五,区分“预期错误”和“系统故障”:订单不存在是预期内的业务状态,返回 404;数据库连接失败是系统故障,需要告警并返回 500。

结语

Go 的错误处理没有魔法,核心就是三条线:用哨兵错误定性,用百分之 w 动词包装保留链路,用 Is 方法和 As 方法在调用方做判断和提取。把这三点坚持下来,服务出问题时,日志里的错误链本身就是一份排查路线图。

【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。