한 개발자가 내부 도구의 REST API를 tRPC로 교체하는 데 2주를 보냈습니다.

전환이 중요했던 이유

기존 스택에서는 DTO, 검증기(validator), 그리고 프론트엔드용 별도의 TypeScript 타입을 모두 유지 관리해야 했습니다. 백엔드 필드 이름을 변경하면 API는 여전히 200을 반환하고 UI는 계속 렌더링되었으며, 버그는 단지 "undefined" 값으로만 나타났습니다. 팀원 중 누구보다 고객이 먼저 이 문제를 발견했습니다. REST 계약(contract)은 문제를 숨겼고, 추가된 파일들은 결코 이득이 되지 않는 유지 관리 비용만 늘렸습니다.

기존 REST 설정의 모습

  • OpenAPI 스펙 – 엔드포인트를 설명하는 정적 파일이었지만, 결코 신뢰할 수 있는 단일 원천(source of truth) 역할을 하지 못했습니다.
  • 클라이언트 SDK 생성 단계 – JavaScript 래퍼를 생성하는 CI 작업입니다.
  • Postman 컬렉션 – 아무도 사용하지 않는 공유 테스트 산출물입니다.
  • 수동 TypeScript 인터페이스 – 서버와 동기화 상태를 유지해야 하는 수동 작성 타입입니다.

API를 변경할 때마다 검증기와 하위 fetch 호출을 포함하여 최소 세 개 이상의 산출물을 수정해야 했습니다. 이 과정은 오류가 발생하기 쉬웠고 느렸습니다.

tRPC가 코드베이스를 줄인 방법

tRPC는 별도의 계약 파일을 없애줍니다. 서버는 router type을 내보내고(export), 클라이언트는 동일한 타입을 가져옵니다(import). 백엔드 필드 이름을 변경하면 코드를 실행하거나 요청이 실패할 필요 없이 에디터가 즉시 불일치를 표시합니다. 개발자는 다음 항목들을 제거했습니다:

  • OpenAPI 스펙 파일.
  • 클라이언트 SDK 생성 단계.
  • 사용하지 않는 Postman 컬렉션.
  • 수동 TypeScript 인터페이스 폴더.

저장소는 더 가벼워졌고, 피드백은 배포 후가 아닌 개발 중에 전달되었습니다.

tRPC의 한계

tRPC는 양쪽 끝(end)이 모두 TypeScript를 사용할 때만 작동합니다. 다음과 같은 경우에는 적합하지 않습니다:

  • 모바일 팀이 Swift나 Kotlin을 사용하는 경우.
  • 외부 파트너가 API를 사용해야 하는 경우.
  • 언어에 구애받지 않는(language-agnostic) 공개 인터페이스가 필요한 경우.

실제 마이그레이션에 필요했던 작업

2주간의 노력은 단순히 복사해서 붙여넣는 수준이 아니었습니다. 개발자는 다음 작업을 수행해야 했습니다:

  • 모든 fetch 호출을 tRPC 클라이언트 함수를 사용하도록 재작성.
  • 에러 처리 로직 조정.
  • 원시 HTTP 응답에 연결된 로딩 및 재시도 상태에 의존하는 UI 컴포넌트 업데이트.

도입 전 고려해야 할 질문들

  • 프론트엔드와 백엔드 모두 TypeScript를 사용하나요? 공유된 타입 시스템이 없다면 tRPC의 주요 장점은 사라집니다.
  • 양쪽 모두 동일한 팀이 담당하나요? 책임 소재가 불분명하면 계약 불일치(contract drift)가 다시 발생할 수 있습니다.
  • 구체적인 버그를 해결하려는 것인가요, 아니면 트렌드를 쫓는 것인가요? 생산성 향상은 실질적이지만, 반드시 기존의 고충(pain point)을 해결할 수 있어야 합니다.

2025년을 위한 하이브리드 접근 방식

많은 팀이 두 스택을 병행함으로써 최적의 균형점을 찾습니다:

  • 내부 애플리케이션 계층에는 tRPC 사용: 코드베이스가 전적으로 TypeScript이고 동일한 팀이 서버와 클라이언트를 모두 관리하는 경우.
  • 웹훅, 공개 API 및 파트너 연동에는 REST 사용: 언어에 구애받지 않는 접근이 필요한 경우.

각 접점(surface)에 적합한 도구를 사용하면 외부 사용자를 위한 개방성을 유지하면서도 내부 개발 속도를 빠르게 유지할 수 있습니다.

요약: REST를 tRPC로 교체하면 중복된 계약 산출물을 제거하고 편집 시점에 버그를 발견할 수 있지만, 이러한 이점은 전체 스택이 TypeScript를 공유하고 팀이 마이그레이션 비용을 감당할 수 있을 때만 실현됩니다. 혼합 전략을 사용하면 TypeScript를 사용하지 않는 소비자들을 배제하지 않으면서도 그 혜택을 누릴 수 있습니다.