📦 04. 제네릭(Generics): 영수네 만능 API 응답 래퍼 만들기

📌 이 문서를 읽기 전에

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

🗺️ 이 문서의 흐름
[반복되는 타입 복붙의 늪] → [제네릭: 타입의 매개변수화] → [아무거나 들어오는 건 싫어: extends 제약]

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

• <T> 가 함수 파라미터와 정확히 똑같은 개념임을 설명할 수 있다.
• 반복되는 API 응답 구조를 하나의 제네릭 인터페이스로 우아하게 통일할 수 있다.
• extends 키워드를 사용해 제네릭이 가질 수 있는 타입의 범위를 안전하게 제한할 수 있다.

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

• 🐣 영철 ( 신입 ): "(타닥타닥... 앗 복사 붙여넣기 삑살났다) 하아... API 엔드포인트가 늘어날 때마다 ApiResponse_User, ApiResponse_Board, ApiResponse_Comment 다 따로 만들고 있는데, statusCode랑 message 필드는 맨날 똑같이 들어가네요. 손가락 아파 죽겠습니다."
• 🦁 영호 ( 리드 ): "영철 님, 혹시 함수 만들 때 중복되는 값이 있으면 매번 함수를 100개 만드나요? 매개변수(Parameter)로 빼버리잖아요. 타입도 똑같아요. 변하는 부분만 파라미터로 넘겨받는 마법, 그게 바로 제네릭(Generics)입니다."

🤔 왜 알아야 하는가: '복붙'은 죄악이다

현대적인 프론트엔드 환경에서 외부와 데이터를 주고받을 때, 백엔드 구성원들은 대체로 공통된 봉투(Wrapper) 안에 데이터를 담아서 줍니다.

이를테면, 영수네 백엔드는 항상 이런 포맷을 고집합니다.

{
  "statusCode": 200,
  "message": "성공!",
  "data": { ...여기에 진짜 데이터... }
}

만약 제네릭을 모른다면, 영철이의 코드는 끔찍하게 비대해질 수밖에 없습니다.

💣 영철이의 과거 (노가다 타입 선언)

// 유저를 가져올 때
interface UserResponse {
  statusCode: number;
  message: string;
  data: { id: number; name: string };
}
 
// 게시글을 가져올 때
interface BoardResponse {
  statusCode: number; // 중복!
  message: string;    // 중복!
  data: { id: number; title: string; content: string }[];
}

이 코드는 실무에서 100개의 API를 붙이면 100번 똑같은 statusCode와 message를 써야 합니다. 그러다 백엔드가 message를 msg로 바꾸면? 야근 확정입니다.

🎩 1. 제네릭의 본질: 타입도 변수다

이 문제를 해결하기 위해 함수의 패러다임을 타입의 세계로 훔쳐 옵니다.

function hello(name) 이라는 함수가 있을 때, 괄호 안의 name 자리에 "영철"을 넣을지 "영호"를 넣을지는 나중에 함수를 호출할 때 결정됩니다.
제네릭도 완전히 똑같습니다. 꺾쇠(< >) 안에 쓸 알파벳(주로 T, U, A 등을 씁니다)은 나중에 결정될 데이터의 모양을 담아둘 "변수 바구니"일 뿐입니다.

🦁 영호의 우아한 만능 래퍼 (Generic Wrapper)

// 영호: "자, 바뀌지 않는 봉투(statusCode, message)는 놔두고,
// 안에 바뀔 알맹이(data) 자리만 <T> 라는 변수로 뚫어두는 겁니다."
 
interface ApiResponse<T> {
  statusCode: number;
  message: string;
  data: T; // 여기에 나중에 넘겨준 타입이 그대로 박힘!
}

이제 영철이는 API 응답을 다음과 같이 한 방에 정리할 수 있습니다.

type User = { id: number; name: string };
type Board = { id: number; title: string; content: string };
 
// 사용할 때, < > 안에 원하는 알맹이를 던져준다!
const userRes: ApiResponse<User> = await fetchUser();
const boardsRes: ApiResponse<Board[]> = await fetchBoards(); // 배열도 통째로 넣을 수 있음!

💡 왜 하필 대문자 T인가요?
Type의 약자입니다. 일반 변수를 a, b, c로 짓듯 제네릭에서는 T, U, V를 관습적으로 씁니다. 하지만 권장하지는 않습니다. 5년 차 개발자라면 그냥 T 말고 의미 있는 이름(<TData>, <TResponse>)을 쓰는 것이 코드 가독성에 훨씬 좋습니다.

🚫 2. 제네릭 제약 (Generic Constraints): 아무거나 넣지 마!

하지만 제네릭이 무조건 뚫려있는 빈 종이여서는 안 될 때가 있습니다.

영철이가 유저의 길이를 출력하는 유틸 함수를 만들었다고 합시다.

// 🐣 영철: "T는 만능이니까 배열이든 문자열이든 다 받아내겠지!"
function logLength<T>(items: T): void {
  // 💣 에러! T가 뭔지 모르는데 length 속성이 있을 줄 어떻게 알아?
  console.log(items.length); 
}

이때 영호 리드가 등판합니다. "영철 님, TS한테 최소한 이 T가 length를 가지고 있다는 건 알려줘야지 아무거나 다 받아주면 어떡합니까?"

extends 로 타입의 성질 제한하기

여기서의 extends는 클래스의 상속이라기보다 "최소한 이 조건은 만족해야 해!" 라는 검문소 역할을 합니다.

