tRPC를 React Query 및 인증과 통합하기

tRPC 컨텍스트는 createTRPCContext 함수가 요청마다 새로 만드는 객체입니다. 이 객체에는 데이터베이스 클라이언트, 인증된 세션, 요청 헤더 또는 프로시저에 필요한 요청별 데이터를 담을 수 있습니다.

컨텍스트 생성은 모든 프로시저보다 먼저 실행되므로 인증과 데이터베이스 연결 설정에 적합한 위치입니다.

createTRPCContext에서 next-auth/next의 getServerSession(authOptions)을 호출하십시오. 결과를 컨텍스트 객체에 연결하십시오. return { session: await getServerSession(authOptions), db }와 같이 작성합니다. 이제 모든 프로시저에서 ctx.session에 접근할 수 있습니다.

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() 호출은 범위가 좁혀진 컨텍스트(null이 아닌 세션)를 이후 미들웨어와 프로시저 처리기에 전달합니다.

미들웨어를 publicProcedure과 결합하십시오. const protectedProcedure = publicProcedure.use(isAuthenticated). 이제 protectedProcedure.query() 또는 protectedProcedure.mutation()으로 정의된 모든 처리기에서 ctx의 세션이 자동으로 null이 아니게 됩니다.

미들웨어가 처리기에 도달하기 전에 오류를 발생시키므로 TypeScript는 보호된 프로시저 내부에서 ctx.session이 null이 아님을 추론합니다.

인증이 필요한 엔드포인트에는 publicProcedure 대신 protectedProcedure을 사용하십시오. protectedProcedure.query(({ ctx }) => getProfileFor(ctx.session.user.id))와 같이 작성합니다. 여기서 TypeScript는 ctx.session이 null이 아님을 알고 있으므로 null 확인 없이 ctx.session.user.id에 안전하게 접근할 수 있습니다.

인증되지 않은 요청은 처리기가 실행되기 전에 자동으로 401 UNAUTHORIZED 응답을 받습니다.

httpBatchLink에 헤더 함수를 전달하십시오. links: [httpBatchLink({ url: '/api/trpc', headers: async () => { const token = await getToken(); return { Authorization: 'Bearer ' + token }; } })]. 이 함수는 요청 묶음이 실행되기 전에 매번 실행됩니다.

이는 리액트 네이티브 클라이언트나 자체 인증 토큰을 관리하는 비-Next.js 클라이언트에서 tRPC를 인증할 때 사용합니다.

Next.js Pages Router에서 SSR을 사용하려면 서버 측 헬퍼를 만드십시오. createServerSideHelpers({ router: appRouter, ctx: await createContext({ req, res }) })와 같이 작성합니다. getServerSideProps에서 helpers.post.getAll.prefetch()를 사용하십시오.

미리 가져온 상태를 dehydrate(queryClient)로 직렬화하여 props로 전달하십시오. 클라이언트에서는 QueryClient가 이 상태에서 캐시를 복원하므로 최초 로드 시 다시 가져오는 작업을 방지할 수 있습니다.

Next.js _app.tsx를 @tanstack/react-query의 Hydrate로 감싸십시오. state 속성에 pageProps.trpcState를 전달하십시오. 그러면 직렬화된 서버 상태에서 미리 가져온 쿼리 캐시가 클라이언트에 복원됩니다.

이렇게 설정하면 사용자는 최초 탐색 시 클라이언트 측 로딩 표시기 없이 데이터가 완전히 채워진 페이지를 즉시 볼 수 있습니다.

적절한 HTTP 의미론적 코드와 함께 TRPCError를 발생시키십시오. UNAUTHORIZED (401), FORBIDDEN (403), NOT_FOUND (404), BAD_REQUEST (400), INTERNAL_SERVER_ERROR (500)을 사용합니다. tRPC 클라이언트는 이러한 코드를 훅 결과의 적절한 오류 상태로 매핑합니다.

message 필드에는 사용자에게 표시할 세부 정보를 담을 수 있지만, 실제 운영 환경의 오류 메시지에 민감한 서버 정보가 노출되지 않도록 주의하십시오.

tRPC는 동일한 AppRouter 타입을 사용하는 리액트 네이티브 클라이언트에서도 작동합니다. httpBatchLink를 httpLink로 바꾸고 인증 헤더를 설정하십시오. RN의 가져오기 기능도 동일하게 작동하며, @trpc/react-query 어댑터는 웹 설정과 똑같이 작동합니다.

따라서 모노레포는 하나의 tRPC 라우터를 Next.js 웹 앱과 Expo 리액트 네이티브 앱에서 공유하면서 양쪽 모두 완전한 타입 안전성을 확보할 수 있습니다.

역할 기반 접근을 위해 미들웨어 패턴을 확장하십시오. ctx.session.user.role을 확인하고 역할이 충분하지 않으면 TRPCError({ code: 'FORBIDDEN' })를 발생시키십시오. 관리자 전용 엔드포인트에는 adminProcedure = publicProcedure.use(isAdmin)을 만드십시오.

복잡한 권한 부여를 위해 여러 미들웨어를 연결할 수 있습니다. publicProcedure.use(isAuthenticated).use(hasFeatureFlag('beta')).query(...)와 같이 작성합니다.

tRPC 컨텍스트는 요청마다 생성되며 세션, 데이터베이스 클라이언트 및 기타 요청 범위 데이터를 담습니다. 보호된 프로시저는 세션을 확인하는 미들웨어를 publicProcedure에 .use()로 결합하여 만듭니다. 서버 측 렌더링에서는 미리 가져오기를 위해 createServerSideHelpers를 사용하고, 클라이언트에서는 캐시를 복원하기 위해 Hydrate를 사용합니다.

Next.js가 아닌 클라이언트의 인증 헤더는 httpBatchLink의 headers 옵션을 통해 전달합니다.