Documentation
¶
Overview ¶
Package errors 提供带调用栈、错误码、上下文字段和结构化追踪的错误工具。
本包兼容标准库 errors.Is、errors.As、errors.Join、errors.Unwrap 和 errors.AsType 语义，并在包装标准库或第三方错误时补充可诊断的调用信息。
Index ¶
- func As(err error, target any) bool
- func AsType[T error](err error) (T, bool)
- func Cause(err error) error
- func Chain(err error) []error
- func Code(err error) (int, bool)
- func Errorf(format string, args ...any) error
- func HasCode(err error, code int) bool
- func HasMsg(err error, msg string) bool
- func HasStack(err error) bool
- func Is(err, target error) bool
- func Join(errs ...error) error
- func New(msg string) error
- func Root(err error) error
- func SetStackDepth(depth int) int
- func SetTraceEnabled(enabled bool) bool
- func Source(err error) error
- func Sources(err error) []error
- func StackDepth() int
- func Tag(err error) error
- func Trace(err error) slog.LogValuer
- func TraceEnabled() bool
- func TraceJSON(err error) string
- func TraceString(err error) string
- func Unwrap(err error) error
- func WithCode(err error, code int) error
- func WithContext(ctx context.Context, err error) error
- func WithContextErr(ctx context.Context, key, value string) context.Context
- func WithContextErrs(ctx context.Context, kvs ...string) context.Context
- func WithContextErrsE(ctx context.Context, kvs ...string) (context.Context, error)
- func WithMessage(err error, msg string) error
- func WithMessagef(err error, format string, args ...any) error
- func Wrap(err error, msg ...string) error
- func Wrapf(err error, format string, args ...any) error
- type Coder
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AsType ¶ added in v1.22.20
AsType 从错误链中提取第一个类型为 T 的错误。 语义对齐 Go 1.26 errors.AsType：按深度优先顺序遍历单链和多链错误。
类型参数说明：
- T：目标错误类型，必须实现 error 接口
func HasStack ¶ added in v1.22.15
HasStack 检查错误链路中是否已经存在追踪栈。 用于判断是否需要重复采集栈信息，避免 Wrap 时重复调用 runtime.Callers。
func Join ¶ added in v1.22.15
Join 合并多个错误，语义与标准库 errors.Join 完全一致。 合并后的错误支持 multiUnwrapper 接口，可通过 Unwrap() 获取所有子错误。
func SetStackDepth ¶ added in v1.22.15
SetStackDepth 设置每一层追踪错误捕获的最大栈帧数。 该设置为全局配置，只影响后续新创建的追踪错误，不影响已创建的错误对象。
边界处理规则：
- depth < 1 时，按 1 处理（最小栈深度）
- depth > maxStackDepth 时，按 maxStackDepth 处理（最大栈深度）
func SetTraceEnabled ¶ added in v1.22.15
SetTraceEnabled 设置是否输出链路追踪栈。 该设置为全局配置，只影响 TraceString/TraceJSON/fmt 格式化输出， 不影响错误的创建、比较和展开逻辑。
func Source ¶ added in v1.22.15
Source 返回错误链最底层的源错误。 沿错误链向下遍历，找到第一个不包含 unwrap 的错误节点。 对 Join 多错误场景，返回第一个非 nil 分支的源错误。
func StackDepth ¶ added in v1.22.15
func StackDepth() int
StackDepth 返回当前每一层追踪错误捕获的最大栈帧数。 该值控制 runtime.Callers 捕获栈帧的数量，影响栈追踪的详细程度和性能开销。
func Tag ¶ added in v1.22.16
Tag 统一包装任意类型的错误，智能判断是否需要添加追踪链路。 这是 Wrap 的增强版本，专门用于处理来自标准库或第三方包的错误。
err 为 nil 时直接返回 nil；错误已有追踪栈时直接返回原错误； 错误没有追踪栈时创建带追踪栈的新错误。
使用场景：
- 统一处理来自不同来源的错误（标准库、第三方包、本包错误）
- 确保所有错误都有完整的追踪链路，便于调试
- 避免对已有追踪的错误重复包装，提高性能
例如：
// 包装标准库错误
err := os.Open("file.txt") // 标准库错误，无追踪
wrappedErr := errors.Tag(err) // 现在有追踪链路了
// 包装已有追踪的错误
trackedErr := errors.New("already tracked") // 已有追踪
result := errors.Tag(trackedErr) // 直接返回原错误
func Trace ¶
Trace 返回适配 slog 的结构化追踪值。 返回的 slog.LogValuer 实现会在日志打印时延迟渲染错误信息。 日志输出包含 code、msg、ctx 等字段，可通过 SetTraceEnabled 控制是否输出 trace 数组。
Example (Disabled) ¶
package main
import (
"fmt"
"github.com/Is999/go-utils/errors"
)
func main() {
old := errors.TraceEnabled()
defer errors.SetTraceEnabled(old)
errors.SetTraceEnabled(false)
repository := func() error {
return errors.New("query cache failed")
}
service := func() error {
if err := repository(); err != nil {
return errors.WithMessage(err, "refresh profile failed")
}
return nil
}
handler := func() error {
if err := service(); err != nil {
return errors.WithCode(err, 30011)
}
return nil
}
err := handler()
fmt.Println(errors.TraceString(err))
}
Output: code=30011; cause=refresh profile failed; cause=query cache failed
Example (Enabled) ¶
package main
import (
"fmt"
"strings"
"github.com/Is999/go-utils/errors"
)
func main() {
repository := func() error {
return errors.New("load config failed")
}
service := func() error {
if err := repository(); err != nil {
return errors.Wrap(err, "bootstrap service failed")
}
return nil
}
handler := func() error {
if err := service(); err != nil {
return errors.WithCode(errors.WithMessage(err, "start app failed"), 50010)
}
return nil
}
err := handler()
fmt.Println(errors.Code(err))
fmt.Println(strings.Contains(errors.TraceJSON(err), `"trace"`))
fmt.Println(strings.Contains(errors.TraceJSON(err), `"msg":"start app failed"`))
}
Output: 50010 true true true
func TraceEnabled ¶ added in v1.22.15
func TraceEnabled() bool
TraceEnabled 返回当前是否输出链路追踪栈。 关闭追踪后，TraceString/TraceJSON 和 fmt 格式化输出将不包含 trace 字段， 但仍会输出错误链消息和错误码，可有效减少日志输出量和性能开销。
func TraceJSON ¶ added in v1.22.13
TraceJSON 返回结构化 JSON 追踪字符串，便于第三方日志或落盘。 JSON 结构包含 code（错误码）、msg（消息）、ctx（上下文）、trace（栈帧数组）等字段。 Join 多错误场景下使用 errs 数组扁平化输出，避免嵌套噪声。
func TraceString ¶ added in v1.22.13
TraceString 返回第三方日志库可直接打印的文本追踪。 格式为：code=xxx, msg=xxx @ file:line; cause=xxx @ file:line 使用预分配策略减少内存分配，追踪深度受 maxChainDepth 限制。
func WithCode ¶ added in v1.22.15
WithCode 为错误附加业务错误码，不采集调用栈。 设计的轻量级包装器，仅在错误上附加 code 信息，适合在业务入口处统一打码。 注意：即使多次 Wrap，错误码也不会覆盖，总是保留错误链中第一个 WithCode 设置的码。
func WithContext ¶ added in v1.22.15
WithContext 使用 context 中的值包装错误。 自动提取 ctx 中通过 WithContextErr/WithContextErrs 存储的键值对， 将其附加到错误链中，便于日志追踪和调试。
提取的 key-value 必须是字符串类型，确保兼容 slog 属性。 ctx 为 nil 或没有可提取值时直接返回原错误，不创建额外对象。
func WithContextErr ¶ added in v1.22.15
WithContextErr 将一对键值存储到 context 中。 存储的值后续会被 WithContext 自动提取并附加到错误链。 适用于在业务处理链中传递请求级标识（如 user_id、request_id）。
func WithContextErrs ¶ added in v1.22.15
WithContextErrs 批量将多对键值存储到 context 中。 出于稳定性考虑，奇数个参数时不会 panic，而是忽略最后一个不完整项。
注意：kvs 长度为奇数时，会忽略最后一个不完整项
func WithContextErrsE ¶ added in v1.22.15
WithContextErrsE 批量将多对键值存储到 context 中，并返回显式错误。 与 WithContextErrs 不同，当前函数在输入参数不完整时会返回错误，便于调用方感知配置问题。
func WithMessage ¶ added in v1.22.15
WithMessage 仅附加一层消息，不采集调用栈。 设计用于高频返回路径，避免每次 Wrap 都采集栈带来的性能开销。 错误链中会保留原始错误的栈信息。
func WithMessagef ¶ added in v1.22.15
WithMessagef 仅附加一层格式化消息，不采集调用栈。 同 WithMessage，但消息通过 fmt.Sprintf 动态生成。
Source Files