retry

retry

简介

retry 包提供了通用的重试机制，支持带上下文和不带上下文的函数重试，内置指数退避（Backoff）和可选抖动（Jitter）机制，适用于网络请求、数据库操作等易失败场景。通过灵活的配置选项，开发者可自定义重试策略，提升系统健壮性。

主要特性

• 支持无上下文和带上下文的函数重试
• 内置指数退避与抖动机制，减少并发冲突
• 灵活的最小/最大等待时间、增长因子等参数配置
• 支持重试过程的取消与超时控制
• API 简洁，易于集成
• 完整的单元测试覆盖

设计理念

本包设计注重通用性与灵活性，采用函数式选项模式（Functional Options）配置重试策略，便于扩展和组合。通过与 Go 的 context 包深度集成，支持优雅的取消和超时控制，适合高并发和分布式系统。

安装

前置条件

• Go 版本要求：Go 1.18 或更高版本
• 依赖要求：
  • 仅依赖 Go 标准库

安装命令

go get -u github.com/fsyyft-go/kit/runtime/retry

快速开始

基础用法

package main

import (
    "fmt"
    "github.com/fsyyft-go/kit/runtime/retry"
)

func main() {
    // 定义一个可能失败的操作
    count := 0
    err := retry.Retry(func() error {
        count++
        if count < 3 {
            return fmt.Errorf("第 %d 次失败", count)
        }
        return nil
    })
    if err != nil {
        fmt.Printf("重试失败: %v\n", err)
    } else {
        fmt.Println("重试成功")
    }
}

带上下文的用法

package main

import (
    "context"
    "fmt"
    "time"
    "github.com/fsyyft-go/kit/runtime/retry"
)

func main() {
    ctx, cancel := context.WithTimeout(context.Background(), time.Second)
    defer cancel()
    count := 0
    err := retry.RetryWithContext(ctx, func(ctx context.Context) error {
        count++
        if count < 5 {
            return fmt.Errorf("第 %d 次失败", count)
        }
        return nil
    }, retry.WithMin(10*time.Millisecond), retry.WithMax(50*time.Millisecond))
    if err != nil {
        fmt.Printf("重试失败: %v\n", err)
    } else {
        fmt.Println("重试成功")
    }
}

配置选项

// 可通过函数式选项自定义重试策略：
retry.Retry(fn,
    retry.WithMin(100*time.Millisecond), // 最小等待时间
    retry.WithMax(2*time.Second),        // 最大等待时间
    retry.WithFactor(1.5),               // 增长因子
    retry.WithJitter(true),              // 启用抖动
)

详细指南

核心概念

重试机制

重试机制用于在操作失败时自动重新尝试，常用于网络、IO、数据库等易受外部影响的场景。合理的重试策略可显著提升系统的健壮性和可用性。

指数退避（Exponential Backoff）

每次重试等待时间按指数递增，有效避免雪崩和资源竞争。可通过 WithFactor、WithMin、WithMax 配置增长速率和区间。

抖动（Jitter）

抖动机制在退避基础上引入随机性，减少高并发场景下的同步重试冲突。通过 WithJitter(true) 启用。

常见用例

1. 网络请求重试

err := retry.Retry(func() error {
    // 执行网络请求
    return doRequest()
}, retry.WithJitter(true))

2. 数据库操作重试

err := retry.RetryWithContext(ctx, func(ctx context.Context) error {
    // 执行数据库操作
    return db.ExecContext(ctx, sql)
}, retry.WithMin(50*time.Millisecond), retry.WithMax(500*time.Millisecond))

最佳实践

• 合理设置最大重试次数，避免无限重试
• 使用带 context 的重试，支持取消和超时
• 在高并发场景下建议开启抖动
• 根据业务场景调整退避参数，平衡重试速度与系统压力
• 对于不可恢复的错误应及时中断重试

API 文档

主要类型

// RetryableFunc 定义了可重试的函数类型。
type RetryableFunc func() error

// RetryableFuncWithContext 定义了带上下文的可重试函数类型。
type RetryableFuncWithContext func(ctx context.Context) error

// Backoff 退避策略生成器，支持参数化配置。
type Backoff struct {
    // ...字段详见源码...
}

关键函数

Retry

对无 context 的函数进行重试。

func Retry(fn RetryableFunc, opts ...BackoffOption) error

RetryWithContext

对带 context 的函数进行重试，支持取消和超时。

func RetryWithContext(ctx context.Context, fn RetryableFuncWithContext, opts ...BackoffOption) error

Backoff 相关

• NewBackoff(opts ...BackoffOption) *Backoff：创建退避策略实例
• WithMin(min time.Duration) BackoffOption：设置最小等待时间
• WithMax(max time.Duration) BackoffOption：设置最大等待时间
• WithFactor(factor float64) BackoffOption：设置增长因子
• WithJitter(jitter bool) BackoffOption：启用/禁用抖动

错误处理

• 当所有重试均失败时，返回最后一次的错误
• 若 context 被取消或超时，返回 context 的错误

性能指标

测试覆盖率

调试指南

常见问题排查

重试未生效

• 检查重试函数返回值，确保失败时返回 error
• 检查 context 是否提前取消或超时
• 检查退避参数设置是否合理

性能问题

• 合理设置最小/最大等待时间，避免频繁重试
• 并发场景下建议使用 ForAttempt 方法

相关文档

• Go context 包文档
• Exponential Backoff 算法
• Go 标准库 time 包