重试链接

非官方测试版翻译

本页面由 PageTurner AI 翻译（测试版）。未经项目官方认可。 发现错误？ 报告问题 →

retryLink 是一个链接组件，允许您在 tRPC 客户端中重试失败的操作。它提供了一种可定制的方式处理暂时性错误（如网络故障或服务器错误），根据预设条件自动重试失败的请求。

技巧

如果您使用 @trpc/react-query，通常不需要此链接，因为其功能已内置在 @tanstack/react-query 的 useQuery() 和 useMutation() 钩子中。

用法

创建 tRPC 客户端时，您可以将 retryLink 导入并添加到 links 数组中。根据需求，此链接可以放置在设置中的其他链接之前或之后。

ts
import { createTRPCClient, retryLink } from '@trpc/client';
const client = createTRPCClient<AppRouter>({
  links: [
    retryLink({
      retry(opts) {
        if (
          opts.error.data &&
          opts.error.data.code !== 'INTERNAL_SERVER_ERROR'
        ) {
          // Don't retry on non-500s
          return false;
        }
        if (opts.op.type !== 'query') {
          // Only retry queries
          return false;
        }
        // Retry up to 3 times
        return opts.attempts <= 3;
      },
      // Double every attempt, with max of 30 seconds (starting at 1 second)
      retryDelayMs: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 30000),
    }),
    httpBatchLink({
      url: 'http://localhost:3000',
    }),
  ],
});

ts
import { createTRPCClient, retryLink } from '@trpc/client';
const client = createTRPCClient<AppRouter>({
  links: [
    retryLink({
      retry(opts) {
        if (
          opts.error.data &&
          opts.error.data.code !== 'INTERNAL_SERVER_ERROR'
        ) {
          // Don't retry on non-500s
          return false;
        }
        if (opts.op.type !== 'query') {
          // Only retry queries
          return false;
        }
        // Retry up to 3 times
        return opts.attempts <= 3;
      },
      // Double every attempt, with max of 30 seconds (starting at 1 second)
      retryDelayMs: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 30000),
    }),
    httpBatchLink({
      url: 'http://localhost:3000',
    }),
  ],
});

在上面的示例中，我们将 retryLink 放在 httpBatchLink 之前。默认情况下，retryLink 会：

• 当错误是状态码为 500 的 TRPCClientError 或无法获取有效 TRPC 错误时，自动重试请求

• 最多重试请求 3 次

您可以通过提供自定义的 retry 函数来定制重试逻辑。

选项

ts
interface RetryLinkOptions<TInferrable extends InferrableClientTypes> {
  /**
   * The retry function
   */
  retry: (opts: RetryFnOptions<TInferrable>) => boolean;
  /**
   * The delay between retries in ms (defaults to 0)
   */
  retryDelayMs?: (attempt: number) => number;
}
interface RetryFnOptions<TInferrable extends InferrableClientTypes> {
  /**
   * The operation that failed
   */
  op: Operation;
  /**
   * The error that occurred
   */
  error: TRPCClientError<TInferrable>;
  /**
   * The number of attempts that have been made (including the first call)
   */
  attempts: number;
}

ts
interface RetryLinkOptions<TInferrable extends InferrableClientTypes> {
  /**
   * The retry function
   */
  retry: (opts: RetryFnOptions<TInferrable>) => boolean;
  /**
   * The delay between retries in ms (defaults to 0)
   */
  retryDelayMs?: (attempt: number) => number;
}
interface RetryFnOptions<TInferrable extends InferrableClientTypes> {
  /**
   * The operation that failed
   */
  op: Operation;
  /**
   * The error that occurred
   */
  error: TRPCClientError<TInferrable>;
  /**
   * The number of attempts that have been made (including the first call)
   */
  attempts: number;
}

处理 tracked() 事件

当 retryLink 与使用 tracked() 的订阅结合使用时，该链接在重试时会自动包含最后已知的事件 ID。这确保了订阅重新连接时能从中断处继续，不会遗漏任何事件。

例如，当您在 httpSubscriptionLink 中使用 Server-sent Events (SSE) 时，遇到 401 Unauthorized 等错误时，retryLink 会自动处理携带最后事件 ID 的重新连接。