// "T라는 변수를 받을 건데, 걔는 무조건 length 속성(number)을 가진 녀석이어야 해!"
interface HasLength {
  length: number;
}
 
function safeLogLength<T extends HasLength>(items: T): void {
  // 이제 TS는 T가 무조건 length를 가졌다고 확신함. 에러 사라짐!
  console.log(items.length); 
}
 
// 사용 예시
safeLogLength([1, 2, 3]); // ✅ 배열은 length가 있음
safeLogLength("안녕하세요"); // ✅ 문자열도 length가 있음
safeLogLength({ length: 10, name: "룰루" }); // ✅ 객체 안에 length 속성을 넣었으니 통과!
 
// safeLogLength(123); // ❌ 삐빅! 숫자는 length가 없습니다!

이처럼 extends를 사용하면, 제네릭의 무한한 자유도를 안전한 테두리 안으로 좁힐 수 있습니다.

📝 마무리 퀴즈

Q1. interface ApiResponse<T> 에서 꺾쇠(<T>) 안에 들어가는 T의 의미를 함수의 파라미터와 비교하여 설명해 보세요.

✅ 정답: T는 함수 선언부의 매개변수(Parameter)와 완벽히 똑같은 역할을 합니다.

💡 상세 해설:

• function print(text)에서 text가 런타임의 실제 '값'을 나중에 받아오기 위한 빈번수 이듯이,
• <T>는 컴파일 타임에 사용할 실제 '타입'의 껍데기를 나중에 받아오기 위해 미리 자리를 비워두는 타입 레벨의 매개변수일 뿐입니다.

Q2. 제네릭 함수를 선언할 때, 인자로 넘어오는 제네릭 T가 반드시 특정 프로퍼티(예: id)를 포함하도록 강제하고 싶을 때 사용하는 키워드는 무엇인가요?

✅ 정답: extends 키워드입니다. (예: <T extends { id: number }>)

💡 상세 해설:

• 제네릭 제약 조건(Constraints)이라고 부릅니다.
• 아무 제약이 없는 T는 TS 입장에서 unknown과 다를 바 없어 내부 프로퍼티를 마음대로 사용할 수 없습니다. extends를 통해 최소한의 구조적 요구사항을 TS에게 전달해야 합니다.

Q3. [영철이의 테스트 타임: 라이브러리 트레이드오프] 팀 회의 시간입니다. 영수(PM/백엔드)가 "요즘 API 클라이언트로 Axios 말고 내장 fetch를 쓰자"고 제안했습니다. 그러자 영철이가 반발합니다. "Axios는 axios.get<User>('/api') 처럼 제네릭을 바로 지원해서 편한데, 순수 fetch는 제가 매번 (await res.json()) as User로 캐스팅해줘야 하잖아요! 너무 불편합니다." 영호 리드는 이 상황을 5분 만에 어떤 커스텀 유틸 함수로 해결해 줄 수 있을까요?

✅ 정답: fetch를 감싸고 제네릭 <T>를 받아 응답값을 Promise<T>로 반환하는 래퍼(Wrapper) 함수를 만들어 준다.

💡 상세 해설:

• 원리 설명: 제네릭은 내장 라이브러리의 불편함을 우아하게 덮는 훌륭한 도구입니다. 아래와 같은 커스텀 fetch 래퍼를 단 한 번만 선언해두면, 온 프로젝트에서 Axios 부럽지 않게 타입을 주입할 수 있습니다.

  async function myFetch<T>(url: string): Promise<T> {
    const response = await fetch(url);
    if (!response.ok) throw new Error('API 💣');
    return response.json(); // 암묵적으로 any가 반환되지만, 반환 타입이 Promise<T>이므로 알아서 캐스팅됨
  }
   
  // 영철이의 사용처: 
  // const user = await myFetch<User>('/api/user');

• 오답 피드백: "영철 님, 라이브러리가 편하다고 의존성에 목매달지 마세요. TypeScript의 제네릭 원리만 알면 우리가 라이브러리처럼 만들어서 쓰면 됩니다. 아, 물론 저기서 json()이 any를 뱉는 건 런타임 불안요소지만, Axios도 결국 똑같은 짓을 하고 있으니 일단 넘어갑시다."
• 📌 핵심 기억법: 껍데기는 내가 만들 테니, 최종 결과물(타입)은 호출하는 쪽(너)이 던져줘!

🐣 영철이의 퇴근 일기

💡 "제네릭은 코드계의 붕어빵 빵틀이다. 반죽이 팥이든 슈크림이든, 봉투(Wrapper)는 우아하게 형태를 유지해 낸다."

내가 며칠 동안 interface 복붙 노가다를 뛰며 삽질한 걸, 영호 리드 님은 단 두 줄의 코드로 우아하게 끝내버렸다. <T> 한 글자의 위력이 이렇게 무서울 줄이야.
그동안 남들이 만든 라이브러리 (React의 useState<number>()나 axios<Res>()) 쓸 땐 아무 생각 없이 꺾쇠 안에 타입을 던져 넣었는데, 그게 다 제네릭이란 녀석이었구나.
내일 출근하면 그동안 복붙해 놨던 ApiResponse_OOO 인터페이스 40개 싹 다 지우고 ApiResponse<T> 로 통일하는 PR 올려야겠다. 리드 님이 "오~ 영철 님 드디어 감 잡았네요" 하고 칭찬해주면 좋겠다 ㅋㅋㅋ 퇴근 쓰리, 투, 원! 달려!