在 go 中实现带元数据的自定义错误主要有三种方式。1. 定义包含元数据的结构体，如 code、message、reqid 等字段，并实现 error() 方法；2. 使用接口封装错误行为，通过定义 errorcode 接口和不同错误类型实现统一访问和处理；3. 结合错误包装和结构化信息，在返回新错误时保留原始错误并通过 unwrap 方法构建错误链，同时支持 json 序列化以适应 api 响应。这些方法使错误具备结构化上下文，提升可观测性和维护性。
在 Go 语言中，错误处理通常是通过 error 接口实现的。但标准库提供的错误信息往往只是一个字符串，缺乏结构化的元数据支持。如果你希望为错误添加上下文、状态码、错误ID等结构化数据，就需要自定义错误类型。
下面介绍几种常见方式，帮助你在 Go 中实现带元数据的自定义错误。
定义包含元数据的错误结构体
最直接的方式是定义一个结构体，包含你需要的错误信息和元数据字段，比如错误消息、错误代码、错误ID、请求ID等。
立即学习“go语言免费学习笔记（深入）”；
type MyError struct {
Code int
Message string
ReqID string
}
func (e MyError) Error() string {
return e.Message
}使用时可以这样构造错误：
err := MyError{
Code: 400,
Message: "invalid input",
ReqID: "abc123",
}这种方式适合需要将错误信息传递给上层处理逻辑（如中间件或日志系统）的情况，结构化的字段可以直接被提取使用。
使用接口封装错误行为与数据
如果你的应用中有多种类型的错误，每种错误可能有不同的元数据需求，可以考虑使用接口来统一访问错误的结构化数据。
例如：
type ErrorCode interface {
Error() string
Code() int
}
type AuthError struct {
Msg string
Code int
}
func (e AuthError) Error() string {
return e.Msg
}
func (e AuthError) Code() int {
return e.Code
}这样你就可以根据不同错误类型做判断和处理：
if e, ok := err.(ErrorCode); ok {
log.Printf("error code: %d", e.Code())
}这种方法在大型项目中很实用，尤其是当你需要根据错误类型进行不同响应（比如返回 HTTP 状态码）时。
结合 fmt.Errorf 和 %w 包装错误链
Go 1.13 引入了错误包装功能，可以通过 %w 标记将原始错误保留在新错误中，从而构建错误链。
你可以结合结构化错误一起使用：
type DBError struct {
Message string
Query string
Err error
}
func (e DBError) Error() string {
return e.Message
}
func (e DBError) Unwrap() error {
return e.Err
}然后这样包装错误：
_, err := db.Query("SELECT * FROM users")
if err != nil {
return DBError{
Message: "database query failed",
Query: "SELECT * FROM users",
Err: err,
}
}这样既保留了原始错误，也加入了结构化的上下文信息，便于排查问题。
错误序列化输出（比如 JSON）
有时候我们需要把错误以 JSON 形式返回给客户端（如 REST API），这时候可以让错误结构体实现 json.Marshaler 接口。
type APIError struct {
Code int
Message string
ReqID string
}
func (e APIError) Error() string {
return e.Message
}
func (e APIError) MarshalJSON() ([]byte, error) {
return json.Marshal(map[string]interface{}{
"code": e.Code,
"message": e.Message,
"req_id": e.ReqID,
})
}在 HTTP 处理函数中，可以直接返回这个错误对象并序列化成 JSON 响应。
基本上就这些方法。结构化错误的核心在于：把错误当作一种携带上下文的数据结构来处理，而不是仅仅是一个字符串。用好这一点，能显著提升程序的可观测性和可维护性。
