doc: add doc for retry package

2026-02-04 12:52:28 +08:00 · 2024-03-05 14:38:42 +08:00
parent c58c50327c
commit d21edd1cde
5 changed files with 428 additions and 3 deletions
--- a/README.md
+++ b/README.md
@@ -1176,6 +1176,16 @@ import "github.com/duke-git/lancet/v2/retry"
 -   **<big>RetryTimes</big>** : 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)]
+-   **<big>BackoffStrategy</big>** : 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)]
+-   **<big>RetryWithCustomBackoff</big>** : set abitary custom backoff strategy.
+    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/retry.md#RetryWithCustomBackoff)]
+-   **<big>RetryWithLinearBackoff</big>** : set linear strategy backoff.
+    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/retry.md#RetryWithLinearBackoff)]
+-   **<big>RetryWithExponentialWithJitterBackoff</big>** : set exponential strategy backoff.
+    [[doc](https://github.com/duke-git/lancet/blob/main/docs/en/api/packages/retry.md#RetryWithExponentialWithJitterBackoff)]
+
+   

 <h3 id="slice"> 18. Slice contains some functions to manipulate slice. &nbsp; &nbsp; &nbsp; &nbsp;<a href="#index">index</a></h3>

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

 <h3 id="slice"> 18. slice 包含操作切片的方法集合。&nbsp; &nbsp; &nbsp; &nbsp; <a href="#index">回到目录</a></h3>

--- 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)

 <div STYLE="page-break-after: always;"></div>

@@ -260,3 +264,201 @@ func main() {
    // 3
 }
 ```
+
+### <span id="BackoffStrategy">BackoffStrategy</span>
+
+<p>定义计算退避间隔的方法的接口。</p>
+
+<b>函数签名:</b>
+
+```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
+}
+```
+
+<b>示例:</b>
+
+```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
+}
+```
+
+### <span id="RetryWithCustomBackoff">RetryWithCustomBackoff</span>
+
+<p>设置自定义退避策略。</p>
+
+<b>函数签名:</b>
+
+```go
+func RetryWithCustomBackoff(backoffStrategy BackoffStrategy) Option 
+```
+
+<b>示例:</b>
+
+```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
+}
+```
+
+
+### <span id="RetryWithLinearBackoff">RetryWithLinearBackoff</span>
+
+<p>设置线性策略退避。</p>
+
+<b>函数签名:</b>
+
+```go
+func RetryWithLinearBackoff(interval time.Duration) Option
+```
+
+<b>示例:</b>
+
+```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
+}
+```
+
+
+### <span id="RetryWithExponentialWithJitterBackoff">RetryWithExponentialWithJitterBackoff</span>
+
+<p>设置指数策略退避。</p>
+
+<b>函数签名:</b>
+
+```go
+func RetryWithExponentialWithJitterBackoff(interval time.Duration, base uint64, maxJitter time.Duration) Option
+```
+
+<b>示例:</b>
+
+```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
+}
+```
--- 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)

 <div STYLE="page-break-after: always;"></div>

@@ -259,3 +263,202 @@ func main() {
    // 3
 }
 ```
+
+
+### <span id="BackoffStrategy">BackoffStrategy</span>
+
+<p>An interface that defines a method for calculating backoff intervals.</p>
+
+<b>Signature:</b>
+
+```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
+}
+```
+
+<b>Example:</b>
+
+```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
+}
+```
+
+### <span id="RetryWithCustomBackoff">RetryWithCustomBackoff</span>
+
+<p>Set abitary custom backoff strategy.</p>
+
+<b>Signature:</b>
+
+```go
+func RetryWithCustomBackoff(backoffStrategy BackoffStrategy) Option 
+```
+
+<b>Example:</b>
+
+```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
+}
+```
+
+
+### <span id="RetryWithLinearBackoff">RetryWithLinearBackoff</span>
+
+<p>Set linear strategy backoff.</p>
+
+<b>Signature:</b>
+
+```go
+func RetryWithLinearBackoff(interval time.Duration) Option
+```
+
+<b>Example:</b>
+
+```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
+}
+```
+
+
+### <span id="RetryWithExponentialWithJitterBackoff">RetryWithExponentialWithJitterBackoff</span>
+
+<p>Set exponential strategy backoff.</p>
+
+<b>Signature:</b>
+
+```go
+func RetryWithExponentialWithJitterBackoff(interval time.Duration, base uint64, maxJitter time.Duration) Option
+```
+
+<b>Example:</b>
+
+```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
+}
+```
--- 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")