Golang如何在多模块项目中统一错误处理_Golang模块间错误管理方法_技术教程

统一错误处理的关键是错误类型可识别、上下文可携带、边界可拦截：应定义自定义错误类型并实现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
    }
    // ...
}