🧠 01. 타입스크립트 멘탈 모델: JS와 TS의 아슬아슬한 규칙

📌 이 문서를 읽기 전에

⏱️ 예상 읽기 시간: 10분(전체) / 핵심 파트만: 5분

🗺️ 이 문서의 흐름
[런타임과 빌드타임의 이해] → [구조적 타이핑(Duck Typing)의 비밀] → [타입스크립트의 배신(any)]

🎯 이 문서를 다 읽으면 할 수 있는 것

• 브라우저에서 실행되는 코드와 TS 컴파일러가 검사하는 코드의 차이를 설명할 수 있다.
• 구조적 타이핑이 왜 실무에서 유용한지 (그리고 왜 가끔 위험한지) 이해한다.
• 영수네 커뮤니티 코드에서 흔히 발생하는 타입 구멍을 어떻게 막는지 체득한다.

🗺️ 이 문서의 배경 세계관: '영수네 커뮤니티'

• 🐣 영철 ( 신입 ): "리드 님! 방금 배포한 프로필 수정 기능에서 Cannot read properties of undefined (reading 'nickname') 에러 나는데요?! 컴파일할 때는 아무 에러 없었단 말이에요!"
• 🦁 영호 ( 리드 ): "영철 님, 타입스크립트는 거짓말을 하지 않아요. 다만 영철 님이 API 응답값을 타입스크립트에게 거짓말로 알려줬을 뿐이죠. 빌드타임과 런타임의 차이점, 오늘 확실하게 짚고 넘어갑시다."

🤔 왜 알아야 하는가: '에러'는 누구의 잘못인가?

영철이의 억울함은 당연합니다. VScode에는 빨간줄 하나 없었고, npm run build도 완벽히 통과했으니까요. 하지만 사용자의 브라우저에서는 속절없이 화면이 하얗게 랙이 걸립니다. 도대체 무엇이 문제였을까요?

이 현상을 이해하려면, 먼저 타입스크립트는 브라우저에서 실행되는 진짜 코드가 아니라는 사실을 뼈저리게 느껴야 합니다. 타입스크립트는 단지 컴파일러(검문소)일 뿐, 실제로 브라우저를 달리는 건 100% 순수한 자바스크립트입니다.

이 **멘탈 모델(Mental Model)**을 제대로 정착시키지 못하면, 5년 차가 되어도 any와 as를 남발하며 타입스크립트와 매일 싸우게 됩니다.

🏗️ 1. 빌드타임 vs 런타임 (평행세계의 이해)

가장 흔하게 착각하는 부분입니다. 타입 텍스트는 오로지 개발 환경(빌드 타임) 에만 존재합니다.

🐣 영철이의 오해 코드

// 🐣 영철: "유저 정보는 무조건 User 타입이니까 안전하겠지!"
type User = {
  id: number;
  nickname: string;
};
 
// 백엔드(영수)가 보내준 데이터를 변수에 할당
async function fetchUser() {
  const response = await fetch('/api/user/1');
  const data: User = await response.json(); // 💣 지옥의 시작
  
  return data;
}

🦁 영호의 팩폭

위 코드에서 const data: User는 데이터 런타임 검증이 아닙니다. 이 문장은 컴파일러에게 이렇게 속삭이는 것과 같습니다.
"야 TS! 내가 장담하는데 저 API 응답은 무조건 User 모양이야. 묻지도 따지지도 말고 통과시켜."

실제 자바스크립트로 변환된 코드는 충격적일 만큼 허무합니다.

// 트랜스파일 후의 순수 JS 코드
async function fetchUser() {
  const response = await fetch('/api/user/1');
  const data = await response.json(); // 타입이 흔적도 없이 사라짐!
  
  return data;
}

만약 백엔드의 영수 님이 실수로 nickname 대신 name을 넘겨주면 어떻게 될까요?

• 빌드타임 (TS): 영철이가 User라고 장담했으니 통과.
• 런타임 (브라우저): data.nickname에 접근하는 순간 undefined 폭탄 터짐!

💡 TS의 한계: 타입스크립트는 네트워크 통신 결과, 로컬 스토리지 데이터, 사용자의 입력값 같은 '런타임'의 동적 데이터를 스스로 알 수 없습니다. 개발자가 정확히 가이드해주거나, Zod 같은 런타임 검증 라이브러리를 써야 합니다.

🦆 2. 구조적 타이핑 (Duck Typing): 넌 어떻게 생겼니?

C#이나 Java 출신의 개발자들이 TS를 처음 접할 때 가장 헷갈리는 부분입니다.
타입스크립트는 구조적 타이핑(Structural Typing) 을 채택하고 있습니다. 쉽게 말해 "오리처럼 생겼고, 오리처럼 꽥꽥거리면, 넌 오리다" 라는 논리입니다.

영수네 커뮤니티 권한 부여 예시

type BoardAdmin = {
  internalId: number;
  manageBoard: () => void;
};
 
type AppSuperUser = {
  internalId: number;
  manageBoard: () => void;
  deleteApp: () => void;
};
 
// 게시판 관리자를 허용하는 함수
function grantBoardAccess(admin: BoardAdmin) {
  admin.manageBoard();
}
 
// 🐣 영철의 질문
const superMan: AppSuperUser = {
  internalId: 100,
  manageBoard: () => console.log("게시판 권한 획득"),
  deleteApp: () => console.log("앱 폭파!"),
};
 
// "BoardAdmin 타입이 아닌데 이게 들어가요?"
grantBoardAccess(superMan); // ✅ 통과! (에러 없음)

