Go 错误链处理实战：用 errors.Is 和 errors.As 保留根因

Go 项目里最容易被低估的地方之一，就是错误处理。很多代码一开始只是简单 return err，后来业务层、仓储层、HTTP 层都在补日志和判断字符串，最后线上排查时只看到“查询失败”，却不知道根因是记录不存在、数据库超时，还是参数不合法。

Go 1.13 之后，标准库提供了 errors.Is、errors.As 和 %w 错误包装能力。合理使用它们，可以同时保留底层根因、上层上下文和对外业务码。本文用一个订单查询接口做例子，把这套错误链处理流程走一遍。

摘要

本文会完成三个目标：定义可判断的哨兵错误，给业务错误加上状态码和提示文案，在 HTTP 层通过 errors.Is 和 errors.As 统一映射响应。适合已经能写 Go Web 接口，但错误处理还比较散的开发者阅读。

适合人群

• Go 项目里经常用字符串判断错误的同学。
• 希望日志能看到根因，对外响应又不泄露内部细节的后端开发者。
• 正在整理 Service、Repository、Handler 分层错误规范的团队。

目录

• 为什么不要直接丢失根因
• 用 %w 包装错误，保留调用链上下文
• 用 errors.Is 判断固定根因
• 用 errors.As 提取业务错误
• HTTP 层统一映射响应
• 常见坑和总结

为什么不要直接丢失根因

先看一个常见写法：

func (s *OrderService) GetOrder(ctx context.Context, id int64) (*Order, error) {
    order, err := s.repo.FindByID(ctx, id)
    if err != nil {
        return nil, errors.New("查询订单失败")
    }
    return order, nil
}

这段代码的问题是：底层错误被完全覆盖了。仓储层可能返回“订单不存在”，也可能返回数据库连接超时，但上层只剩一句“查询订单失败”。日志、告警、接口响应都很难做精细处理。

更好的做法是：底层错误作为根因保留，上层只补充当前步骤的上下文。

用 %w 包装错误，保留调用链上下文

fmt.Errorf 的 %w 可以把原始错误包进新的错误里。这样错误信息有上下文，程序也还能识别根因。

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

type OrderRepo struct{}

func (r *OrderRepo) FindByID(ctx context.Context, id int64) (*Order, error) {
    if id == 404 {
        return nil, ErrOrderNotFound
    }
    return &Order{ID: id, Amount: 19900}, nil
}

type OrderService struct {
    repo *OrderRepo
}

func (s *OrderService) GetOrder(ctx context.Context, id int64) (*Order, error) {
    order, err := s.repo.FindByID(ctx, id)
    if err != nil {
        return nil, fmt.Errorf("get order %d from repo: %w", id, err)
    }
    return order, nil
}

最终日志里可以看到“get order 404 from repo: order not found”，同时上层依然可以判断它是不是 ErrOrderNotFound。

用 errors.Is 判断固定根因

当底层错误是一个固定哨兵值，比如记录不存在、权限不足、状态不允许，可以用 errors.Is 判断。

func handleServiceError(err error) (int, string) {
    switch {
    case errors.Is(err, ErrOrderNotFound):
        return http.StatusNotFound, "订单不存在"
    default:
        return http.StatusInternalServerError, "系统繁忙，请稍后再试"
    }
}

errors.Is 会沿着错误链往里找，即使错误被包装了多层，也能识别真正的根因。它比字符串包含判断可靠得多，也更适合重构。

用 errors.As 提取业务错误

有些错误不只是一个固定值，还需要带业务码、HTTP 状态码、用户提示。这时可以定义结构体错误，并用 errors.As 提取。

type BizError struct {
    Code    string
    Message string
    Status  int
}

func (e *BizError) Error() string {
    return e.Code + ": " + e.Message
}

func NewBizError(code, message string, status int) error {
    return &BizError{Code: code, Message: message, Status: status}
}

func validateOrderID(id int64) error {
    if id 

上层处理时不关心它被包装了几层，只要链上有 *BizError，就能提取出来。

func mapError(err error) (int, string) {
    var biz *BizError
    if errors.As(err, &biz) {
        return biz.Status, biz.Message
    }

    if errors.Is(err, ErrOrderNotFound) {
        return http.StatusNotFound, "订单不存在"
    }

    return http.StatusInternalServerError, "系统繁忙，请稍后再试"
}

HTTP 层统一映射响应

Handler 里不要到处写一堆 if err != nil 分支。推荐把映射逻辑集中到一个函数里，让 Service 只负责业务语义，Handler 负责协议响应。

func GetOrderHandler(service *OrderService) http.HandlerFunc {
    return func(w http.ResponseWriter, r *http.Request) {
        ctx := r.Context()
        id := int64(404)

        order, err := service.GetOrder(ctx, id)
        if err != nil {
            status, message := mapError(err)
            writeJSON(w, status, map[string]any{
                "message": message,
            })
            return
        }

        writeJSON(w, http.StatusOK, order)
    }
}

func writeJSON(w http.ResponseWriter, status int, body any) {
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(status)
    _ = json.NewEncoder(w).Encode(body)
}

这种方式有一个好处：日志可以记录完整错误链，对外只返回稳定提示。比如内部日志是“get order 404 from repo: order not found”，用户看到的是“订单不存在”。

常见坑

• 包装错误时忘了 %w。 如果用了 %v，错误文本还在，但链断了，errors.Is 和 errors.As 就找不到根因。
• 到处定义重复哨兵错误。 同一个业务根因应该复用同一个错误值，避免判断失败。
• 对外直接返回内部错误。 数据库、缓存、文件路径等内部细节不要暴露给用户。
• 日志只记用户提示。 用户提示适合前端展示，排障日志要保留完整错误链。

推荐落地规范

• Repository 层返回明确根因，例如记录不存在、唯一键冲突、连接超时。
• Service 层用 %w 包装上下文，不随意覆盖错误。
• Handler 层统一通过 mapError 转成 HTTP 状态码和用户提示。
• 日志记录完整错误链，响应只返回稳定业务文案。

总结

Go 的错误链处理并不复杂，关键是不要把根因丢掉。用 %w 保留调用链，用 errors.Is 判断固定根因，用 errors.As 提取业务错误，再在 HTTP 层统一映射响应。这样代码更容易维护，线上排查也会更清楚。