统一错误处理的关键是错误类型可识别、上下文可携带、边界可拦截：应定义自定义错误类型并实现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{}) 安全判断，不依赖字符串内容。
立即学习“go语言免费学习笔记（深入）”；
- 所有模块的错误类型应放在各自
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.PermissionDeniedError 转成通用 errors.New("forbidden")。只要有一处松动，整条链就失去类型可靠性。
