1. 自定义错误类型的基本思路
本文聚焦于 Golang 自定义错误类型实战：如何实现 error 接口方法及高质量错误信息，围绕错误的封装、字段设计与统一输出格式展开。通过自定义错误类型，可以在不暴露实现细节的前提下，携带丰富的上下文信息，方便调用方进行错误分类与诊断。实现 error 接口的方法是基础，这是自定义错误的起点。
在 Go 语言中，错误是一个接口：type error interface { Error() string }。要创建自定义错误类型，需要让自定义类型实现 Error() string，从而满足 error 接口。与此同时，考虑到后续的错误检查和链路追溯，通常还会提供一个可选的 Unwrap 方法，用于保留根因并支持错误包装的传播。
错误类型的设计要点
字段设计：Code、Msg、Err（用于包裹根因）等，字段越清晰，调用方在日志和断言时越方便。输出的一致性，有助于统一的日志格式与告警规则。
一致的输出格式：尽量采用结构化的输出，比如统一的 Code 与 Msg 的组合，避免同一场景输出差异过大，提高可读性与可维护性。
package errorsimport "fmt"type AppError struct {Code intMsg stringErr error
}func (e *AppError) Error() string {if e == nil {return ""}if e.Err != nil {return fmt.Sprintf("[%d] %s: %v", e.Code, e.Msg, e.Err)}return fmt.Sprintf("[%d] %s", e.Code, e.Msg)
}// Unwrap 允许调用方通过 errors.Is / errors.As 进行根因分析
func (e *AppError) Unwrap() error { return e.Err }
2. 如何实现 error 接口的方法
要让自定义类型成为一个可用的 error，必须实现 Error() string。这一点是最基本的要求。为了实现更强的错误处理能力，建议结合错误包装（Wrap）与断言机制（Is/As）来增强可用性。
在设计时，可以将错误分层：最粗粒度的错误码和描述，以及可选的根因，确保外部能通过错误码快速定位问题，同时通过根因追踪具体原因。Error() 的实现应稳定且可预测，以便日志和监控的统计口径一致。
实现 Error 与包装的要点
核心要点包括：实现 Error()、提供 Unwrap() 以便进行错误链路分析、以及在需要时提供错误包装的能力。这些能力使上游调用方能够使用 errors.Is 和 errors.As 进行精准匹配。
package mainimport ("errors""fmt"
)type MyError struct {Code intMsg stringErr error
}func (e *MyError) Error() string {if e == nil {return ""}if e.Err != nil {return fmt.Sprintf("code %d: %s: %v", e.Code, e.Msg, e.Err)}return fmt.Sprintf("code %d: %s", e.Code, e.Msg)
}func (e *MyError) Unwrap() error { return e.Err }func main() {base := errors.New("timeout")err := &MyError{Code: 504, Msg: "request failed", Err: base}fmt.Println(err.Error())// 使用 errors.As 捕获具体类型var me *MyErrorif errors.As(err, &me) {fmt.Printf("Captured MyError with code=%d\n", me.Code)}// 使用 errors.Is 判断根因if errors.Is(err, base) {fmt.Println("Root cause is base error")}
}
3. 高质量错误信息的设计与实践
高质量的错误信息应具备上下文、可追溯性和可操作性。通过在 Error() 内部拼装结构化信息，或结合外部日志系统输出结构化字段，可以显著提升排查效率。不要暴露敏感实现细节，但要保留足够的上下文以定位问题。
设计时要关注信息的一致性与可扩展性：采用固定模板、统一错误码、以及可选的根因链路，确保未来扩展时兼容性良好。模板化消息与可观测的错误码，是维护大型系统的好方法。
信息结构与上下文
上下文字段：Operation、Resource、UserID、RequestID 等，帮助在日志中快速定位场景。分层次输出，在日志中按统一格式落地，方便聚合与告警。
以下示例展示如何把上下文信息融入错误输出，同时保留根因，便于上游系统进行错误聚合与分析。
type HTTPError struct {Op string // 操作，如 "GET /users"ID int // 资源标识Msg string // 描述性信息Err error // 根因
}func (e *HTTPError) Error() string {if e == nil {return ""}if e.Err != nil {return fmt.Sprintf("operation=%s id=%d: %s | cause=%v", e.Op, e.ID, e.Msg, e.Err)}return fmt.Sprintf("operation=%s id=%d: %s", e.Op, e.ID, e.Msg)
}func (e *HTTPError) Unwrap() error { return e.Err }
结合日志框架（如结构化日志）输出时，可以将 Operation、ID、Code、Msg 等字段作为独立字段落地，提升后续筛选能力。
错误信息的格式与最佳实践
在公共库中，推荐使用固定的错误码与文本模板，而非每次拼接自由文本。模板化消息可以减少歧义，便于跨团队协作与自动化告警。
var ErrNotFound = errors.New("not found")func fetch(id int) (User, error) {//...if somethingMissing {return User{}, &AppError{Code: 404, Msg: "user not found", Err: ErrNotFound}}//...return user, nil
}
4. 将错误集成到 API/库中
将错误对外暴露时，需保证语义清晰，并通过包装保留根因与上下文。错误变量（sentinel errors）与自定义错误类型结合使用，让调用方通过 errors.Is / errors.As 进行精准匹配与提取字段。
在库层实现时，建议统一返回自定义错误类型，并在需要时把底层错误包装进去，以提高可诊断性与可测试性。
对外暴露的错误类型与变量
通过导出错误变量（如 ErrNotFound）以及自定义错误类型组合使用，提供清晰的调用方判定入口。这样既能做快速匹配，也能通过字段获取更多信息。
var ErrNotFound = errors.New("not found")type AppError struct {Code intMsg stringErr error
}
此外，保持示例代码的自包含性，确保不会因为文档片段而出现未定义标识符。
使用 errors.Is / errors.As 的示例
通过错误包装，调用方可以使用 errors.Is 来判断根因，使用 errors.As 获取自定义错误类型的具体字段。
import ("errors""fmt"
)var ErrNotFound = errors.New("not found")type AppError struct {Code intMsg stringErr error
}func (e *AppError) Error() string {if e == nil {return ""}if e.Err != nil {return fmt.Sprintf("code=%d, msg=%s, cause=%v", e.Code, e.Msg, e.Err)}return fmt.Sprintf("code=%d, msg=%s", e.Code, e.Msg)
}func (e *AppError) Unwrap() error { return e.Err }func DoWork() error {base := ErrNotFoundreturn &AppError{Code: 404, Msg: "resource missing", Err: base}
}func main() {if err := DoWork(); err != nil {if errors.Is(err, ErrNotFound) {fmt.Println("Handled not found.")}var app *AppErrorif errors.As(err, &app) {fmt.Printf("Code: %d, Msg: %s\n", app.Code, app.Msg)}}
}