grantBoardAccess 함수는 BoardAdmin을 요구합니다. 하지만 우리는 AppSuperUser를 넣었습니다.
다른 언어라면 상속(extends) 관계가 명시되지 않아 에러를 뿜었겠지만, 타입스크립트는 통과시킵니다.

왜일까요? superMan이 최소한 BoardAdmin이 요구하는 모든 스펙(internalId, manageBoard) 을 완벽하게 갖추고 있기 때문입니다. 떡고물이 더 묻어있을(deleteApp) 뿐입니다.

이 유연성 덕분에 TS는 자바스크립트의 동적이고 자유분방한 객체 할당 패턴을 무리 없이 품어낼 수 있습니다.

🚫 3. any와 as: 제어권을 포기하는 행위

아키텍처 관점에서, 타입스크립트의 가장 강력한 무기는 any도 아니고 Interface도 아닙니다. 바로 타입 추론(Type Inference) 입니다.

❌ 나쁜 예 (영철이의 타입 강제 삽입)

// 🐣 영철: "난 TS가 불안하니까 모든 변수에 타입을 달아줄 거야!"
const message: string = "안녕하세요!";
const isLoading: boolean = true;
const userIds: number[] = [1, 2, 3];
 
const result = "비밀 문서" as any; // 💣 급할 때 쓰는 만능열쇠

✅ 좋은 예 (영호의 우아한 추론)

// 🦁 영호: "TS는 생각보다 똑똑해요. 명백한 건 놔두고, 필요한 곳에만 힘을 주죠."
const message = "안녕하세요!"; // TS가 이미 string으로 암
const isLoading = true; // boolean으로 암
const userIds = [1, 2, 3]; // number[]로 암
 
// 명시적 타입은 인자, 반환값, 복잡한 객체 생성 시에 집중!
function createProfile(name: string, age: number): User {
  return { id: 1, nickname: name };
}

특히 as (Type Assertion)는 "TS야, 넌 틀렸어. 닥치고 내가 맞으니까 검사하지 마." 라는 오만한 선언입니다. 웬만하면 as 없이 타입이 유연하게 흘러가도록(Flow) 코드를 작게 쪼개는 것이 진짜 실력입니다.

📝 마무리 퀴즈

Q1. 외부 API에서 데이터를 가져올 때 const data: User = await res.json()으로 타이핑하는 것의 위험성은 무엇인가?

✅ 정답: 빌드타임 검사만 통과할 뿐, 실제 런타임 데이터 구조를 보장하지 못함.

💡 상세 해설:

• res.json()은 타입스크립트 관점에서 기본적으로 any를 반환합니다.
• 변수에 : User를 단다고 해서 객체 내용이 변경되는 것이 아닙니다. 런타임(브라우저)에서 실제로 nickname 프로퍼티가 없으면 나중에 접근 시 예외가 발생합니다.

Q2. 자바스크립트는 런타임 언어입니다. 타입스크립트는 런타임에 에러를 막아주는 방패 역할을 수행하나요?

✅ 정답: 아니요. 타입스크립트는 브라우저(런타임)에서 실행되지 않습니다.

💡 상세 해설:

• 타입스크립트의 검사는 개발 환경(빌드 타임, VSCode 편집 중)까지만 유효합니다.
• 실행되는 시점에는 모든 type과 interface 껍데기 코드가 증발하고 순수한 자바스크립트만 남습니다. 이 평행 세계를 이해하는 것이 멘탈 모델의 첫 단추입니다.

Q3. [영철이의 테스트 타임: 실무 딜레마] 영철이가 디자인 시스템 컴포넌트인 Button을 만들고 있습니다. 기존 HTML <button>의 모든 속성(onClick, disabled 등)을 다 받아오면서 커스텀 속성인 variant를 추가하고 싶어 합니다. "이거 Props를 일일이 다 적어줘야 하나요?"라고 고민할 때, 구조적 타이핑을 이해한 영호 리드는 어떤 해결책(개념)을 제시할까요?

✅ 정답: "오리처럼 생긴 건 다 받아와!" (extends를 통한 HTML attributes 확장)

💡 상세 해설:

• 원리 설명: 구조적 타이핑의 유연함을 활용하면, type ButtonProps = React.ButtonHTMLAttributes<HTMLButtonElement> & { variant?: 'primary' | 'secondary' } 형태로 손쉽게 HTML 기본 속성을 싹 다 흡수할 수 있습니다.
• 오답 피드백: "영철 님, onClick?: () => void부터 onMouseEnter까지 100개가 넘는 이벤트 속성을 수작업으로 적고 있는 건 아니죠?"
• 📌 핵심 기억법: 내가 필요한 스펙(variant)만 정의하고, 나머지는 검증된 덩어리(HTMLAttributes)와 합치면 그만이다.

🐣 영철이의 퇴근 일기

💡 "타입스크립트는 천사 같은 경비원이지만, 성문을 통과한 후의 사고는 책임져 주지 않는다."

오늘도 한바탕 난리였다. any와 as를 덕지덕지 발라서 VScode의 빨간 줄만 지우면 끝인 줄 알았던 나의 안일한 과거를 반성하게 된 하루. 마치 음주 측정도 안 하고 무조건 통과시켜 주는 경찰관을 좋은 사람이라고 착각한 것과 같달까?
내일부터는 API 응답값을 다룰 때 절대 나 스스로를 믿지 말아야겠다. 집에 가서 런타임 유효성 검사해 주는 Zod라는 라이브러리나 좀 찾아보고 자야지. 아, 영호 리드 님이 퇴근길에 던져주신 바나나 우유 달달하네!