Golang 结构化错误包装与元数据管理插件库 Fault 的使用

Fault 提供了一个可扩展且符合人体工程学的错误包装机制。它实现了一种称为"装饰器"的中间件风格模式：func(error) error。装饰器简单地将一个错误包装在另一个错误中，就像许多库所做的那样。

使用

包装错误

在调用栈上升时包装错误对于在出现问题时为团队提供足够的上下文至关重要。

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

Fault 提供的堆栈跟踪只关心相关的代码位置。当使用 %+v 格式化时，Fault 堆栈跟踪如下所示：

stdlib sentinel error
    /Users/southclaws/Work/fault/fault_test.go:34
failed to call function
    /Users/southclaws/Work/fault/fault_test.go:43
    /Users/southclaws/Work/fault/fault_test.go:52

如果你想添加上下文，可以使用 fmsg.With：

if err != nil {
    return fault.Wrap(err, fmsg.With("failed to do a thing"))
}

Fault 的真正强大之处在于可以组合多个包装器：

if err != nil {
    return fault.Wrap(err,
        fctx.With(ctx),          // 使用上下文中的键值元数据装饰错误
        ftag.With(ftag.NotFound), // 将错误分类为"未找到"
        fmsg.With("failed to do something", "There was a technical error while retrieving your account"), // 提供终端用户消息
    )
}

处理错误

包装错误只是故事的一半，最终你需要实际处理错误。Fault 提供了 Flatten 函数，允许你访问简单的堆栈跟踪和对根本原因错误的引用。

chain := Flatten(err)

• chain.Root - 错误链的根本原因
• chain.Errors - 错误链中包装的错误列表，其中第一项是根本原因的包装器

实用工具

fmsg

这个简单的实用程序允许你为错误链添加一组单独的消息，供开发人员和终端用户阅读。

extraContext := "extra context"
err := errors.New("root")
err = fault.Wrap(err, fmsg.With("one"))
err = fault.Wrap(err, fmsg.Withf("two (%s)", extraContext))
err = fault.Wrap(err, fmsg.With("three"))
fmt.Println(err)
// three: two (extra context): one: root

要为终端用户提供有用的错误描述，可以使用 fmsg.WithDesc：

if err != nil {
    return fault.Wrap(err,
        fmsg.WithDesc("permission denied", "The post is not accessible from this account."),
    )
}

获取终端用户消息：

issues := GetIssue(err)
// "The post is not accessible from this account."

fctx

错误上下文是 context 包和错误之间的缺失环节。上下文通常包含关于大规模应用程序中调用栈的元数据位，如跟踪 ID、请求 ID、用户 ID 等。

向上下文添加元数据

ctx = fctx.WithMeta(ctx, "trace_id", traceID)

用上下文元数据装饰错误

if err != nil {
    return fault.Wrap(err,
        fctx.With(ctx),
    )
}

访问元数据进行日志记录

ec := fctx.Unwrap(err)
logger.Error("http handler failed", ec)

ftag

这个实用程序只是用一个字符串注释整个错误链。这有助于用简单的标记对错误链进行分类，允许将错误映射到响应机制，如 HTTP 状态代码或 gRPC 状态代码。

if err != nil {
    return fault.Wrap(err,
        ftag.With(ftag.NotFound),
    )
}

获取错误类型：

ek := ftag.Get(err)
// ftag.NotFound = "NOT_FOUND"

switch ek {
  case ftag.NotFound:
    return http.StatusNotFound
  // others...
  default:
    return http.StatusInternalServerError
}

完整示例

package main

import (
	"context"
	"errors"
	"fmt"
	"net/http"

	"github.com/Southclaws/fault"
	"github.com/Southclaws/fault/fctx"
	"github.com/Southclaws/fault/fmsg"
	"github.com/Southclaws/fault/ftag"
)

func main() {
	// 创建一个带有元数据的上下文
	ctx := context.Background()
	ctx = fctx.WithMeta(ctx, "request_id", "12345")
	ctx = fctx.WithMeta(ctx, "user_id", "southclaws")

	// 模拟一个错误
	err := errors.New("database connection failed")

	// 包装错误并添加上下文
	err = fault.Wrap(err,
		fctx.With(ctx),
		ftag.With(ftag.Internal),
		fmsg.WithDesc("database error", "We're having technical difficulties. Please try again later."),
	)

	// 处理错误
	handleError(err)
}

func handleError(err error) {
	// 获取错误链
	chain := fault.Flatten(err)
	fmt.Printf("Root error: %v\n", chain.Root)

	// 获取错误类型并返回适当的HTTP状态
	ek := ftag.Get(err)
	status := httpStatusFromErrorKind(ek)
	fmt.Printf("HTTP Status: %d\n", status)

	// 获取终端用户消息
	issue := fmsg.GetIssue(err)
	fmt.Printf("User message: %s\n", issue)

	// 获取上下文元数据
	meta := fctx.Unwrap(err)
	fmt.Printf("Metadata: %v\n", meta)
}

func httpStatusFromErrorKind(kind ftag.Kind) int {
	switch kind {
	case ftag.NotFound:
		return http.StatusNotFound
	case ftag.PermissionDenied:
		return http.StatusForbidden
	case ftag.InvalidArgument:
		return http.StatusBadRequest
	case ftag.Internal:
		return http.StatusInternalServerError
	default:
		return http.StatusInternalServerError
	}
}

这个示例展示了如何使用 Fault 库来：

1. 创建带有元数据的上下文
2. 包装错误并添加上下文、标签和用户消息
3. 处理错误时获取错误链、错误类型、用户消息和元数据
4. 根据错误类型返回适当的 HTTP 状态码

Fault 提供了结构化错误处理和元数据管理的强大功能，同时保持了代码的简洁性和可读性。