封装error工具包可解决Go原生错误信息单一、无堆栈、难分类等问题，通过定义包含错误码、消息、堆栈、时间等字段的Error结构体，实现NewError和Wrap函数以创建和包装错误，支持Unwrap和Error接口兼容标准库；使用时能携带上下文并追踪错误链，结合结构化日志输出，提升错误定位与维护效率。
在 Go 语言开发中，错误处理是程序健壮性的核心部分。由于 Go 原生采用返回 error 的方式处理异常，随着项目规模扩大，散落在各处的 if err != nil 和缺乏上下文的错误信息会显著降低可维护性。因此，封装一个统一、结构化的 error 工具包非常必要。
一、设计目标：为什么要封装 error 工具包？
原生 error 接口虽然简单，但在实际工程中存在以下痛点：
- 错误信息单一，缺少堆栈、时间、上下文等关键信息
- 无法区分错误类型（如网络错误、数据库错误、业务错误）
- 跨服务调用时难以追踪错误源头
- 日志中难以定位具体出错位置
为此，一个良好的 error 工具包应具备以下能力：
二、核心结构设计：定义统一错误类型
我们可以定义一个结构体来承载丰富的错误信息：
立即学习“go语言免费学习笔记（深入）”；
type Error struct {code int
message string
cause error
stack string
time time.Time
}
字段说明：
- code：错误码，用于程序判断或前端识别
- message：用户可读的错误描述
- cause：原始错误，实现错误链（error wrapping）
- stack：运行时堆栈快照，可用 runtime.Caller 获取
- time：错误发生时间，便于日志分析
三、关键功能实现
基于上述结构，提供一组易用的工具函数：
NewError(code int, msg string) *Error
创建基础错误，自动记录时间和堆栈：
func NewError(code int, msg string) *Error {
_, file, line, _ := runtime.Caller(1)
return &Error{
code: code,
message: msg,
stack: fmt.Sprintf("%s:%d", file, line),
time: time.Now(),
}
}
Wrap(err error, code int, msg string) *Error
包装已有错误，保留原始错误链：
func Wrap(err error, code int, msg string) *Error {if err == nil {
return nil
}
e := NewError(code, msg)
e.cause = err
return e
}
(e *Error) Unwrap() error
实现 Go 1.13+ 的 errors.Unwrap 接口，支持 errors.Is 和 errors.As：
func (e *Error) Unwrap() error {return e.cause
}
(e *Error) Error() string
实现 error 接口，返回可读字符串：
func (e *Error) Error() string {if e.cause != nil {
return fmt.Sprintf("[%d] %s: caused by %v", e.code, e.message, e.cause)
}
return fmt.Sprintf("[%d] %s", e.code, e.message)
}
四、使用示例与最佳实践
在实际代码中这样使用：
func GetUser(id int) (*User, error) {user, err := db.Query("SELECT ... WHERE id = ?", id)
if err != nil {
return nil, errorutil.Wrap(err, 5001, "failed to query user")
}
if user == nil {
return nil, errorutil.NewError(4041, "user not found")
}
return user, nil
}
在日志或中间件中打印完整错误链：
for curr := err; curr != nil; curr = errors.Unwrap(curr) {if appErr, ok := curr.(*errorutil.Error); ok {
log.Printf("Code: %d, Msg: %s, Stack: %s, Time: %v",
appErr.Code(), appErr.Message(), appErr.Stack(), appErr.Time())
}
}
五、进阶建议
- 可引入 errors.Cause 模式（类似 github.com/pkg/errors），提取根因
- 结合 zap 或 slog 等结构化日志库输出 JSON 格式错误
- 预定义常见错误码常量，如 ErrDatabaseFailure、ErrNetworkTimeout
- 在 HTTP 中间件中统一拦截并返回 JSON 错误响应
基本上就这些。一个好的 error 工具包不复杂但容易忽略细节，关键是保持简洁、兼容标准库，并为错误注入足够上下文，让排查问题变得高效直观。
