TypeScript Academy · 강의

tRPC 아키텍처

tRPC가 API 스키마 중복을 없애는 방식을 알아봅니다.

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

종단 간 문제

일반적인 웹 앱에서는 서버가 API를 정의하고 클라이언트가 이를 호출합니다. 둘의 타입을 동기화하기는 어렵습니다. 서버의 필드를 변경하면 클라이언트가 실행 시점에 조용히 망가질 수 있습니다. tRPC는 코드 생성 없이 타입을 직접 공유하여 이 문제를 해결합니다.

// Server: returns { id: number; name: string }
// Client: must know that shape exactly
// Without sync: runtime errors when they drift

tRPC란 무엇인가

tRPC는 TypeScript에서 완전히 타입이 지정된 API를 구축하기 위한 라이브러리입니다. 서버가 프로시저를 정의하면 클라이언트는 이를 로컬 함수처럼 호출할 수 있으며, 서버 코드에서 추론된 완전한 자동 완성과 타입 검사를 사용할 수 있습니다.

// Client call looks like a local function:
// const user = await client.user.byId.query(1);
// user is typed automatically from the server

코드 생성 없음

GraphQL 또는 OpenAPI 작업 흐름과 달리 tRPC에는 코드 생성 단계가 필요하지 않습니다. 컴파일할 스키마 파일도, 생성된 클라이언트도 없습니다. 타입은 컴파일 시점에 TypeScript 추론만을 통해 서버에서 클라이언트로 전달됩니다.

// No .graphql files, no generated SDK
// Just import a type from the server package

라우터가 계약입니다

tRPC의 중심은 라우터입니다. 라우터는 프로시저(조회와 변경 작업)의 트리입니다. 서버의 라우터 객체, 특히 그 객체에서 추론된 타입이 클라이언트와 공유되는 단일 진실 공급원입니다.

// appRouter (server) defines every procedure
// type AppRouter = typeof appRouter is the contract

유형 공유 방식

서버는 라우터의 유형만 내보내고 구현은 내보내지 않습니다. 클라이언트는 이 유형을 가져와 프록시 클라이언트의 유형을 지정하는 데 사용합니다. 서버 코드는 브라우저로 전송되지 않고, 빌드 시점에 제거되는 유형만 전송됩니다.

// server.ts
export type AppRouter = typeof appRouter;

// client.ts
import type { AppRouter } from '../server';

query 및 mutation

절차에는 두 가지 주요 종류가 있습니다. query는 데이터를 읽으며 일반적으로 멱등성을 가집니다. mutation은 데이터를 변경합니다. 이 구분은 캐싱 및 HTTP 의미 체계와 연결되며 클라이언트가 이를 호출하는 방식에도 영향을 줍니다.

// client.user.list.query()      -> read
// client.user.create.mutate(...) -> write

런타임과 유형

tRPC에는 두 개의 계층이 있습니다. 런타임에서는 호출이 HTTP를 통한 JSON 형식으로 이루어지고 어댑터가 처리합니다. 컴파일 시점에는 공유된 AppRouter 유형이 모든 호출을 완전히 검사합니다. 런타임은 얇고, 유형 안전성이 핵심 가치입니다.

// Runtime: POST /trpc/user.byId  body: {"input":1}
// Types: client.user.byId.query(1) is checked end to end

추론이 코드 생성을 능가하는 이유

유형이 추론되므로 잊어버릴 수 있는 동기화 단계가 없습니다. 절차를 수정하면 호출이 더 이상 일치하지 않는 위치에 즉시 빨간 물결 밑줄이 표시되어 클라이언트에도 변경 사항이 바로 반영됩니다. 피드백은 즉시 제공되며 편집기 안에서 확인할 수 있습니다.

// Add a required input field on the server
// -> every client call missing it becomes a type error

tRPC가 적합한 곳

tRPC는 Next.js 앱처럼 클라이언트와 서버가 하나의 코드베이스를 공유하는 풀스택 TypeScript 모노레포에서 특히 유용합니다. 다른 언어로 작성된 클라이언트가 사용하는 공개 API에는 적합하지 않습니다. 그런 경우에는 OpenAPI나 GraphQL처럼 언어에 구애받지 않는 스키마를 사용하는 것이 좋습니다.

// Great: Next.js app, shared types, internal API
// Not ideal: public API for non-TS consumers

전체 그림

흐름은 다음과 같습니다. 라우터에 절차를 정의하고, 라우터 유형을 내보내고, HTTP 어댑터를 연결한 다음, 해당 유형으로 유형이 지정된 클라이언트를 만듭니다. 생성된 코드 없이 모든 호출이 서버 계약에 맞는지 검사됩니다. 다음 레슨에서는 각 구성 요소를 하나씩 만들어 봅니다.

// Roadmap:
// 1. initTRPC + procedures + appRouter
// 2. export AppRouter, create typed client
// 3. context + middleware for auth

컴파일러를 신뢰하세요

관점을 바꿔야 합니다. API 계약은 문서나 런타임 검증만이 아니라 컴파일러가 강제하는 유형에 존재합니다. 컴파일되면 클라이언트와 서버가 서로 일치한다는 뜻입니다. 이것이 바로 "종단 간 유형 안전성"이 의미하는 보장입니다.

// If client.ts compiles, it matches the current server.

빠른 확인

tRPC 아키텍처에 대한 이해도를 확인해 보세요.

복습

tRPC 모델을 배웠습니다.

라우터가 계약이며, 라우터 유형이 유일한 기준입니다.
서버는 코드가 아니라 AppRouter 유형만 내보냅니다.
query는 읽고 mutation은 기록하며, 런타임에서는 HTTP를 통한 JSON을 사용합니다.
유형 안전성은 추론에서 나오므로 코드 생성 단계가 필요하지 않습니다.

다음 주제: 라우터와 절차 정의하기

자주 묻는 질문

“tRPC 아키텍처” 강의는 무료인가요?

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

“tRPC 아키텍처”에서 뭘 배우나요?

tRPC가 API 스키마 중복을 없애는 방식을 알아봅니다. 브라우저에서 직접 실행하는 실습 코드로 TypeScript Academy을(를) 배우며, 24/7 AI 튜터가 강의를 진행하면서 질문에 답변해줍니다.

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

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

“tRPC 아키텍처” 강의는 얼마나 걸리나요?

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

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

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

이 강의의 모든 강의

← TypeScript Academy(으)로 돌아가기