효율적인 Typescript 백엔드 구축을 위한 TRPC의 기초 블록 이해하기

2025-03-16 01:16:49

typescriptnextjsapireact

TRPC의 이해: Typescript 백엔드를 위한 기초 블록

TRPC는 최근 Typescript 백엔드 개발에서 큰 인기를 끌고 있는 툴입니다. NextJS와의 결합으로 주목받고 있지만, Deno, Bun 같은 다양한 Typescript 프레임워크에서도 효율성을 높일 수 있습니다. 이번 글에서는 TRPC의 기초 블록에 대해 살펴보고, IT 전문가의 관점에서 어떻게 이점을 가져갈 수 있는지 논의해 보겠습니다.

TRPC의 표준 구성에 대한 개요

TRPC의 표준 구성은 T3 Stack에서 기본적으로 제공하는 설정을 기반으로 하고 있습니다. 이는 TRPC를 NextJS 프로젝트에 통합할 때 거의 사실상 표준으로 자리 잡았으며, TRPC 통합의 모범 사례로 간주됩니다. T3 Stack 프로젝트를 생성하고 TRPC를 선택하여 이를 익히는 것이 좋습니다.

TRPC의 시각화

TRPC를 이해하는 데 시각화는 큰 도움이 됩니다. 다만, 이 글의 다이어그램은 100% 정확하지는 않으니 공식 문서를 참고하는 것을 권장합니다.

컨텍스트(Context)의 중요성

TRPC에서 '컨텍스트'는 간단하지만 필수적인 개념입니다. 모든 프로시저가 접근할 수 있는 정보를 뜻하며, TRPC의 계층 구조 전반에 영향을 미칩니다.

// src/trpc/server.ts
export const createTRPCContext = async (opts: { headers: Headers }) => {
    const session = await getServerAuthSession();

    return {
        db,
        session,
        ...opts,
    };
};

컨텍스트는 데이터베이스 객체, 세션 객체, 그리고 요청에서 온 헤더를 포함하여 모든 프로시저에서 접근할 수 있도록 구성됩니다.

TRPC 객체 "t"의 역할

TRPC 객체는 관련된 요소의 모음이며, "t"라는 이름으로 불립니다. 이 개념은 타입 안전성을 보장하며, 데이터 전송 시 superjson 같은 변환기와 zod 에러 포맷터를 통해 오류를 정확히 기술합니다.

// src/server/api/trpc.ts
const t = initTRPC.context<typeof createTRPCContext>().create({
    transformer: superjson,
    errorFormatter({ shape, error }) {
        return {
            ...shape,
            data: {
                ...shape.data,
                zodError:
                    error.cause instanceof ZodError ? error.cause.flatten() : null,
            },
        };
    },
});

Caller: 절차 호출하기

Caller는 프로시저를 호출하는 자바스크립트 코드의 일부분입니다. 표준 구성에서는 헬퍼 함수로 생성되어, 클라이언트 자바스크립트에 주입됩니다.

// src/server/api/trpc.ts
export const createCallerFactory = t.createCallerFactory;

// src/server/api/root.ts
export const createCaller = createCallerFactory(appRouter);

Caller를 통해 프로시저를 호출할 수 있으며, 서버 이벤트나 API 경로 등 필요한 곳 어디에서든 사용할 수 있습니다.

Router: 논리적 절차의 집합

Router는 절차의 논리적인 모음으로, 계층 구조로 그룹화할 수 있습니다. 표준 구성에서는 게시물, 댓글 등 다양한 경로를 만들어 AppRouter에 통합합니다.

// src/server/api/root.ts
export const appRouter = createTRPCRouter({
  post: postRouter,
  comment: commentRouter,
});

클라이언트 코드에서는 특정 라우터의 캐시를 무효화하고 데이터 재요청을 강제할 수 있어 유용합니다.

await utils.comment.invalidate();

Procedure: 작업 단위

프로시저는 TRPC의 기본 작업 단위이며, 각기 다른 미들웨어를 통해 다양한 프로시저 타입을 생성할 수 있습니다. 주로 사용되는 프로시저 타입에는 공개 및 보호된 프로시저가 있습니다.

// src/server/api/trpc.ts
export const publicProcedure = t.procedure.use(timingMiddleware);

// src/server/api/trpc.ts
export const protectedProcedure = t.procedure
  .use(timingMiddleware)
  .use(({ ctx, next }) => {
    if (!ctx.session || !ctx.session.user) {
      throw new TRPCError({ code: "UNAUTHORIZED" });
    }
    return next({
      ctx: {
        session: { ...ctx.session, user: ctx.session.user },
      },
    });
  });

공개 프로시저는 누구나 접근할 수 있으며, 보호된 프로시저는 인증된 사용자만이 이용할 수 있습니다. 이는 사용자 역할에 따라 더 세분화하여 사용할 수도 있습니다.

결론

TRPC는 Typescript 백엔드 개발에 있어 강력한 도구로 자리 잡았습니다. 프로그램의 다양한 부분을 체계적으로 조직할 수 있는 유연성과 효율성을 제공합니다. TRPC의 다양한 블록을 제대로 이해하고 활용하면, 더 나은 성능을 가진 어플리케이션을 구축할 수 있습니다. 이 글의 내용이 도움이 되었다면 TRPC의 공식 문서와 관련 링크를 통해 추가 정보를 탐색해보세요.

백링크: TRPC 공식 문서