🧠 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(); // 런타임 검증 없이 User라고 약속한 상태
 
  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) 코드를 작게 쪼개는 것이 진짜 실력입니다.

외부 데이터는 unknown으로 받아 작은 검증 경계를 통과시키면, 타입 선언과 런타임 사실이 어긋나는 지점을 줄일 수 있습니다.

type User = {
  id: number;
  nickname: string;
};
 
function isUser(value: unknown): value is User {
  if (typeof value !== "object" || value === null) return false;
 
  const user = value as Record<string, unknown>;
 
  return (
    typeof user.id === "number" &&
    typeof user.nickname === "string"
  );
}
 
async function fetchUserSafely() {
  const response = await fetch("/api/user/1");
  const data: unknown = await response.json();
 
  if (!isUser(data)) {
    throw new Error("프로필 API 응답 형식이 User와 다릅니다.");
  }
 
  return data;
}

이 코드는 "빨간 줄을 없애기"보다 "외부에서 들어온 값을 언제 신뢰할지"를 명시합니다. 영철이는 여기서부터 타입스크립트를 문법이 아니라 데이터 경계 설계 도구로 보기 시작합니다.

📝 마무리 퀴즈

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를 일일이 다 적어줘야 하나요?"라고 고민할 때, 구조적 타이핑을 이해한 영호 리드는 어떤 해결책(개념)을 제시할까요?

✅ 정답: 기존 버튼 속성 타입을 확장하거나 교차해서 재사용한다. 예: React.ButtonHTMLAttributes<HTMLButtonElement>에 variant를 더한다.

💡 상세 해설:

• 구조적 타이핑 덕분에 ButtonProps가 HTML 버튼이 요구하는 속성 구조를 포함하면, 별도의 상속 계층 없이도 안전하게 호환됩니다.
• type ButtonProps = React.ButtonHTMLAttributes<HTMLButtonElement> & { variant?: "primary" | "secondary" }처럼 작성하면 기존 이벤트, 접근성 속성, disabled 같은 표준 속성을 빠뜨릴 위험이 줄어듭니다.
• 핵심은 "타입을 전부 직접 쓰기"가 아니라, 이미 검증된 타입 덩어리에 우리 서비스의 의미 있는 속성만 얹는 것입니다.

🐣 영철이의 퇴근 일기

오늘은 빨간 줄이 없다는 사실과 런타임이 안전하다는 사실이 다르다는 걸 제대로 배웠다. const data: User = await res.json()은 검증이 아니라 내가 TS에게 보낸 약속이었다. 그 약속이 틀리면 피해는 사용자 브라우저에서 예외로 드러난다.

영호 님이 "타입은 실행되지 않는다"라고 짚어준 뒤로, any와 as를 쓰는 손이 조금 무거워졌다. 빨간 줄을 지우는 게 목표가 아니라, 데이터가 들어오는 경계에서 무엇을 믿고 무엇을 확인할지 정하는 게 목표였다.

💡 "타입스크립트는 런타임 데이터를 대신 검증하지 않는다. 외부에서 들어오는 값은 타입 선언이 아니라 검증 경계로 다뤄야 한다."

내일은 프로필 API 응답을 다시 보면서 unknown으로 받은 뒤 필요한 필드만 확인하는 작은 유틸부터 만들어볼 생각이다. 구조적 타이핑은 편하지만, 외부 데이터에는 신뢰의 출처를 남겨야 한다는 걸 코드 리뷰 체크리스트에 적어둬야겠다.