每日一库：retry-go —— Go 语言轻量级重试库

七点一刻

发布于 2026-03-18 19:02:29

970

概述

retry-go是一个简单易用的 Go 语言重试库，由 Avast 开源。它提供灵活的重试策略和丰富的配置选项，适用于需要网络请求、资源访问等场景的错误重试。与其他重试库（如cenkalti/backoff）相比，retry-go 的接口更直观，支持带返回值重试和动态条件控制，适合快速集成到项目中。

• Github：https://github.com/avast/retry-go

核心特性

1.简洁的 API 设计： •retry.Do()：执行无返回值的重试逻辑。 •retry.DoWithData()：执行带返回值的重试逻辑（支持泛型）。
2.多种延迟策略： •指数退避（默认）、固定延迟、随机抖动，支持自定义组合。
3.灵活的重试条件： • 根据错误类型、重试次数、自定义逻辑动态控制是否重试。
4.上下文支持： • 集成context.Context，支持超时或手动取消重试任务。
5.错误处理： • 收集所有重试错误，或仅返回最后一次错误。 • 支持将错误标记为不可恢复（Unrecoverable），立即终止重试。

快速开始

安装

go get github.com/avast/retry-go

基本用法：HTTP GET 重试

url := "http://example.com"
var body []byte

err := retry.Do(
    func()error {
        resp, err := http.Get(url)
        if err != nil {
            return err
        }
        defer resp.Body.Close()
        body, err = io.ReadAll(resp.Body)
        return err
    },
    retry.Attempts(3),       // 最大重试次数
    retry.Delay(time.Second),// 重试间隔
)

if err != nil {
    log.Fatal("请求失败:", err)
}
fmt.Println(string(body))

带返回值的重试

使用DoWithData简化返回值处理：

body, err := retry.DoWithData(
    func() ([]byte, error) {
        resp, err := http.Get(url)
        if err != nil {
            return nil, err
        }
        defer resp.Body.Close()
        return io.ReadAll(resp.Body)
    },
    retry.Attempts(5),
)

高级配置

1. 延迟策略

•指数退避（默认）：

retry.DelayType(retry.BackOffDelay)

•固定延迟：

retry.DelayType(retry.FixedDelay)
retry.Delay(500 * time.Millisecond) // 固定 500ms

•随机抖动：

retry.DelayType(retry.RandomDelay)
retry.MaxJitter(1 * time.Second)    // 最大抖动 1s

•组合策略（如固定延迟 + 随机抖动）：

retry.DelayType(retry.CombineDelay(
    retry.FixedDelay,
    retry.RandomDelay,
))

2. 自定义重试条件

通过RetryIf根据错误类型判断是否重试：

retry.Do(
    fetchData,
    retry.RetryIf(func(err error) bool {
        return strings.Contains(err.Error(), "timeout")
    }),
)

标记不可恢复错误：

err := retry.Do(
    func() error {
        if criticalError {
            return retry.Unrecoverable(errors.New("致命错误"))
        }
        return nil
    },
)

3. 无限重试与上下文

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
defer cancel()

retry.Do(
    task,
    retry.Attempts(0),       // 无限重试
    retry.Context(ctx),      // 绑定上下文
    retry.Delay(time.Second),
)

4. 重试回调

记录每次重试日志：

retry.OnRetry(func(attempt uint, err error) {
    log.Printf("第 %d 次重试，错误: %v", attempt, err)
})

版本迁移注意

•v 1 → v 2：retry.Delay的语义从“基础单位”变为“最终延迟”，移除retry.Units。 •v 0 → v 1：函数名从Retry改为Do，新增Options模式。

对比其他库

库名	特点	适用场景
retry-go	简单直观，支持泛型返回值	快速集成，通用重试逻辑
cenkalti/backoff	复杂退避算法，Google 官方实现	高并发场景，精细控制
matryer/try	链式调用，高人气	偏好流式接口的项目