go-multierror 使用指南

go-multierror 是一个用于 Golang 的错误聚合处理库，它允许你将多个错误合并为一个复合错误对象，同时保留所有原始错误信息。这在需要处理多个可能失败的并行操作时特别有用。

基本用法

安装

go get github.com/hashicorp/go-multierror

简单示例

package main

import (
	"fmt"
	"github.com/hashicorp/go-multierror"
)

func main() {
	var result error

	// 创建新的 multierror.Error
	var merr *multierror.Error

	// 添加错误
	merr = multierror.Append(merr, fmt.Errorf("第一个错误"))
	merr = multierror.Append(merr, fmt.Errorf("第二个错误"))
	merr = multierror.Append(merr, fmt.Errorf("第三个错误"))

	// 获取合并后的错误
	result = merr.ErrorOrNil()

	if result != nil {
		fmt.Printf("发生了 %d 个错误:\n", len(merr.Errors))
		fmt.Println(result)
	}
}

输出：

发生了 3 个错误:
3 errors occurred:
	* 第一个错误
	* 第二个错误
	* 第三个错误

高级特性

自定义格式化

func main() {
	var merr *multierror.Error
	merr = multierror.Append(merr, fmt.Errorf("错误1"))
	merr = multierror.Append(merr, fmt.Errorf("错误2"))
	
	// 自定义错误格式
	merr.ErrorFormat = func(errors []error) string {
		var b strings.Builder
		b.WriteString("自定义错误格式:\n")
		for _, err := range errors {
			b.WriteString(fmt.Sprintf("- %s\n", err))
		}
		return b.String()
	}
	
	fmt.Println(merr)
}

并行操作中的使用

func processTasks(tasks []string) error {
	var merr *multierror.Error
	var wg sync.WaitGroup
	var mu sync.Mutex

	for _, task := range tasks {
		wg.Add(1)
		go func(t string) {
			defer wg.Done()
			err := doTask(t)
			if err != nil {
				mu.Lock()
				merr = multierror.Append(merr, fmt.Errorf("任务 %s 失败: %v", t, err))
				mu.Unlock()
			}
		}(task)
	}

	wg.Wait()
	return merr.ErrorOrNil()
}

func doTask(task string) error {
	// 模拟任务执行
	if len(task) > 5 {
		return nil
	}
	return fmt.Errorf("任务太短")
}

错误展平

func main() {
	var merr *multierror.Error
	
	// 添加普通错误
	merr = multierror.Append(merr, fmt.Errorf("错误1"))
	
	// 添加另一个 multierror
	nested := &multierror.Error{}
	nested = multierror.Append(nested, fmt.Errorf("嵌套错误1"))
	nested = multierror.Append(nested, fmt.Errorf("嵌套错误2"))
	
	// 默认情况下会保留嵌套结构
	merr = multierror.Append(merr, nested)
	fmt.Println("默认嵌套:", merr)
	
	// 使用 Flatten 展平所有错误
	flattened := merr.Flatten()
	fmt.Println("展平后:", flattened)
}

错误转换

func main() {
	var merr *multierror.Error
	merr = multierror.Append(merr, fmt.Errorf("错误1"))
	merr = multierror.Append(merr, fmt.Errorf("错误2"))
	
	// 转换为标准错误
	stdErr := merr.Unwrap()
	fmt.Println("标准错误:", stdErr)
	
	// 检查是否包含特定错误
	if errors.Is(merr, fmt.Errorf("错误1")) {
		fmt.Println("包含错误1")
	}
}

最佳实践

1. 并行操作：在并发场景下使用 mutex 保护 multierror 的修改
2. 错误检查：使用 ErrorOrNil() 来检查是否有错误发生
3. 格式化：为不同场景定制错误输出格式
4. 错误处理：考虑使用 errors.Is() 和 errors.As() 处理特定错误
5. 性能考虑：对于高频操作，考虑预分配错误容量

与其他库的比较

• 相比标准库的 errors.Join (Go 1.20+)，go-multierror 提供更多功能：
  • 自定义格式化
  • 错误展平
  • 更丰富的操作方法
  • 更好的并发支持

go-multierror 特别适合需要细粒度控制错误聚合和展示的复杂应用场景。