TypeScript Academy · 강의

클라이언트-서버 타입 추론

코드 생성 없이 완전히 타입이 지정된 클라이언트를 사용합니다.

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

라우터 유형 공유

클라이언트는 서버 라우터 유형을 가져와 유형 안전성을 얻습니다. 이는 유형만 가져오는 방식이므로 서버의 어떤 코드도 클라이언트에서 실행되지 않고 정적 계약만 경계를 넘어갑니다.

import type { AppRouter } from '../server/router';
// type-only import - erased at build time

유형이 지정된 클라이언트 만들기

AppRouter를 유형 매개변수로 지정해 createTRPCClient 또는 프록시 변형을 사용합니다. 그러면 클라이언트 객체가 서버 라우터의 형태를 그대로 반영하며 모든 절차에 대한 자동 완성을 완전히 지원합니다.

import { createTRPCClient, httpBatchLink } from '@trpc/client';

const client = createTRPCClient<AppRouter>({
  links: [httpBatchLink({ url: 'http://localhost:3000' })],
});

절차 호출하기

호출 방식은 라우터 트리를 그대로 따릅니다. 중첩된 절차 user.byId에는 client.user.byId로 접근하고, 그 위에서 .query 또는 .mutate를 호출합니다. 입력과 출력의 유형은 서버에서 가져옵니다.

const user = await client.user.byId.query({ id: 1 });
// user is typed exactly as the server resolver returns

추론된 입력

클라이언트는 서버 스키마를 통해 각 절차의 입력을 알고 있습니다. 잘못된 형태를 전달하면 앱을 실행하기도 전에 컴파일 오류가 발생합니다.

await client.user.byId.query({ id: 1 });   // ok
// await client.user.byId.query({ id: 'x' }); // error: id must be number
// await client.user.byId.query({});          // error: id is required

추론된 출력

반환 유형도 전달됩니다. query의 결과값은 서버 리졸버가 반환하는 값과 정확히 같으므로 이후 코드도 완전히 검사됩니다.

const u = await client.user.byId.query({ id: 1 });
const name: string = u.name; // ok if server returns name: string

클라이언트에서 mutation 사용하기

mutation은 .mutate로 호출합니다. 동일한 추론이 적용됩니다. 입력은 스키마로 검증된 유형을 사용하고, 출력은 리졸버에서 유형을 가져옵니다.

const created = await client.user.create.mutate({ name: 'Bea' });
// created is typed from the create resolver's return

추론 흐름

유형이 어떻게 전달되는지 따라가 보세요. 서버의 조드 스키마에서 입력 유형을 추론하고, 리졸버의 반환값에서 출력 유형을 추론하며, typeof appRouter가 두 유형을 AppRouter에 담고, 클라이언트가 해당 유형을 호출 가능한 메서드에 매핑합니다. 한 번의 변경이 자동으로 전체에 전달됩니다.

// schema -> input type
// resolver -> output type
// appRouter -> AppRouter (both captured)
// client<AppRouter> -> typed calls

도우미 유형 추론하기

tRPC는 리액트 구성 요소 등에서 재사용할 수 있도록 입력 및 출력 유형을 추출하는 도우미를 제공합니다. inferRouterInputs와 inferRouterOutputs를 사용하면 AppRouter에서 이러한 매핑을 얻을 수 있습니다.

import type { inferRouterOutputs } from '@trpc/server';

type Outputs = inferRouterOutputs<AppRouter>;
type User = Outputs['user']['byId'];

불일치 방지 보장

클라이언트가 현재 라우터 유형으로 유형이 지정되므로 서버와 클라이언트는 서로 불일치할 수 없습니다. 절차 이름을 바꾸거나 입력을 변경하면 호출을 업데이트할 때까지 클라이언트가 컴파일되지 않습니다. 컴파일러가 계약 테스트 역할을 합니다.

// Server renames user.byId -> user.find
// client.user.byId becomes a type error immediately

일괄 처리와 링크

links 배열은 전송 방식을 설정합니다. httpBatchLink는 같은 틱에 이루어진 여러 호출을 하나의 HTTP 요청으로 묶어 왕복 통신을 줄입니다. 이는 유형에는 영향을 주지 않는 런타임 최적화입니다.

links: [httpBatchLink({ url: '/trpc' })]
// Several .query calls in one tick -> one request

실제 종단 간 사용

결과적으로 client.user.byId.query(...)를 로컬 함수처럼 호출할 수 있습니다. 입력 자동 완성, 인수 검사, 유형이 지정된 결과를 모두 지원하며, 이 모든 정보는 생성된 파일 없이 서버 코드에서 파생됩니다. 이것이 추론을 통해 제공되는 종단 간 유형 안전성입니다.

const u = await client.user.byId.query({ id: 7 });
console.log(u.name); // fully typed, no codegen

빠른 확인

클라이언트와 서버의 추론에 대한 이해도를 확인해 보세요.

복습

완전한 유형 안전성을 갖춘 tRPC API를 사용했습니다.

AppRouter를 유형만 가져오는 방식으로 가져옵니다.
createTRPCClient<AppRouter>는 라우터 트리를 그대로 반영합니다.
입력과 출력은 서버 스키마 및 리졸버에서 추론됩니다.
클라이언트와 서버는 서로 불일치할 수 없으며, 컴파일러가 계약을 강제합니다.

다음 주제: 인증을 위한 컨텍스트와 middleware

자주 묻는 질문

“클라이언트-서버 타입 추론” 강의는 무료인가요?

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

“클라이언트-서버 타입 추론”에서 뭘 배우나요?

코드 생성 없이 완전히 타입이 지정된 클라이언트를 사용합니다. 브라우저에서 직접 실행하는 실습 코드로 TypeScript Academy을(를) 배우며, 24/7 AI 튜터가 강의를 진행하면서 질문에 답변해줍니다.

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

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

“클라이언트-서버 타입 추론” 강의는 얼마나 걸리나요?

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

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

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

이 강의의 모든 강의

← TypeScript Academy(으)로 돌아가기