跳至主内容
版本：10.x

HTTP 批处理流式链接

非官方测试版翻译

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

unstable_httpBatchStreamLink 是一个终止链接，它将多个独立的 tRPC 操作批量打包成单个 HTTP 请求发送到 tRPC 过程（相当于 httpBatchLink），但不会等待批处理中所有响应准备完成，而是在任何数据可用时立即流式传输响应。

信息

由于这是新 API，我们为其添加了 unstable_ 前缀，但你可以安全使用！了解更多。

用法​

所有用法和选项均与 httpBatchLink 完全相同。

备注

如果需要在过程内部更改/设置响应头（包括 cookies），请务必改用 httpBatchLink！这是因为 unstable_httpBatchStreamLink 在流式传输开始后不支持设置响应头。了解更多。

您可以通过以下方式导入并将 httpBatchStreamLink 添加到 links 数组：

client/index.ts
ts
import { createTRPCProxyClient, httpBatchStreamLink } from '@trpc/client';
import type { AppRouter } from '../server';
const client = createTRPCProxyClient<AppRouter>({
  links: [
    httpBatchStreamLink({
      url: 'http://localhost:3000',
    }),
  ],
});
client/index.ts
ts
import { createTRPCProxyClient, httpBatchStreamLink } from '@trpc/client';
import type { AppRouter } from '../server';
const client = createTRPCProxyClient<AppRouter>({
  links: [
    httpBatchStreamLink({
      url: 'http://localhost:3000',
    }),
  ],
});

之后，您可以通过将所有过程放入 Promise.all 来利用批处理功能。以下代码将产生仅一次 HTTP 请求，在服务器端执行仅一次数据库查询：

ts
const somePosts = await Promise.all([
  trpc.post.byId.query(1),
  trpc.post.byId.query(2),
  trpc.post.byId.query(3),
]);
ts
const somePosts = await Promise.all([
  trpc.post.byId.query(1),
  trpc.post.byId.query(2),
  trpc.post.byId.query(3),
]);

流式模式​

⚠️ 此链接处于不稳定状态，未来可能发生变化。

当批量处理请求时，常规 httpBatchLink 的行为是等待所有请求完成后再发送响应。如果您希望在响应就绪时立即发送，可以改用 httpBatchStreamLink。这对于长时间运行的请求非常有用。

client/index.ts
ts
import {
  createTRPCProxyClient,
  unstable_httpBatchStreamLink,
} from '@trpc/client';
import type { AppRouter } from '../server';
const client = createTRPCProxyClient<AppRouter>({
  links: [
    unstable_httpBatchStreamLink({
      url: 'http://localhost:3000',
    }),
  ],
});
client/index.ts
ts
import {
  createTRPCProxyClient,
  unstable_httpBatchStreamLink,
} from '@trpc/client';
import type { AppRouter } from '../server';
const client = createTRPCProxyClient<AppRouter>({
  links: [
    unstable_httpBatchStreamLink({
      url: 'http://localhost:3000',
    }),
  ],
});

相比常规 httpBatchLink，unstable_httpBatchStreamLink 会：

  • 在请求中添加 Trpc-Batch-Mode: stream 标头

  • 在响应中添加 Transfer-Encoding: chunked 和 Vary: trpc-batch-mode 标头

  • 从传递给 responseMeta 的参数对象中移除 data 键（因为使用流式响应时，标头在数据可用前就已发送）

兼容性（客户端）​

浏览器​

浏览器支持应与 fetch 支持范围相同。

Node.js / Deno​

对于非浏览器运行时，fetch 实现需支持流式传输，即通过 await fetch(...) 获取的响应应具有类型为 ReadableStream<Uint8Array> | NodeJS.ReadableStream 的 body 属性，这意味着：

  • response.body.getReader 是返回 ReadableStreamDefaultReader<Uint8Array> 对象的函数

  • 或 response.body 是 Uint8Array 类型的 Buffer

这包括对 undici、node-fetch、原生 Node.js fetch 实现和 WebAPI fetch 实现（浏览器）的支持。

React Native​

接收流依赖 TextDecoder API，而 React Native 不支持此 API。若仍需启用流式传输，可使用 polyfill 并将其传递给 httpBatchStreamLink 选项：

ts
unstable_httpBatchStreamLink({
  url: 'http://localhost:3000',
  textDecoder: new TextDecoder(),
  // ^? textDecoder: { decode: (input: Uint8Array) => string }
});
ts
unstable_httpBatchStreamLink({
  url: 'http://localhost:3000',
  textDecoder: new TextDecoder(),
  // ^? textDecoder: { decode: (input: Uint8Array) => string }
});

兼容性（服务端）​

⚠️ 在 AWS Lambda 中，unstable_httpBatchStreamLink 不受支持（将退化为常规 httpBatchLink 行为）。启用后不会导致错误，但不会产生实际效果。

⚠️ 在 Cloudflare Workers 中，需通过特性标志启用 ReadableStream API：streams_enable_constructors

参考文档​

您可以在 GitHub 查看此链接的源代码。