Class RetryBudget

java.lang.Object
cloud.opencode.base.cache.protection.RetryBudget
public final class RetryBudget extends Object
Retry Budget — Limits the fraction of requests that can be retried. 重试预算 — 限制可重试请求的比例。

Prevents retry amplification in microservices by ensuring that retries never exceed a configurable fraction of total requests (default: 20%).

通过确保重试不超过总请求的可配置比例（默认：20%），防止微服务中的重试放大。

Uses a simple ratio gate: each original request increments a total counter; each retry is allowed only when retries/requests < retryRatio.

使用简单的比例门控：每个原始请求递增总计数器； 仅当 retries/requests < retryRatio 时才允许重试。

Example | 示例:

RetryBudget budget = RetryBudget.ofRatio(0.20); // max 20% retries

Features | 主要功能:

  • Ratio-based retry limiting - 基于比率的重试限制
  • Atomic counter tracking - 原子计数器跟踪
  • Retry amplification prevention - 重试放大防护

Usage Examples | 使用示例:

RetryBudget budget = RetryBudget.ofRatio(0.20);
budget.recordRequest();
if (budget.tryAcquireRetry()) {
    // retry allowed
}

Security | 安全性:

  • Thread-safe: Yes (uses AtomicLong) - 线程安全: 是（使用 AtomicLong）
  • Null-safe: Yes - 空值安全: 是
Since:
JDK 25, opencode-base-cache V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • ofRatio

      public static RetryBudget ofRatio(double retryRatio)
      Creates a retry budget with the given ratio. 创建具有给定比例的重试预算。
      Parameters:
      retryRatio - the maximum fraction of retries (0 exclusive, 1 exclusive), e.g. 0.20 = at most 20% of requests may be retried - 最大重试比例（不含 0 和 1），例如 0.20 = 最多 20% 的请求可重试
      Returns:
      the retry budget - 重试预算

    • ofPercent

      public static RetryBudget ofPercent(int percent)
      Creates a retry budget with the given percentage (1–99). 创建具有给定百分比的重试预算（1–99）。
      Parameters:
      percent - the percentage of requests that may be retried (1–99) - 可重试请求的百分比（1–99）
      Returns:
      the retry budget - 重试预算

    • unlimited

      public static RetryBudget unlimited()
      Creates a retry budget that effectively allows unlimited retries (99.99% ratio). Useful for testing or scenarios where budgeting is not desired. 创建实际上允许无限重试的重试预算（99.99% 比例）。 适用于测试或不需要预算控制的场景。
      Returns:
      an unlimited retry budget - 无限重试预算

    • recordRequest

      public void recordRequest()
      Records an original (non-retry) request. Should be called before each original request attempt. 记录一个原始（非重试）请求。 应在每个原始请求尝试之前调用。

    • canRetry

      public boolean canRetry()
      Returns true if a retry is allowed given the current budget state. 如果当前预算状态允许重试，则返回 true。
      Returns:
      true if a retry is allowed - 如果允许重试返回 true

    • recordRetry

      public void recordRetry()
      Records that a retry is about to be attempted. Should be called just before making a retry attempt. 记录即将尝试重试。 应在进行重试尝试之前调用。

    • currentRetryRatio

      public double currentRetryRatio()
      Returns the current retry ratio (retries / total requests). Returns 0.0 if no requests have been recorded. 返回当前重试比率（重试次数 / 总请求数）。 如果没有记录请求，则返回 0.0。
      Returns:
      the current retry ratio - 当前重试比率

    • getRetryRatio

      public double getRetryRatio()
      Returns the configured maximum retry ratio. 返回配置的最大重试比率。
      Returns:
      the max retry ratio - 最大重试比率

    • getTotalRequests

      public long getTotalRequests()
      Returns the total number of original requests recorded. 返回已记录的原始请求总数。
      Returns:
      the total request count - 总请求数

    • getTotalRetries

      public long getTotalRetries()
      Returns the total number of retries recorded. 返回已记录的重试总数。
      Returns:
      the total retry count - 总重试数

    • toString

      public String toString()
      Overrides:
      toString in class Object