开发工具【免费下载链接】lancetA comprehensive, efficient, and reusable util function library of Go.项目地址https://gitcode.com/gh_mirrors/la/lancet点击查看免费下载retry是 Go 通用工具库 lancet 提供的重试执行包用于反复执行一个函数直到它成功或被 context 取消retry/retry.go。在分布式系统、网络请求、数据库操作等易失败场景中合理的重试次数、重试间隔与退避backoff策略是提升稳定性的关键。阅读本文后你将掌握 lancet retry 包的完整 API、Option配置模式、线性/指数/自定义三类退避策略的实现原理以及如何用context优雅地中断重试并能够直接落地到自己的项目中。一、包定位与设计概述lancet 将工具函数按包组织retry包专注于重试执行这一横切关注点。其核心设计是函数式选项Functional Options模式所有可调参数都通过返回Option的构造函数注入主函数Retry只负责执行循环。这种设计让调用方可以按需组合配置且未来新增配置项不会破坏既有调用。包内全部符号均可在 retry/retry.go 中找到其中RetryConfig是内部配置结构体持有context、retryTimes与backoffStrategy三个字段Option是func(*RetryConfig)类型所有RetryXxx/Context构造函数都返回它BackoffStrategy是决定两次重试之间等待多久的接口是包内扩展性的核心。二、安装与导入lancet 当前版本v2.x要求 Go 1.18 及以上见 go.mod 中go 1.18安装命令go get github.com/duke-git/lancet/v2导入方式以模块路径github.com/duke-git/lancet/v2为准import ( github.com/duke-git/lancet/v2/retry )三、API 总览retry包对外暴露的符号如下表符号类型作用Retry函数重试执行RetryFunc直到成功或被 context 取消RetryFunc类型被重试执行的函数签名func() errorRetryTimes函数设置重试次数默认 5 次RetryDuration函数设置两次重试间隔见下文历史说明Context函数设置重试 context可取消重试BackoffStrategy接口定义计算退避间隔的方法CalculateInterval() time.DurationRetryWithCustomBackoff函数设置任意自定义退避策略RetryWithLinearBackoff函数设置线性退避策略RetryWithExponentialWithJitterBackoff函数设置带随机抖动jitter的指数退避策略其中Retry是唯一的入口其余函数均为配置构造函数。README 的 retry 小节 也给出了同样的函数清单与中文说明可作为速查参考。关于 RetryDuration 的历史说明文档索引中保留了RetryDuration(d time.Duration)条目默认 3 秒但从当前源码结构看该函数在 retry/retry.go 中已不存在取而代之的是RetryWithLinearBackoff(interval time.Duration)。如果你需要固定间隔重试请直接使用RetryWithLinearBackoff若完全不指定任何退避策略Retry内部默认采用间隔 3 秒的线性退避常量DefaultRetryLinearInterval time.Second * 3见 retry/retry.go。四、核心入口Retry的源码级原理Retry的完整实现位于 retry/retry.go核心逻辑如下func Retry(retryFunc RetryFunc, opts ...Option) error { config : RetryConfig{ retryTimes: DefaultRetryTimes, // 默认 5 次 context: context.TODO(), } for _, opt : range opts { opt(config) // 依次应用所有 Option } if config.backoffStrategy nil { config.backoffStrategy linear{ interval: DefaultRetryLinearInterval, // 默认 3 秒 } } var i uint var lastErr error for i config.retryTimes { lastErr retryFunc() if lastErr nil { return nil // 成功立即返回 } if i config.retryTimes-1 { // 仅非最后一次重试时等待 select { case -time.After(config.backoffStrategy.CalculateInterval()): case -config.context.Done(): return errors.New(retry is cancelled) } } i } // 通过反射与 runtime 获取被重试函数的名称 funcPath : runtime.FuncForPC(reflect.ValueOf(retryFunc).Pointer()).Name() lastSlash : strings.LastIndex(funcPath, /) funcName : funcPath[lastSlash1:] return fmt.Errorf(function %s run failed after %d times retry, last error: %w, funcName, i, lastErr) }从实现中可以提炼出几个关键事实成功即返回只要retryFunc返回nil循环立即结束并返回nil后续次数不会浪费最后一次失败不等待i config.retryTimes-1的判断确保第 N 次尝试失败后不再 sleep直接返回错误避免多余的无效等待等待可被 context 打断间隔等待通过select同时监听time.After与context.Done()context 被取消时立即返回errors.New(retry is cancelled)错误信息自带函数名通过runtime.FuncForPCreflect.ValueOf(...).Pointer()解析出被重试函数的名称最终错误格式为function 函数名 run failed after 次数 times retry, last error: 原始错误。注意文档示例中输出只写到了...after 2 times retry是省略写法实际返回的错误通过%w包装了最后一次错误可用errors.Is/errors.As展开判断retry/retry.go。默认值速查配置项默认值定义位置重试次数5DefaultRetryTimesretry/retry.go退避间隔3 秒DefaultRetryLinearIntervalretry/retry.gocontextcontext.TODO()retry/retry.go五、Option 配置项逐个击破所有 Option 构造函数都遵循同一模式返回一个闭包在Retry内部被应用到RetryConfig上。1. RetryTimes(n uint)控制重试次数设置最大重试次数含首次尝试。默认 5 次。示例当函数第 3 次才成功、而次数上限为 2 时将得到失败错误package main import ( errors fmt github.com/duke-git/lancet/v2/retry ) func main() { number : 0 increaseNumber : func() error { number if number 3 { return nil } return errors.New(error occurs) } err : retry.Retry(increaseNumber, retry.RetryTimes(2)) if err ! nil { fmt.Println(err) } // Output 形如 // function main.main.func1 run failed after 2 times retry, last error: error occurs }2. Context(ctx)优雅地取消重试重试可能长时间空转Context选项允许外部通过context.CancelFunc随时中断。示例中函数始终返回错误但第 4 次调用时主动cancel()Retry在等待阶段感知 context 取消并立即返回package main import ( context errors fmt time github.com/duke-git/lancet/v2/retry ) func main() { ctx, cancel : context.WithCancel(context.TODO()) number : 0 increaseNumber : func() error { number if number 3 { cancel() } return errors.New(error occurs) } retry.Retry(increaseNumber, retry.RetryWithLinearBackoff(time.Microsecond*50), retry.Context(ctx), ) fmt.Println(number) // Output: // 4 }同理你也可以在重试函数外启动一个 goroutine 在超时后调用cancel()实现超时即停止重试。六、Backoff 退避策略重试间隔的艺术重试如果失败即立刻重试往往会在服务短暂故障时形成请求风暴。退避策略决定了每次重试前等待多久。retry包以接口方式抽象了这一行为// BackoffStrategy 定义计算退避间隔的方法。 type BackoffStrategy interface { // CalculateInterval 返回下一次重试应等待的时间。 CalculateInterval() time.Duration }Retry主循环会在每次等待时调用CalculateInterval()因此该接口天然支持间隔随时间动态变化的策略。1. 线性退避RetryWithLinearBackoff固定间隔等待策略内部结构体为linearCalculateInterval恒定返回设定值retry/retry.gofunc (l *linear) CalculateInterval() time.Duration { return l.interval }使用示例err : retry.Retry(increaseNumber, retry.RetryWithLinearBackoff(time.Microsecond*50))参数校验interval 0时直接panic(programming error: retry interval should not be lower or equal to 0)retry/retry.go。2. 带抖动的指数退避RetryWithExponentialWithJitterBackoff指数退避让间隔按倍数增长适合应对流量尖峰抖动jitter则引入随机量避免多个客户端在同一时刻集体重试造成惊群。签名func RetryWithExponentialWithJitterBackoff(interval time.Duration, base uint64, maxJitter time.Duration) Optioninterval初始间隔base增长基数maxJitter最大抖动幅度。实现上有两条路径retry/retry.gobase为偶数时采用位运算优化shifter log2(base)间隔每次左移shifter位等价于乘以 base但更快对应结构体shiftExponentialWithJitterbase为奇数时采用乘法间隔每次乘以base对应结构体exponentialWithJitter。两者计算逻辑一致返回当前间隔 随机抖动func (e *exponentialWithJitter) CalculateInterval() time.Duration { current : e.interval e.interval e.interval * e.base return current jitter(e.maxJitter) }jitter的实现是在[1, maxJitter]范围内取随机数若maxJitter为 0 则不加抖动retry/retry.gofunc jitter(maxJitter time.Duration) time.Duration { if maxJitter 0 { return 0 } return time.Duration(rand.Int63n(int64(maxJitter)) 1) }使用示例err : retry.Retry(increaseNumber, retry.RetryWithExponentialWithJitterBackoff(time.Microsecond*50, 2, time.Microsecond*25))参数校验interval 0或maxJitter 0时panicretry/retry.go。3. 完全自定义RetryWithCustomBackoff如果内置策略不满足需求实现BackoffStrategy接口即可。例如自定义一个固定间隔 1的策略package main import ( errors fmt time github.com/duke-git/lancet/v2/retry ) type ExampleCustomBackoffStrategy struct { interval time.Duration } func (c *ExampleCustomBackoffStrategy) CalculateInterval() time.Duration { return c.interval 1 } func main() { number : 0 increaseNumber : func() error { number if number 3 { return nil } return errors.New(error occurs) } err : retry.Retry(increaseNumber, retry.RetryWithCustomBackoff(ExampleCustomBackoffStrategy{interval: time.Microsecond * 50})) if err ! nil { return } fmt.Println(number) // Output: // 3 }注意RetryWithCustomBackoff传入nil策略会直接panicretry/retry.go因此自定义策略应始终以非空实例传入。七、测试验证与运行retry包对每个导出函数都提供了单元测试与可运行示例测试位于 retry/retry_test.go示例位于 retry/retry_example_test.go。在仓库根目录运行go test ./retry/...可复现全部验证。测试用例覆盖了关键行为可直接作为你理解语义的活文档测试函数验证点TestRetryFailed始终失败时执行满默认 5 次返回错误且errors.Is(err, customError)为真TestRetrySucceeded/TestRetryOneShotSucceeded第 5 次成功 / 首次即成功时提前返回nilTestSetRetryTimesRetryTimes(3)时恰好执行 3 次后失败TestCancelRetrycontext 取消后停止重试执行次数为 4TestRetryWithExponentialSucceeded/TestRetryWithExponentialShiftSucceededbase 为 3乘法与 base 为 4位移两条指数路径均正常TestRetryWitCustomBackoffOneShotSucceeded自定义策略生效这些测试同时印证了前文的分析重试次数默认 5、最后一次失败不等待、context 取消立即返回、错误可用errors.Is解包。八、实战注意事项重试函数必须是幂等的retryFunc会被反复调用若函数本身有副作用如写库、发消息应确认重复执行不会造成业务错误用errors.Is判断失败原因最终错误通过%w包装了最后一次lastErr可用errors.Is(err, 目标错误)或errors.As提取而不是做字符串匹配生产环境建议显式指定退避策略不传退避选项时默认是 3 秒固定间隔高并发场景下更推荐RetryWithExponentialWithJitterBackoff利用 jitter 打散重试节奏配合 context 设置总超时重试次数 × 间隔可能很长建议将带超时的 context 通过Context(ctx)注入保证整体耗时可控参数非法会 panicinterval 0、maxJitter 0、backoffStrategy nil均触发 panic属于编程错误programming error应在调用前自行校验。综上lancet 的retry包以极小的 API 面提供了完整的重试闭环——次数控制、context 取消、三种退避策略与自定义扩展点配合源码中清晰的实现与完备的测试是 Go 项目引入重试能力时成本最低的选择之一。深入阅读 retry/retry.go 与 retry/retry_test.go 即可获得全部实现细节。赞分享开发工具【免费下载链接】lancetA comprehensive, efficient, and reusable util function library of Go.项目地址https://gitcode.com/gh_mirrors/la/lancet点击查看免费下载相关推荐Higress model-mapper 插件基于 LLM 协议实现 AI 模型参数映射与统一路由Higress model mapper 插件基于 LLM 协议实现 AI 模型参数映射与统一路由 model mapper 是 Higress AI 网关中开发工具Got 重试机制完全指南retry 配置、指数退避与 Retry-After 实战解析Got 重试机制完全指南retry 配置、指数退避与 Retry After 实战解析 本篇指南围绕 Got当前仓库为 gh_mirrors/go/got后端网络Akka.NET 监督机制Supervision完全指南从容错策略到 Backoff 指数退避Akka.NET 监督机制Supervision完全指南从容错策略到 Backoff 指数退避 Akka.NET 的监督Supervision是 Ac后端微服务上一篇NeteaseCloudMusicFlac 实战一条歌单链接批量拿下无损FLAC下一篇英雄联盟免费换肤指南R3nzSkin国服特供版从注入到切换皮肤只需5分钟创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考