Golang实现跨网络错误传输的错误处理插件库errors的使用

cockroachdb/errors是一个Go语言的错误处理库，旨在作为github.com/pkg/errors和Go标准errors包的替代品。它提供了错误对象的网络可移植性，适合分布式系统和混合版本软件兼容性。

主要特性

• 错误构造函数(New, Errorf等)
• 错误原因(Cause/Unwrap)
• 原因屏障(Opaque/Handled)
• errors.As(), errors.Is()
• 自动错误包装(当格式以: %w结尾时)
• 带高效堆栈跟踪捕获的标准包装器
• 透明的protobuf编码/解码与向前兼容
• errors.Is()可识别跨网络的错误
• 全面的PII-free详情支持
• 同时支持Cause()和Unwrap()
• 标准错误报告到Sentry.io

如何使用

基本使用示例

package main

import (
	"fmt"
	"github.com/cockroachdb/errors"
)

func main() {
	// 创建基础错误
	err := errors.New("initial error")
	
	// 包装错误
	err = errors.Wrap(err, "wrapped message")
	
	// 测试错误标识
	if errors.Is(err, errors.New("initial error")) {
		fmt.Println("Error matches!")
	}
	
	// 打印详细错误信息
	fmt.Printf("%+v\n", err)
}

跨网络错误传输示例

package main

import (
	"context"
	"fmt"
	"github.com/cockroachdb/errors"
	"google.golang.org/protobuf/proto"
)

func main() {
	// 创建错误
	originalErr := errors.New("database connection failed")
	wrappedErr := errors.Wrap(originalErr, "operation failed")
	
	// 编码错误
	encoded := errors.EncodeError(context.Background(), wrappedErr)
	
	// 模拟网络传输 - 这里encoded可以序列化为protobuf并通过网络发送
	// 在接收端解码错误
	decodedErr := errors.DecodeError(context.Background(), encoded)
	
	// 即使通过网络传输，errors.Is()仍然有效
	if errors.Is(decodedErr, originalErr) {
		fmt.Println("Successfully recognized error across network!")
	}
	
	fmt.Printf("Decoded error details: %+v\n", decodedErr)
}

带安全详情的错误示例

package main

import (
	"fmt"
	"github.com/cockroachdb/errors"
)

func main() {
	// 创建带安全详情的错误
	err := errors.Newf("user error: %s", errors.Safe("user123"))
	
	// 获取安全详情
	safeDetails := errors.GetSafeDetails(err)
	fmt.Printf("Safe details: %v\n", safeDetails)
	
	// 报告到Sentry
	report := errors.ReportError(err)
	fmt.Printf("Sentry report: %s\n", report)
}

自定义错误类型示例

package main

import (
	"fmt"
	"github.com/cockroachdb/errors"
	"github.com/gogo/protobuf/proto"
)

// 自定义错误类型
type CustomError struct {
	Code    int
	Message string
}

func (e *CustomError) Error() string {
	return fmt.Sprintf("custom error %d: %s", e.Code, e.Message)
}

// 注册解码函数
func init() {
	errors.RegisterLeafDecoder((*CustomError)(nil), func(_ context.Context, msg string, _ []string, _ proto.Message) error {
		// 这里简化处理，实际应该解析msg
		return &CustomError{Code: 123, Message: "decoded message"}
	})
}

func main() {
	// 创建自定义错误
	err := &CustomError{Code: 404, Message: "not found"}
	
	// 编码/解码
	encoded := errors.EncodeError(context.Background(), err)
	decoded := errors.DecodeError(context.Background(), encoded)
	
	fmt.Printf("Original: %v\n", err)
	fmt.Printf("Decoded: %v\n", decoded)
}

错误包装器示例

package main

import (
	"fmt"
	"github.com/cockroachdb/errors"
)

func processFile() error {
	return errors.New("file not found")
}

func main() {
	err := processFile()
	
	// 添加用户提示
	err = errors.WithHint(err, "Please check if the file exists and try again")
	
	// 添加技术细节
	err = errors.WithDetail(err, "Attempted to open file at /path/to/file.txt")
	
	// 添加问题跟踪链接
	err = errors.WithIssueLink(err, errors.IssueLink{
		IssueURL: "https://github.com/your/repo/issues/123",
		Detail:   "Known issue with file handling",
	})
	
	fmt.Printf("Full error:\n%+v\n", err)
	
	// 获取所有提示
	hints := errors.GetAllHints(err)
	fmt.Println("Hints:", hints)
	
	// 获取所有详情
	details := errors.GetAllDetails(err)
	fmt.Println("Details:", details)
}

错误断言示例

package main

import (
	"fmt"
	"github.com/cockroachdb/errors"
)

func validate(input int) error {
	if input < 0 {
		return errors.AssertionFailedf("input cannot be negative: %d", input)
	}
	return nil
}

func main() {
	err := validate(-1)
	
	if errors.IsAssertionFailure(err) {
		fmt.Println("Assertion failure detected!")
		fmt.Printf("%+v\n", err)
	}
}

cockroachdb/errors库提供了丰富的功能来处理和传输错误，特别是在分布式系统中。通过其网络可移植性特性，可以确保错误在不同服务间传输时仍能保持其标识和详细信息。