From d21edd1cde5ed3f06574da150c720e79dfa1cc66 Mon Sep 17 00:00:00 2001 From: dudaodong Date: Tue, 5 Mar 2024 14:38:42 +0800 Subject: [PATCH] doc: add doc for retry package --- README.md | 10 ++ README_zh-CN.md | 10 ++ docs/api/packages/retry.md | 202 +++++++++++++++++++++++++++++++++ docs/en/api/packages/retry.md | 203 ++++++++++++++++++++++++++++++++++ retry/retry.go | 6 +- 5 files changed, 428 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index d67eab10..cf0c7db1 100644 --- a/README.md +++ b/README.md @@ -1176,6 +1176,16 @@ import "github.com/duke-git/lancet/v2/retry" - **RetryTimes** : set times of retry. [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/retry.md#RetryTimes)] [[play](https://go.dev/play/p/ssfVeU2SwLO)] +- **BackoffStrategy** : An interface that defines a method for calculating backoff intervals. + [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/retry.md#BackoffStrategy)] +- **RetryWithCustomBackoff** : set abitary custom backoff strategy. + [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/retry.md#RetryWithCustomBackoff)] +- **RetryWithLinearBackoff** : set linear strategy backoff. + [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/retry.md#RetryWithLinearBackoff)] +- **RetryWithExponentialWithJitterBackoff** : set exponential strategy backoff. + [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/retry.md#RetryWithExponentialWithJitterBackoff)] + +

18. Slice contains some functions to manipulate slice.        index

diff --git a/README_zh-CN.md b/README_zh-CN.md index e11241a7..c1080f11 100644 --- a/README_zh-CN.md +++ b/README_zh-CN.md @@ -1176,6 +1176,16 @@ import "github.com/duke-git/lancet/v2/retry" - **RetryTimes** : 设置重试次数，默认 5。 [[doc](https://github.com/duke-git/lancet/blob/main/docs/api/packages/retry.md#RetryTimes)] [[play](https://go.dev/play/p/ssfVeU2SwLO)] +- **BackoffStrategy** : 定义计算退避间隔的方法的接口。 + [[doc](https://github.com/duke-git/lancet/blob/main/docs/api/packages/retry.md#BackoffStrategy)] +- **RetryWithCustomBackoff** : 设置自定义退避策略。 + [[doc](https://github.com/duke-git/lancet/blob/main/docs/api/packages/retry.md#RetryWithCustomBackoff)] +- **RetryWithLinearBackoff** : 设置线性策略退避。 + [[doc](https://github.com/duke-git/lancet/blob/main/docs/api/packages/retry.md#RetryWithLinearBackoff)] +- **RetryWithExponentialWithJitterBackoff** : 设置指数策略退避。 + [[doc](https://github.com/duke-git/lancet/blob/main/docs/api/packages/retry.md#RetryWithExponentialWithJitterBackoff)] + +

18. slice 包含操作切片的方法集合。        回到目录

diff --git a/docs/api/packages/retry.md b/docs/api/packages/retry.md index 52bf9080..2517c52e 100644 --- a/docs/api/packages/retry.md +++ b/docs/api/packages/retry.md @@ -27,6 +27,10 @@ import ( - [RetryFunc](#RetryFunc) - [RetryDuration](#RetryDuration) - [RetryTimes](#RetryTimes) +- [BackoffStrategy](#BackoffStrategy) +- [RetryWithCustomBackoff](#RetryWithCustomBackoff) +- [RetryWithLinearBackoff](#RetryWithLinearBackoff) +- [RetryWithExponentialWithJitterBackoff](#RetryWithExponentialWithJitterBackoff)
@@ -260,3 +264,201 @@ func main() { // 3 } ``` + +### BackoffStrategy + +

定义计算退避间隔的方法的接口。

+ +函数签名: + +```go +// BackoffStrategy is an interface that defines a method for calculating backoff intervals. +type BackoffStrategy interface { + // CalculateInterval returns the time.Duration after which the next retry attempt should be made. + CalculateInterval() time.Duration +} +``` + +示例: + +```go +package main + +import ( + "fmt" + "errors" + "log" + "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(&示例CustomBackoffStrategy{interval: time.Microsecond * 50})) + if err != nil { + return + } + + fmt.Println(number) + + // Output: + // 3 +} +``` + +### RetryWithCustomBackoff + +

设置自定义退避策略。

+ +函数签名: + +```go +func RetryWithCustomBackoff(backoffStrategy BackoffStrategy) Option +``` + +示例: + +```go +package main + +import ( + "fmt" + "errors" + "log" + "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(&示例CustomBackoffStrategy{interval: time.Microsecond * 50})) + if err != nil { + return + } + + fmt.Println(number) + + // Output: + // 3 +} +``` + + +### RetryWithLinearBackoff + +

设置线性策略退避。

+ +函数签名: + +```go +func RetryWithLinearBackoff(interval time.Duration) Option +``` + +示例: + +```go +package main + +import ( + "fmt" + "errors" + "log" + "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.RetryWithLinearBackoff(time.Microsecond*50)) + if err != nil { + return + } + + fmt.Println(number) + + // Output: + // 3 +} +``` + + +### RetryWithExponentialWithJitterBackoff + +

设置指数策略退避。

+ +函数签名: + +```go +func RetryWithExponentialWithJitterBackoff(interval time.Duration, base uint64, maxJitter time.Duration) Option +``` + +示例: + +```go +package main + +import ( + "fmt" + "errors" + "log" + "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.RetryWithExponentialWithJitterBackoff(time.Microsecond*50, 2, time.Microsecond*25)) + if err != nil { + return + } + + fmt.Println(number) + + // Output: + // 3 +} +``` diff --git a/docs/en/api/packages/retry.md b/docs/en/api/packages/retry.md index 734de3b8..553c453f 100644 --- a/docs/en/api/packages/retry.md +++ b/docs/en/api/packages/retry.md @@ -27,6 +27,10 @@ import ( - [RetryFunc](#RetryFunc) - [RetryDuration](#RetryDuration) - [RetryTimes](#RetryTimes) +- [BackoffStrategy](#BackoffStrategy) +- [RetryWithCustomBackoff](#RetryWithCustomBackoff) +- [RetryWithLinearBackoff](#RetryWithLinearBackoff) +- [RetryWithExponentialWithJitterBackoff](#RetryWithExponentialWithJitterBackoff)
@@ -259,3 +263,202 @@ func main() { // 3 } ``` + + +### BackoffStrategy + +

An interface that defines a method for calculating backoff intervals.

+ +Signature: + +```go +// BackoffStrategy is an interface that defines a method for calculating backoff intervals. +type BackoffStrategy interface { + // CalculateInterval returns the time.Duration after which the next retry attempt should be made. + CalculateInterval() time.Duration +} +``` + +Example: + +```go +package main + +import ( + "fmt" + "errors" + "log" + "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 + +

Set abitary custom backoff strategy.

+ +Signature: + +```go +func RetryWithCustomBackoff(backoffStrategy BackoffStrategy) Option +``` + +Example: + +```go +package main + +import ( + "fmt" + "errors" + "log" + "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 +} +``` + + +### RetryWithLinearBackoff + +

Set linear strategy backoff.

+ +Signature: + +```go +func RetryWithLinearBackoff(interval time.Duration) Option +``` + +Example: + +```go +package main + +import ( + "fmt" + "errors" + "log" + "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.RetryWithLinearBackoff(time.Microsecond*50)) + if err != nil { + return + } + + fmt.Println(number) + + // Output: + // 3 +} +``` + + +### RetryWithExponentialWithJitterBackoff + +

Set exponential strategy backoff.

+ +Signature: + +```go +func RetryWithExponentialWithJitterBackoff(interval time.Duration, base uint64, maxJitter time.Duration) Option +``` + +Example: + +```go +package main + +import ( + "fmt" + "errors" + "log" + "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.RetryWithExponentialWithJitterBackoff(time.Microsecond*50, 2, time.Microsecond*25)) + if err != nil { + return + } + + fmt.Println(number) + + // Output: + // 3 +} +``` diff --git a/retry/retry.go b/retry/retry.go index 7f3c7662..8198f1fc 100644 --- a/retry/retry.go +++ b/retry/retry.go @@ -45,7 +45,7 @@ func RetryTimes(n uint) Option { } // RetryWithCustomBackoff set abitary custom backoff strategy -// todo: Add playground link +// Play: todo func RetryWithCustomBackoff(backoffStrategy BackoffStrategy) Option { if backoffStrategy == nil { panic("programming error: backoffStrategy must be not nil") @@ -57,7 +57,7 @@ func RetryWithCustomBackoff(backoffStrategy BackoffStrategy) Option { } // RetryWithLinearBackoff set linear strategy backoff -// todo: Add playground link +// Play: todo func RetryWithLinearBackoff(interval time.Duration) Option { if interval <= 0 { panic("programming error: retry interval should not be lower or equal to 0") @@ -71,7 +71,7 @@ func RetryWithLinearBackoff(interval time.Duration) Option { } // RetryWithExponentialWithJitterBackoff set exponential strategy backoff -// todo: Add playground link +// Play: todo func RetryWithExponentialWithJitterBackoff(interval time.Duration, base uint64, maxJitter time.Duration) Option { if interval <= 0 { panic("programming error: retry interval should not be lower or equal to 0")