Go语言需扩展error接口以支持结构化错误码，推荐定义含Code()方法的整型码结构体，确保实现Error()和Unwrap()以便errors.Is/As正确识别，并分层设计码值、避免动态拼接，统一在日志与gRPC中透传。
Go 语言原生的 error 接口不带错误码，直接用字符串描述错误（如 errors.New("not found")）无法结构化识别问题类型。要支持错误分类、日志聚合、前端提示映射或 RPC 错误透传，必须自己扩展错误类型——核心是让错误值携带可比较的错误码，并保持与标准库兼容。
定义带错误码的自定义错误类型
最常用方式是定义一个结构体，嵌入 error 字段或实现 Error() 方法，同时暴露 Code() 方法返回整型或字符串码。推荐用整型码（如 HTTP 状态码风格），便于数值比较和 switch 判断。
type CodeError struct {
code int
msg string
}
func (e *CodeError) Error() string { return e.msg }
func (e *CodeError) Code() int { return e.code }
var (
ErrNotFound = &CodeError{code: 404, msg: "resource not found"}
ErrInvalid = &CodeError{code: 400, msg: "invalid parameter"}
)
注意：不要用指针接收者定义 Code() 时返回值为 int，否则 fmt.Printf("%v", err) 可能 panic（未实现 error 接口）。确保结构体显式实现 error 接口（即有 Error() string 方法）。
用 errors.Is / errors.As 判断带码错误
Go 1.13+ 的 errors.Is 和 errors.As 支持自定义错误的链式判断。但前提是你的错误类型实现了 Unwrap() error（用于包装）或正确响应 Is(target error) bool。
立即学习“go语言免费学习笔记（深入）”；
- 若只做简单错误码判断，无需包装，可直接在
Is中比对指针：errors.Is(err, ErrNotFound) - 若需从包装错误中提取原始码（例如
fmt.Errorf("failed: %w", ErrNotFound)），则必须实现Unwrap() error：
func (e *CodeError) Unwrap() error { return nil } // 表示无下层错误
// 或包装时返回被包装错误：
func WrapCode(err error, code int, msg string) error {
return &wrappedCodeError{
code: code,
msg: msg,
err: err,
}
}
type wrappedCodeError struct {
code int
msg string
err error
}
func (e *wrappedCodeError) Error() string { return e.msg }
func (e *wrappedCodeError) Code() int { return e.code }
func (e *wrappedCodeError) Unwrap() error { return e.err }
此时 errors.As(err, &target) 才能成功把底层 *CodeError 提取出来。
避免在错误码中混用业务状态和系统错误
错误码不是 HTTP 状态码的简单复刻。常见误区是把所有“失败”都塞进 Code()，比如数据库连接失败返回 500、用户未登录也返回 500，导致上层无法区分是重试还是跳转登录页。
- 建议分层设计：定义公共错误码常量集（如
CodeDBConnection = 1001）、业务错误码（如CodeUserNotActive = 2001） - HTTP 层再做一次映射：不是所有
CodeDBConnection都返回 500，某些场景可降级为 404 或 429 - 禁止在
Code()返回值里动态拼接数字（如return 400 + id），这破坏可枚举性和日志分析能力
日志与 gRPC 场景下的错误码透传
日志中仅打印 err.Error() 会丢失码信息；gRPC 的 status.Code 要求明确映射。关键是在日志打点和 RPC 响应前，先提取并结构化错误码。
// 日志示例（使用 zap）
if ce, ok := errors.Cause(err).(*CodeError); ok {
logger.Error("operation failed", zap.Int("code", ce.Code()), zap.String("msg", ce.Error()))
} else {
logger.Error("unknown error", zap.Error(err))
}
// gRPC server 示例
func (s *Service) Do(ctx context.Context, req *pb.Request) (*pb.Response, error) {
err := s.biz.Do(req)
if err != nil {
if ce, ok := err.(*CodeError); ok {
return nil, status.Error(codes.Code(ce.Code()), ce.Error())
}
return nil, status.Error(codes.Internal, err.Error())
}
return &pb.Response{}, nil
}
注意 errors.Cause 来自 github.com/pkg/errors，Go 1.20+ 更推荐用 errors.Unwrap 循环获取最底层错误，但需小心无限循环（包装层数过多或循环引用）。
错误码真正起作用的地方不在定义那一刻，而在所有调用方一致检查 err.(interface{ Code() int }) 或用 errors.As 提取的那一刻。漏掉一处类型断言，整个码体系就断了。
