useAsyncRateLimiter

函数：useAsyncRateLimiter()

function useAsyncRateLimiter<TFn>(fn, options): AsyncRateLimiter<TFn>

function useAsyncRateLimiter<TFn>(fn, options): AsyncRateLimiter<TFn>

定义于：react-pacer/src/async-rate-limiter/useAsyncRateLimiter.ts:67

一个低级别的 React 钩子，用于创建一个 AsyncRateLimiter 实例，以限制异步函数在时间窗口内可以执行的次数。

此钩子设计灵活且与状态管理无关——它仅返回一个速率限制器实例，您可以将其与任何状态管理解决方案（useState、Redux、Zustand、Jotai 等）集成。

速率限制允许异步函数在时间窗口内执行达到指定限制的次数，然后阻止后续调用，直到窗口过去。这对于遵守 API 速率限制非常有用，管理资源约束，或控制异步操作的爆发。

与非异步 RateLimiter 不同，此异步版本支持从速率限制函数返回值，使其非常适合 API 调用和其他异步操作，在这些操作中，您希望获得 maybeExecute 调用的结果而不是在速率限制函数内部设置状态变量的结果。

速率限制器支持两种类型的窗口：

'fixed'：一个严��的窗口，在窗口期过后重置。窗口内的所有执行都计入限制，并且窗口在期满后完全重置。
'sliding'：一个滚动窗口，允许随着旧执行的过期而执行。这提供了一个更随时间推移更一致的执行速率。

错误处理：

如果提供了 onError 处理程序，它将与错误和速率限制器实例一起被调用
如果 throwOnError 为 true（未提供 onError 处理程序时的默认值），则会抛出错误
如果 throwOnError 为 false（提供 onError 处理程序时的默认值），则会吞没错误
onError 和 throwOnError 可以一起使用——处理程序将在抛出任何错误之前被调用
可以使用底层的 AsyncRateLimiter 实例检查错误状态
速率限制拒绝（当超出限制时）通过 onReject 处理程序与执行错误分开处理

类型参数

• TFn extends AnyAsyncFunction

参数

fn

TFn

options

AsyncRateLimiterOptions<TFn>

AsyncRateLimiter<TFn>

示例

tsx

// 带返回值的基础 API 调用速率限制
const { maybeExecute } = useAsyncRateLimiter(
  async (id: string) => {
    const data = await api.fetchData(id);
    return data; // 返回值被保留
  },
  { limit: 5, window: 1000 } // 每秒 5 次调用
);

// 带状态管理和返回值
const [data, setData] = useState(null);
const { maybeExecute } = useAsyncRateLimiter(
  async (query) => {
    const result = await searchAPI(query);
    setData(result);
    return result; // 返回值可供调用者使用
  },
  {
    limit: 10,
    window: 60000, // 每分钟 10 次调用
    onReject: (rateLimiter) => {
      console.log(`已超出速率限制。请在 ${rateLimiter.getMsUntilNextWindow()} 毫秒后重试`);
    },
    onError: (error) => {
      console.error('API 调用失败：', error);
    }
  }
);

// 带返回值的基础 API 调用速率限制
const { maybeExecute } = useAsyncRateLimiter(
  async (id: string) => {
    const data = await api.fetchData(id);
    return data; // 返回值被保留
  },
  { limit: 5, window: 1000 } // 每秒 5 次调用
);

// 带状态管理和返回值
const [data, setData] = useState(null);
const { maybeExecute } = useAsyncRateLimiter(
  async (query) => {
    const result = await searchAPI(query);
    setData(result);
    return result; // 返回值可供调用者使用
  },
  {
    limit: 10,
    window: 60000, // 每分钟 10 次调用
    onReject: (rateLimiter) => {
      console.log(`已超出速率限制。请在 ${rateLimiter.getMsUntilNextWindow()} 毫秒后重试`);
    },
    onError: (error) => {
      console.error('API 调用失败：', error);
    }
  }
);