查询、变更与订阅

将 .input(zodSchema).query(async ({ input, ctx }) => ...) 链接到 publicProcedure 上。处理程序会接收经过验证的输入和请求上下文。您可以返回任何可序列化的值：对象、数组或原始值。

返回类型会自动推断，并成为客户端上对应 useQuery 钩子的数据类型。

trpc.post.getById.useQuery({ id: '1' }) 会调用文章路由器中的 getById 过程。该钩子会返回熟悉的 React 查询结果对象：{ data, isLoading, isError, refetch }。

输入对象具有静态类型：当模式要求字符串时传入 { id: 123 }，会产生 TypeScript 错误，并在开发时被捕获。

对于服务器端写入操作（创建、更新或删除数据），请使用 .input(zodSchema).mutation(async ({ input, ctx }) => ...)。变更操作需要显式调用，不会在组件挂载时自动运行。

变更处理程序可以通过 ctx 访问完整的请求上下文，其中包括来自 NextAuth 的会话。

const { mutate, isLoading, error } = trpc.post.create.useMutation()。调用 mutate({ title: 'New', content: '...' }) 来触发变更操作。与 React 查询的 useMutation 类似，它不会在组件挂载时运行。

将 onSuccess 和 onError 回调传入 useMutation 选项，以处理变更后的副作用。

要在变更成功后刷新查询数据，请使用 tRPC 实用工具钩子：const utils = trpc.useUtils()。在 onSuccess 中调用 utils.post.getAll.invalidate()，以触发文章列表的重新获取。

这相当于 React 查询的 queryClient.invalidateQueries()，并遵循相同的过期后重新获取模式。

tRPC 默认使用 Zod 验证输入。Zod 模式会在运行时于服务器上执行，在输入到达处理程序之前拒绝格式错误的输入。同一个模式还会为客户端提供 TypeScript 类型。

这种双重作用（运行时验证和 TypeScript 类型）消除了重复定义：您只需在 Zod 中定义一次契约，就能免费获得这两项安全保障。

默认情况下，tRPC 使用 httpBatchLink，将多个并发的 tRPC 请求批处理为一个 HTTP 请求。同一组件渲染周期内的多个 useQuery 调用会一起发送并一起解析。

与页面中每个查询都单独发出 HTTP 请求相比，这会显著减少网络开销。

定义订阅过程：publicProcedure.subscription(async function*() { while (true) { yield await nextEvent(); } })。订阅使用异步生成器，并且需要 WebSocket 传输。

订阅非常适合实时功能，例如实时通知、协作编辑光标或流式 AI 响应。

使用 splitLink 将 httpBatchLink 替换为 httpBatchLink 和 wsLink 的组合：将订阅路由到 wsLink，将查询和变更操作路由到 httpBatchLink。使用 createWSClient({ url: 'ws://localhost:3000' }) 创建 WebSocket 客户端。

这种混合传输意味着大多数请求使用高效的 HTTP 批处理，而订阅使用持久的 WebSocket 连接。

trpc.notifications.onNew.useSubscription(undefined, { onData: (notification) => addToList(notification), onError: console.error }) 会订阅该过程。每产生一个值，都会调用一次 onData 回调。

如果 WebSocket 断开后重新连接，订阅会自动重新建立。

一个实时列表页面可能会使用查询加载初始列表，使用变更操作添加项目，并使用订阅接收其他用户实时添加的项目。这三者都针对同一个 AppRouter 进行类型检查，并且可以自然地组合使用。

缓存失效策略取决于您更偏好完整重新获取（变更后使缓存失效），还是更新缓存（utils.post.getAll.setData）。

哪个 tRPC 实用工具方法会在变更成功后触发查询的重新获取？

使用 .query() 定义查询，使用 .mutation() 定义变更操作，并通过 Zod 模式验证二者。在客户端使用 trpc.router.procedure.useQuery() 和 useMutation()。变更后使用 utils.procedure.invalidate() 使查询失效。订阅使用异步生成器，并且需要 wsLink 作为 WebSocket 传输。

httpBatchLink 默认会将并发查询批处理为一个 HTTP 请求。