retry

package
v0.0.8 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 25, 2026 License: MIT Imports: 6 Imported by: 0

README

retry 包 — 重试机制

所属层级: Infrastructure Layer
设计理念: 独立重试机制,统一重试策略
设计灵感: Spring Retry + Resilience4j Retry

概述

retry 包提供独立的重试机制支持,从 event/deadletter.go 和 web/server/retry.go 抽取而来,为事件处理、HTTP 请求等场景提供统一的重试策略和执行器。

核心功能
功能 说明
重试策略配置 最大次数、退避策略、延迟计算
退避策略 None/Fixed/Linear/Exponential 四种策略
Jitter 防惊群 抖动比例 (0.0-1.0),防止惊群效应
上下文取消 支持 context.Context 取消重试
回调通知 重试成功/失败回调通知
零依赖 仅使用 Go 标准库

核心类型

RetryPolicy 重试策略配置
type RetryPolicy struct {
    MaxAttempts  int             // 最大尝试次数(包含首次),0 表示不重试
    Strategy     BackoffStrategy // 退避策略
    InitialDelay time.Duration   // 初始延迟
    MaxDelay     time.Duration   // 最大延迟(指数退避上限)
    Multiplier   float64         // 退避乘数(指数退避用)
    Jitter       float64         // 抖动比例 (0.0-1.0)
}
Executor 重试执行器
executor := retry.NewExecutor(policy)
result, err := executor.Execute(ctx, func(ctx context.Context) (any, error) {
    return httpClient.Get(ctx, url)
})

便捷构造函数

函数 说明
NoRetry() 不重试策略(仅执行一次)
FixedDelay(maxAttempts, delay) 固定延迟重试
LinearBackoff(maxAttempts, initialDelay, maxDelay) 线性退避
ExponentialBackoff(maxAttempts, initialDelay, maxDelay) 指数退避

退避策略

策略 常量 说明
无退避 BackoffNone 立即重试
固定间隔 BackoffFixed 每次延迟相同时间
线性 BackoffLinear 延迟线性递增
指数 BackoffExponential 延迟指数递增(推荐)

使用示例

// 指数退避:最多 3 次,初始 100ms,最大 10s
policy := retry.ExponentialBackoff(3, 100*time.Millisecond, 10*time.Second)
executor := retry.NewExecutor(policy)

result, err := executor.Execute(ctx, func(ctx context.Context) (any, error) {
    return httpClient.Get(ctx, url)
})

设计决策

  • ADR-004: 零外部依赖,仅使用 Go 标准库
  • ADR-005: 接口定义在 doc.go,实现隐藏在 retry.go
  • 从 event 和 web/server 抽取,统一重试逻辑避免重复

Documentation

Overview

Package retry 提供独立的重试机制支持。

从 event/deadletter.go 和 web/server/retry.go 抽取而来, 为事件处理、HTTP 请求等场景提供统一的重试策略和执行器。

核心组件:

  • RetryPolicy: 重试策略配置(最大次数、退避策略、延迟计算)
  • Executor: 重试执行器(支持 jitter 防惊群、上下文取消、回调通知)
  • BackoffStrategy: 退避策略(None/Fixed/Linear/Exponential)

使用示例:

policy := retry.ExponentialBackoff(3, 100*time.Millisecond, 10*time.Second)
executor := retry.NewExecutor(policy)

result, err := executor.Execute(ctx, func(ctx context.Context) (any, error) {
    return httpClient.Get(ctx, url)
})

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Execute

func Execute[T any](ctx context.Context, exec *Executor, fn RetryableFunc[T]) (T, error)

Execute 执行带重试的函数

Types

type BackoffStrategy

type BackoffStrategy string

BackoffStrategy 退避策略

const (
	// BackoffNone 无退避,立即重试。
	BackoffNone BackoffStrategy = "none" // 无退避,立即重试
	// BackoffFixed 固定间隔退避。
	BackoffFixed BackoffStrategy = "fixed" // 固定间隔退避
	// BackoffLinear 线性退避。
	BackoffLinear BackoffStrategy = "linear" // 线性退避
	// BackoffExponential 指数退避。
	BackoffExponential BackoffStrategy = "exponential" // 指数退避
)

type Executor

type Executor struct {
	// contains filtered or unexported fields
}

Executor 重试执行器

func MustNewExecutor

func MustNewExecutor(policy RetryPolicy, opts ...ExecutorOption) *Executor

MustNewExecutor 创建重试执行器(失败时 panic)

func NewExecutor

func NewExecutor(policy RetryPolicy, opts ...ExecutorOption) (*Executor, error)

NewExecutor 创建重试执行器

func (*Executor) ExecuteVoid

func (e *Executor) ExecuteVoid(ctx context.Context, fn func(ctx context.Context) error) error

ExecuteVoid 执行无返回值的重试函数

type ExecutorOption

type ExecutorOption func(*Executor)

ExecutorOption 执行器选项

func WithOnRetry

func WithOnRetry(fn OnRetryFunc) ExecutorOption

WithOnRetry 设置重试回调

func WithRetryable

func WithRetryable(fn func(error) bool) ExecutorOption

WithRetryable 设置可重试错误判断函数

type OnRetryFunc

type OnRetryFunc func(info RetryInfo)

OnRetryFunc 重试回调函数签名

type RetryInfo

type RetryInfo struct {
	Attempt     int           // 当前尝试次数(从 0 开始)
	MaxAttempts int           // 最大尝试次数
	Delay       time.Duration // 下次重试延迟
	LastErr     error         // 最后一次错误
}

RetryInfo 重试信息(用于回调)

type RetryPolicy

type RetryPolicy struct {
	MaxAttempts  int             // 最大尝试次数(包含首次),0 表示不重试
	Strategy     BackoffStrategy // 退避策略
	InitialDelay time.Duration   // 初始延迟
	MaxDelay     time.Duration   // 最大延迟(指数退避上限)
	Multiplier   float64         // 退避乘数(指数退避用)
	Jitter       float64         // 抖动比例 (0.0-1.0),防止惊群效应
}

RetryPolicy 重试策略配置

func ExponentialBackoff

func ExponentialBackoff(maxAttempts int, initialDelay, maxDelay time.Duration) RetryPolicy

ExponentialBackoff 创建指数退避策略(带 jitter 防惊群)

func FixedDelay

func FixedDelay(maxAttempts int, delay time.Duration) RetryPolicy

FixedDelay 创建固定延迟重试策略

func LinearBackoff

func LinearBackoff(maxAttempts int, initialDelay, maxDelay time.Duration) RetryPolicy

LinearBackoff 创建线性退避策略

func NoRetry

func NoRetry() RetryPolicy

NoRetry 创建不重试策略

func (RetryPolicy) CalculateDelay

func (p RetryPolicy) CalculateDelay(attempt int) time.Duration

CalculateDelay 计算当前重试次数对应的延迟(含 jitter)

func (RetryPolicy) Validate

func (p RetryPolicy) Validate() error

Validate 验证策略配置是否合法

type RetryableFunc

type RetryableFunc[T any] func(ctx context.Context) (T, error)

RetryableFunc 可重试的函数签名

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL