TypeScript Academy · 강의

라우터와 프로시저 정의

입력 검증을 포함한 쿼리와 변경 작업을 구축합니다.

라우터와 프로시저 정의은(는) CoddyKit의 무료 TypeScript Academy 강의입니다. 이것은 4개 중 2번째 강의입니다. 아래에서 전체 강의를 무료로 읽을 수 있으며, 내장 코드 에디터와 24/7 AI 튜터와 함께 브라우저에서 직접 실습할 수 있습니다. 이 강의는 TypeScript Academy 학습 경로의 일부이며, 진행 상황이 웹과 CoddyKit 앱에 동기화됩니다. TypeScript Academy 강의에는 총 4개의 강의가 포함되어 있습니다.

tRPC 초기화

모든 tRPC 백엔드는 initTRPC로 인스턴스를 만드는 것에서 시작합니다. 이 인스턴스는 라우터와 절차를 만들기 위한 빌더를 반환합니다. 일반적으로 한 번만 만들고 필요한 구성 요소를 내보냅니다.

import { initTRPC } from '@trpc/server';

const t = initTRPC.create();
export const router = t.router;
export const publicProcedure = t.procedure;

첫 번째 절차

절차는 하나의 API 엔드포인트입니다. 가장 단순한 절차는 값을 반환하는 query입니다. publicProcedure.query는 입력이 없는 읽기 전용 엔드포인트를 정의합니다.

import { router, publicProcedure } from './trpc';

const appRouter = router({
  health: publicProcedure.query(() => 'ok'),
});

입력 검증

절차는 검증기를 사용해 입력을 선언하며, 일반적으로 조드 스키마를 사용합니다. .input(schema)는 런타임에서 입력을 검증하는 동시에 리졸버와 클라이언트의 입력 유형을 추론합니다.

import { z } from 'zod';

const greet = publicProcedure
  .input(z.object({ name: z.string() }))
  .query(({ input }) => 'Hello, ' + input.name);

입력 읽기

리졸버 내부에서는 검증된 입력을 input으로 사용할 수 있으며, 스키마에 따라 유형이 완전히 지정됩니다. 수동으로 형변환할 필요가 없습니다. 조드와 tRPC가 입력 형태를 함께 추론합니다.

const byId = publicProcedure
  .input(z.object({ id: z.number() }))
  .query(({ input }) => {
    // input.id is number
    return { id: input.id, name: 'Alice' };
  });

mutation

데이터를 변경하는 작업에는 .mutation을 사용합니다. 형태는 query와 같지만 기록 작업임을 나타내므로 클라이언트 캐싱과 HTTP 메서드에 영향을 줍니다.

const createUser = publicProcedure
  .input(z.object({ name: z.string() }))
  .mutation(({ input }) => {
    return { id: 1, name: input.name };
  });

앱 라우터 만들기

router(...)에 객체를 전달해 절차를 라우터에 모읍니다. 각 키가 호출 가능한 절차 이름이 됩니다. 이 appRouter가 전체 API입니다.

const appRouter = router({
  greet,
  byId,
  createUser,
});

중첩 라우터

대규모 API를 체계적으로 구성하려면 라우터를 중첩합니다. 라우터 객체의 값 자체가 라우터일 수 있으며, 그러면 user.byId와 같은 네임스페이스가 포함된 호출을 만들 수 있습니다.

const userRouter = router({ byId, createUser });

const appRouter = router({
  user: userRouter,
  greet,
});
// call paths: user.byId, user.createUser, greet

라우터 유형 내보내기

가장 중요한 내보내기는 라우터 유형입니다. 클라이언트는 이 유형을 가져와 완전한 유형 안전성을 얻습니다. 서버 어댑터에는 값을, 클라이언트에는 유형을 내보내세요.

export const appRouter = router({ user: userRouter });
export type AppRouter = typeof appRouter;

어댑터 연결하기

