tRPC vs REST: 타입 안전한 API 계층 선택

타입스크립트로 프론트와 백엔드를 함께 만든다면, API 응답 타입이 백엔드 변경과 어긋나 런타임에서 터지는 문제를 겪어 봤을 것이다. tRPC는 이 문제를 코드 생성 없이 타입으로 해결하지만, 모든 상황에 맞는 만능은 아니다. 외부에 API를 공개해야 하거나 여러 언어의 클라이언트가 붙는다면 이야기가 달라진다. 이 글은 두 접근이 각각 무엇을 강제하고 무엇을 포기하는지 비교해 선택 기준을 정리한다.

API 계약을 타입으로 강제한다는 것

API 계약은 "어떤 입력을 보내면 어떤 출력이 오는가"에 대한 약속이다. REST에서는 이 약속을 문서나 스키마로 관리하고, 클라이언트는 그에 맞춰 타입을 만든다. tRPC 공식 Concepts 문서에 따르면 appRouter와 publicProcedure로 정의한 서버 라우터 타입(AppRouter)이 그대로 클라이언트에 전달되어, 별도 스키마 정의나 코드 생성 없이 호출부에서 타입 검사가 이뤄진다. 계약이 어긋나면 배포 전에 컴파일 단계에서 드러난다.

tRPC가 잘 맞는 조건

tRPC의 전제는 "서버와 클라이언트가 같은 타입스크립트 코드베이스의 타입을 공유한다"는 것이다. 이 전제가 성립할 때 개발 속도가 크게 오른다.

• 모노레포나 타입을 공유하는 구성에서 프론트와 백엔드를 한 팀이 함께 개발한다.
• 소비자가 자사 프론트엔드뿐이고, 외부 공개 API가 아니다.
• 스키마 정의와 코드 생성 단계를 줄이고 싶다.
• React Query 같은 데이터 패칭 계층과 자연스럽게 연동하고 싶다.

모노레포·동일 팀·내부 소비자

tRPC는 라우터를 정의하면 클라이언트가 그 타입을 추론한다. 엔드포인트를 추가할 때 별도 스키마 파일을 갱신하지 않아도 되고, 리팩터링 시 호출부가 함께 깨져 누락을 막는다. 대신 서버와 클라이언트가 같은 런타임·버전에 묶이므로, 배포가 분리된 환경에서는 타입 불일치를 다루는 추가 설계가 필요하다.

REST/OpenAPI가 유리한 조건

REST는 HTTP 메서드와 경로, 상태 코드라는 보편 규칙 위에 서 있다. OpenAPI로 스키마를 정의하면 다양한 언어의 클라이언트를 생성할 수 있고, 문서·목 서버·검증 도구가 생태계로 연결된다. 다음 조건에서는 REST가 낫다.

• 외부 개발자나 제휴사에 API를 공개해야 한다.
• 여러 언어·플랫폼 클라이언트가 있다.
• HTTP 캐시, CDN, 게이트웨이 정책을 그대로 활용해야 한다.
• 계약을 버전 단위로 관리하고 하위 호환을 보장해야 한다.

캐싱·버전 관리·외부 공개 비교

두 접근의 차이는 운영 단계에서 더 분명해진다.

특히 캐싱은 실무 차이가 크다. REST는 GET 응답에 캐시 헤더를 붙여 CDN·프록시에서 재사용할 수 있지만, RPC 스타일 호출은 이런 의미를 갖지 않아 캐시 계층을 별도로 설계해야 한다.

혼합 전략과 경계 설정

둘 중 하나를 전체에 강제할 필요는 없다. 사내 대시보드·관리 도구처럼 소비자가 명확한 영역은 tRPC로 빠르게 만들고, 외부 공개 API나 서드파티가 붙는 경계는 REST/OpenAPI로 두는 혼합이 현실적이다. 경계는 "소비자가 누구인가"로 정한다. 같은 데이터라도 외부에 나가는 순간 계약은 문서화·버전 관리 대상이 된다.

// 내부: tRPC 라우터 (타입 공유)
export const appRouter = router({
  listOrders: publicProcedure.query(() => db.orders.findMany())
});

// 외부: OpenAPI 스키마로 공개
// GET /v1/orders  -> 스키마·버전 관리 대상

혼합 시 주의할 점은 내부 편의를 위해 만든 RPC 엔드포인트가 습관적으로 외부에 노출되는 것이다. 공개 경계를 명시적으로 관리하지 않으면 tRPC 라우터 전체가 의도치 않게 외부에 열릴 수 있다.

타입 안전을 유지하는 현실적인 절차

REST를 선택하더라도 타입 안전을 포기할 필요는 없다. openapi-typescript로 OpenAPI 스키마에서 클라이언트 타입을 생성하고, 서버 응답이 스키마와 일치하는지 검증하는 단계를 CI에 넣는다. 스펙 기반 타입 생성 절차는 OpenAPI 스펙으로 타입을 생성하고 API 계약 지키기에서 단계별로 확인할 수 있다. 이렇게 하면 스키마가 단일 출처이자 검증 기준이 된다. 반대로 tRPC를 선택하면 외부 소비자가 생기는 시점을 미리 표시해 두고, 그때 REST 경계를 추가하는 계획을 세운다. 두 방식 모두 "계약이 어디에 정의되어 있는가"를 한곳으로 모으는 것이 핵심이다. 계약이 코드·문서·타입 세 곳에 흩어지면 어느 것이 최신인지 알 수 없게 된다. 데이터 패칭과 서버 상태를 다루는 방식은 App Router 데이터 흐름 글과 함께 보면 계약과 캐시 경계를 정리하기 좋다.

선택 후 되돌리기 비용

tRPC는 소비자가 늘어날 때 확장 비용이 커진다. 반대로 REST는 초기 스키마·코드 생성 설정 비용이 들지만 소비자가 늘어도 부담이 완만하다. 되돌리기 관점에서는 "지금의 소비자가 앞으로도 하나일 것인가"를 기준으로 판단한다. 내부 전용이 확실하면 tRPC, 외부 확장 가능성이 있으면 REST를 기본으로 두는 편이 안전하다. API 계층은 데이터 패칭·캐시 전략과 맞물리므로, 프론트 상태 관리 결정과 함께 검토하는 것이 좋다.