Golang 错误处理增强插件库 oops 的使用

Oops 是一个全面的 Go 错误处理库，提供带有丰富上下文信息的结构化错误管理。它设计为 Go 内置 error 的替代品，添加了强大的功能，如堆栈跟踪、源代码片段、结构化属性和开发者友好的调试提示。

🎯 主要特性

• 🔧 无缝替代：无缝替换标准 Go 错误处理
• 📊 丰富上下文：添加结构化属性、用户信息
• 🐛 调试友好：开箱即用的堆栈跟踪和源代码片段
• 🔗 错误链：用额外上下文包装和组合错误
• 🛡️ 恐慌恢复：内置 panic 处理与错误转换
• ✅ 断言：用于验证的单行断言辅助
• ⚡ 性能：零依赖、轻量且快速
• 📝 日志集成：适用于所有主流 Go 日志库
• ✂️ 关注点分离：错误处理和日志记录是分开的工作
• 🍳 易集成：无需大规模重构

🚀 安装

go get github.com/samber/oops

💡 快速开始

基础示例

import "github.com/samber/oops"

func main() {
    // 带上下文的简单错误
    err := oops.
        In("user-service").
        Tags("database", "postgres").
        Code("network_failure").
        User("user-123", "email", "foo@bar.com").
        With("path", "/hello/world").
        Errorf("failed to fetch user: %s", "connection timeout")
    
    // 错误包装
    if err != nil {
        return oops.
            Trace("req-123").
            With("product_id", "456").
            Wrapf(err, "user operation failed")
    }
}

错误构建器方法

上下文构建器方法

🧠 完整示例

错误包装示例

// 带错误包装
err0 := oops.
    In("repository").
    Tags("database", "sql").
    Wrapf(sql.Exec(query), "could not fetch user")  // 当 sql.Exec() 为 nil 时 Wrapf 返回 nil

// 带 panic 恢复
err1 := oops.
    In("repository").
    Tags("database", "sql").
    Recover(func () {
        panic("caramba!")
    })

// 带断言
err2 := oops.
    In("repository").
    Tags("database", "sql").
    Recover(func () {
        // ...
        oops.Assertf(time.Now().Weekday() == 1, "This code should run on Monday only.")
        // ...
    })

// oops.New
err3 := oops.
    In("repository").
    Tags("database", "sql").
    New("an error message")

// oops.Errorf
err4 := oops.
    In("repository").
    Tags("database", "sql").
    Errorf("an error message: %d", 42)

上下文丰富示例

// 带公共面向消息的简单错误
err0 := oops.
    Public("Could not fetch user.").
    Errorf("sql: bad connection")

// 带可选域的简单错误
err2 := oops.
    In("repository").
    Tags("database", "sql").
    Errorf("could not fetch user")

// 带自定义属性
ctx := context.WithContext(context.Background(), "a key", "value")
err3 := oops.
    With("driver", "postgresql").
    With("query", query).
    With("query.duration", queryDuration).
    With("lorem", func() string { return "ipsum" }).    // 延迟评估
    WithContext(ctx, "a key", "another key").
    Errorf("could not fetch user")

// 带 trace+span
err4 := oops.
    Trace(traceID).
    Span(spanID).
    Errorf("could not fetch user")

// 带提示和所有权，帮助开发者解决问题
err5 := oops.
    Hint("The user could have been removed. Please check deleted_at column.").
    Owner("Slack: #api-gateway").
    Errorf("could not fetch user")

Panic 处理示例

func mayPanic() {
    panic("permission denied")
}

func handlePanic() error {
    return oops.
        Code("iam_authz_missing_permission").
        In("authz").
        With("permission", "post.create").
        Trace("6710668a-2b2a-4de6-b8cf-3272a476a1c9").
        Hint("Runbook: https://doc.acme.org/doc/abcd.md").
        Recoverf(func() {
            // ...
            mayPanic()
            // ...
        }, "unexpected error %d", 42)
}

断言示例

func mayPanic() {
    x := 42

    oops.
        Trace("6710668a-2b2a-4de6-b8cf-3272a476a1c9").
        Hint("Runbook: https://doc.acme.org/doc/abcd.md").
        Assertf(time.Now().Weekday() == 1, "This code should run on Monday only.").
        With("x", x).
        Assertf(x == 42, "expected x to be equal to 42, but got %d", x)

    oops.Assert(re.Match(email))
    // ...
}

func handlePanic() error {
    return oops.
        Code("iam_authz_missing_permission").
        In("authz").
        Recover(func() {
            // ...
            mayPanic()
            // ...
        })
}

📫 日志集成

一些日志器可能需要自定义格式化程序来从 oops.OopsError 中提取属性。

可用日志器：

• log
• slog
• logrus
• zerolog

🥷 最佳实践

公共面向错误消息

err := oops.
    Public("Could not fetch user.").
    Errorf("sql: bad connection")

userMessage := oops.GetPublic(err, "Unexpected error")

错误构建器重用

errorBuilder := oops.
    In("iam").
    Trace("77cb6664").
    With("hello", "world")

err := mayFail1()
if err != nil {
    return errorBuilder.Wrap(err)
}

err = mayFail2()
if err != nil {
    return errorBuilder.Wrap(err)
}

return errorBuilder.Wrap(mayFail3())

调用者/被调用者属性

func a() error {
    return b()
}

func b() error {
    return oops.
        In("iam").
        Trace("4ea76885-a371-46b0-8ce0-b72b277fa9af").
        With("hello", "world").
        Wrapf(c(), "something failed")
}

func c() error {
    return d()
}

func d() error {
    return oops.
        Code("iam_missing_permission").
        In("authz").
        Time(time.Now()).
        With("permission", "post.create").
        Hint("Runbook: https://doc.acme.org/doc/abcd.md").
        User("user-123", "firstname", "john", "lastname", "doe").
        Tenant("organization-123", "name", "Microsoft").
        Errorf("permission denied")
}

Oops 提供了强大的错误处理能力，可以帮助开发者创建更结构化、更易于调试的错误信息。通过丰富的上下文信息和堆栈跟踪，可以大大简化错误诊断过程。