HTTP를 통해 라우터를 제공하려면 어댑터를 연결해야 합니다. tRPC는 독립 실행형 노드, 익스프레스, Next.js, 페치 등을 위한 어댑터를 제공합니다. 어댑터는 들어오는 요청을 절차 호출로 변환합니다.

import { createHTTPServer } from '@trpc/server/adapters/standalone';

createHTTPServer({ router: appRouter }).listen(3000);

파일 구성하기

일반적인 구성은 다음과 같습니다. initTRPC와 내보낸 router/publicProcedure를 담은 trpc.ts, 각각 별도의 파일에 둔 기능별 라우터, 그리고 이들을 조합하는 루트 appRouter입니다. initTRPC를 한곳에 두면 여러 인스턴스가 생기는 것을 방지할 수 있습니다.

// trpc.ts: initTRPC.create(), export router + publicProcedure
// routers/user.ts: userRouter
// router.ts: appRouter = router({ user: userRouter })

입력 추론 복습

.input(schema)은 검증과 추론을 모두 수행하므로 스키마를 한 번만 작성하면 런타임 보호 기능과 정적 유형을 함께 얻을 수 있습니다. 클라이언트는 이 스키마에서 파생된 각 절차가 정확히 어떤 입력을 기대하는지 알 수 있습니다.

const search = publicProcedure
  .input(z.object({ q: z.string(), page: z.number().optional() }))
  .query(({ input }) => ({ q: input.q, page: input.page ?? 1 }));

빠른 확인

라우터와 절차에 대한 이해도를 확인해 보세요.

복습

tRPC 백엔드를 만들었습니다.

initTRPC.create()는 router 및 procedure 빌더를 제공합니다.
.input(schema)은 입력을 검증하고 추론합니다.
.query는 읽고, .mutation은 기록합니다.
절차를 appRouter로 조합하고 type AppRouter = typeof appRouter를 내보냅니다.

다음 주제: 유형이 완전히 지정된 클라이언트로 사용하기

자주 묻는 질문

“라우터와 프로시저 정의” 강의는 무료인가요?

네 — “라우터와 프로시저 정의” 전체 내용을 이 웹사이트에서 무료로 읽을 수 있습니다. 인터랙티브하게 실습하려면(내장 코드 에디터와 24/7 AI 튜터), CoddyKit PRO로 업그레이드하면 TypeScript Academy 강의 전체를 잠금 해제할 수 있습니다. TypeScript Academy 강의에는 총 4개의 강의가 포함되어 있습니다.

“라우터와 프로시저 정의”에서 뭘 배우나요?

입력 검증을 포함한 쿼리와 변경 작업을 구축합니다. 브라우저에서 직접 실행하는 실습 코드로 TypeScript Academy을(를) 배우며, 24/7 AI 튜터가 강의를 진행하면서 질문에 답변해줍니다.

TypeScript Academy을(를) 시작하는 데 경험이 필요한가요?

사전 경험은 필요하지 않습니다. CoddyKit의 TypeScript Academy은(는) 초급자부터 고급 학습자까지를 위해 구성되어 있으므로, 여기서 시작하거나 처음부터 시작할 수 있으며 자신의 속도대로 진행할 수 있습니다. 이것은 4개 중 2번째 강의입니다.

“라우터와 프로시저 정의” 강의는 얼마나 걸리나요?

대부분의 CoddyKit 강의는 약 5~10분이 소요됩니다. 각 강의는 간결하고 인터랙티브하여 꾸준한 진행이 가능하며, 웹과 앱에서 중단한 부분부터 바로 시작할 수 있습니다.

이 TypeScript Academy 강의에서 코드를 작성하고 실행할 수 있나요?

네. 모든 TypeScript Academy 강의에는 내장 코드 에디터가 포함되어 있으므로, 브라우저에서 바로 실제 코드를 작성하고 실행한 후 즉시 AI 피드백을 받을 수 있습니다 — 로컬 설정이 필요 없습니다.

이 강의의 모든 강의

← TypeScript Academy(으)로 돌아가기