将 tRPC 与 React Query 和身份验证集成

tRPC 上下文是由 createTRPCContext 函数为每个请求新建的对象。它可以包含数据库客户端、经过身份验证的会话、请求标头，或您的过程所需的任何请求专属数据。

上下文创建会在任何过程执行之前运行，因此非常适合在此处设置身份验证和数据库连接。

在 createTRPCContext 中，请从 next-auth/next 调用 getServerSession(authOptions)。将结果附加到上下文对象：return { session: await getServerSession(authOptions), db }。现在所有过程都可以访问 ctx.session。

如果会话为 null，则用户未通过身份验证。过程可以据此有条件地返回数据或抛出错误。

定义一个检查 ctx.session 的中间件：const isAuthenticated = t.middleware(({ ctx, next }) => { if (!ctx.session) throw new TRPCError({ code: 'UNAUTHORIZED' }); return next({ ctx: { session: ctx.session } }); })。

next() 调用会将经过收窄的上下文（会话不为空）传递给后续中间件和过程处理函数。

将中间件与 publicProcedure 组合起来：const protectedProcedure = publicProcedure.use(isAuthenticated)。现在，使用 protectedProcedure.query() 或 protectedProcedure.mutation() 定义的任何处理函数都会自动在 ctx 中获得非空会话。

TypeScript 能推断出受保护过程中 ctx.session 不为空，因为如果中间件检查失败，处理函数就不会被执行。

对于要求身份验证的端点，请将 publicProcedure 替换为 protectedProcedure：protectedProcedure.query(({ ctx }) => getProfileFor(ctx.session.user.id))。TypeScript 知道此处的 ctx.session 不为空，因此无需进行空值检查即可安全访问 ctx.session.user.id。

未通过身份验证的请求会在处理函数执行前自动收到 401 UNAUTHORIZED 响应。

向 httpBatchLink 传递一个标头函数：links: [httpBatchLink({ url: '/api/trpc', headers: async () => { const token = await getToken(); return { Authorization: 'Bearer ' + token }; } })]。该函数会在每一批请求之前运行。

当您从 React Native 客户端或任何自行管理身份验证令牌的非 Next.js 客户端对 tRPC 进行身份验证时，会使用这种方式。

对于 Next.js Pages Router 中的 SSR，请创建服务器端辅助工具：createServerSideHelpers({ router: appRouter, ctx: await createContext({ req, res }) })。在 getServerSideProps 中使用 helpers.post.getAll.prefetch()。

使用 dehydrate(queryClient) 将预获取的状态进行脱水，并将其作为属性传递。在客户端，QueryClient 会从该状态完成水合，从而避免首次加载时再次获取数据。

请使用来自 @tanstack/react-query 的 Hydrate 包裹 Next.js 的 _app.tsx。将 pageProps.trpcState 传递给 state 属性。这样，客户端就能根据序列化的服务器状态恢复预获取的查询缓存。

通过这种设置，用户在初次导航时会立即看到内容完整的页面，无需等待客户端加载旋转指示器。

请使用恰当的 HTTP 语义代码抛出 TRPCError：UNAUTHORIZED（401）、FORBIDDEN（403）、NOT_FOUND（404）、BAD_REQUEST（400）、INTERNAL_SERVER_ERROR（500）。tRPC 客户端会将这些代码映射为钩子结果中相应的错误状态。

message 字段可以包含面向用户的详细信息，但在生产环境的错误消息中应避免泄露敏感的服务器信息。

tRPC 可以与使用相同 AppRouter 类型的 React Native 客户端配合使用。请将 httpBatchLink 替换为 httpLink（RN fetch 的工作方式相同），并配置身份验证标头。@trpc/react-query 适配器与网页端设置的工作方式完全相同。

这意味着单一代码仓库可以在 Next.js 网页应用和 Expo React Native 应用之间共享一个 tRPC 路由器，并在两端都获得完整的类型安全。

请扩展中间件模式以实现基于角色的访问控制：检查 ctx.session.user.role，如果角色权限不足，则抛出 TRPCError({ code: 'FORBIDDEN' })。请创建 adminProcedure = publicProcedure.use(isAdmin)，用于仅限管理员访问的端点。

对于复杂的授权，可以叠加多个中间件：publicProcedure.use(isAuthenticated).use(hasFeatureFlag('beta')).query(...)。

在 tRPC 中，如何创建受保护的过程来强制执行身份验证？

tRPC 上下文按请求创建，其中包含会话、数据库客户端及其他请求范围内的数据。受保护的过程通过将检查会话的中间件使用 .use() 组合到 publicProcedure 上来创建。服务器端渲染使用 createServerSideHelpers 进行预获取，并使用 Hydrate 在客户端恢复缓存。

对于非 Next.js 客户端，请通过 httpBatchLink 的 headers 选项传递身份验证标头。