17370845950

统一错误处理的关键是错误类型可识别、上下文可携带、边界可拦截：应定义自定义错误类型并实现error接口和Is方法，用%w包装保留错误链，仅在HTTP/gRPC边界层转换为响应，禁止字符串匹配或降级错误类型。

多模块 Go 项目里，错误不该靠 fmt.Errorf 拼字符串传递，也不该让下游自己解析 error.Error() 内容做判断——统一错误处理的关键是「错误类型可识别、上下文可携带、边界可拦截」。

用自定义错误类型替代字符串拼接

不同模块抛出的错误如果都走 errors.New 或 fmt.Errorf，调用方只能靠字符串匹配判断错误类型，极易因文案微调而断裂。应为每类业务错误定义结构体，并实现 error 接口。

例如在 auth 模块中定义：

type InvalidTokenError struct {
    Token string
}

func (e *InvalidTokenError) Error() string {
    return "invalid token: " + e.Token
}

func (e *InvalidTokenError) Is(target error) bool {
    _, ok := target.(*InvalidTokenError)
    return ok
}

下游模块可用 errors.Is(err, &auth.InvalidTokenError{}) 安全判断，不依赖字符串内容。

• 所有模块的错误类型应放在各自 errors.go 文件中，导出但不暴露字段（用方法封装行为）
• 避免嵌套多个 fmt.Errorf("%w", err) 导致堆栈过深；用 fmt.Errorf("failed to parse config: %w", err) 仅在必要时加一层语义
• 不要在错误类型中存敏感信息（如原始密码、密钥），Error() 方法返回的内容可能被日志直接输出

跨模块传递错误时保留原始错误链

模块 A 调用模块 B，B 返回了 *auth.InvalidTokenError，A 不应转成 fmt.Errorf("auth failed: %w", err) 后再抛给上层——这会切断原始错误类型的可识别性。

正确做法是：只在需要补充上下文时包装，且确保 %w 保留底层错误，同时提供类型断言入口：

func (s *Service) ValidateUser(ctx context.Context, id string) error {
    err := s.authClient.VerifyToken(ctx, id)
    if err != nil {
        // 包装但不破坏原始类型
        return fmt.Errorf("user %s auth verification failed: %w", id, err)
    }
    return nil
}

上游仍可用 errors.Is(err, &auth.InvalidTokenError{}) 判断，因为 %w 保留了错误链。

• 禁止用 %v 或 %s 替代 %w 包装错误，否则原始错误对象丢失
• 若需记录错误但不向上抛，用 errors.Unwrap 或 errors.As 提取原始类型再处理，而非检查 err.Error()
• gRPC 或 HTTP handler 层是错误转换的合理位置，其他中间层尽量透传原始错误

在模块边界统一拦截并转换错误响应

HTTP handler 或 gRPC server 是错误出口，这里才该决定「用户看到什么」和「日志记什么」。各业务模块只负责返回带语义的错误类型，不关心序列化格式。

例如在 API 层集中处理：

func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
    err := h.service.DoSomething(r.Context())
    if err != nil {
        var authErr *auth.InvalidTokenError
        if errors.As(err, &authErr) {
            http.Error(w, "invalid token", http.StatusUnauthorized)
            return
        }

        var notFoundErr *storage.RecordNotFoundError
        if errors.As(err, ¬FoundErr) {
            http.Error(w, "not found", http.StatusNotFound)
            return
        }

        log.Printf("unhandled error: %+v", err)
        http.Error(w, "internal error", http.StatusInternalServerError)
        return
    }
    // ...
}

• 每个模块的错误类型应在主应用或 API 层显式 import，避免循环依赖（如把所有错误类型塞进一个 shared/errors 模块反而增加耦合）
• 不要在模块内部直接调用 log.Fatal 或写 panic，错误应向上传递到边界层统一决策
• 若使用 OpenAPI，可将常见错误类型映射为标准 HTTP 状态码 + JSON 错误体，保持对外契约稳定

最难的部分不是定义错误类型，而是坚持不在任意中间层做「错误降级」——比如把 *auth.Perm

issionDeniedError 转成通用 errors.New("forbidden")。只要有一处松动，整条链就失去类型可靠性。