같은 주문 상태를 두고 화면은 paid, API는 success, 운영 문서는 완료라고 부르던 팀이 있었다. 기능은 돌아갔지만 협업 비용이 컸다.
이 팀은 TypeScript 타입 선언을 단순한 보조 문서가 아니라 제품 계약서처럼 다뤘다. 이름을 맞추자 오류보다 대화 시간이 먼저 줄었다.
타입 리뷰가 설계 리뷰가 된 순간
BFF 응답 형태를 화면이 원하는 모양으로 바꾸는 과정에서, 누가 어떤 필드를 책임지는지 드러났다.
TypeScript는 여기서 큰 역할을 했다. 런타임 오류를 줄인 것도 중요하지만, 무엇보다 팀의 용어를 통일하는 도구가 됐다.
팀이 정한 기준
도메인 타입 우선
장점 제품 언어와 코드가 같이 움직인다.
주의점 초기 설계 시간이 조금 더 든다.
화면별 임시 타입
장점 빠르게 붙일 수 있다.
주의점 팀이 커질수록 상태 이름이 갈라진다.
실무에서 남긴 원칙
- 상태 이름은 제품 문서와 타입 선언에서 동일하게 쓴다.
- BFF는 화면 편의보다 도메인 용어 정합성을 먼저 챙긴다.
- 복잡한 유니온 타입은 화면 요구가 아니라 규칙 혼선을 드러내는 신호로 본다.
리뷰 뒤에 남은 것
- TypeScript는 오류 방지 도구이면서 동시에 제품 용어 정리 도구다.
- 프런트와 API 계약이 자주 흔들리는 팀일수록 타입 리뷰가 효과적이다.
- 팀 확장기에는 도메인 타입을 먼저 세우는 편이 결과적으로 더 빠르다.