📦 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');

• 다만 이 래퍼도 런타임 검증을 자동으로 해주지는 않습니다. 1장에서 본 것처럼 response.json()의 실제 모양은 네트워크 경계에서 별도로 확인해야 합니다.
• 핵심은 공통 봉투와 호출부별 데이터 타입을 분리하는 것입니다. 봉투는 래퍼가 책임지고, 최종 데이터 타입은 호출하는 쪽에서 <User>처럼 명확히 넘깁니다.

🐣 영철이의 퇴근 일기

오늘은 제네릭이 "어려운 문법"이라기보다 타입 세계의 매개변수라는 게 선명해졌다. ApiResponse<T> 하나로 공통 응답 봉투를 고정하고, 안쪽 data만 호출부마다 바꾸면 복붙 타입이 사라진다.

extends 제약도 마음에 남았다. 아무 타입이나 받는 자유보다, 최소한의 조건을 걸어두는 자유가 더 실무적이었다. length가 필요하면 T extends { length: number }처럼 컴파일러가 이해할 근거를 줘야 한다.

💡 "제네릭은 중복 타입을 지우는 도구이지만, 제약 없는 제네릭은 책임 없는 빈칸이 된다. 변하는 부분과 반드시 필요한 조건을 함께 표현해야 한다."

내일은 ApiResponse_User처럼 이름만 다른 인터페이스를 ApiResponse<TData>로 정리하는 PR을 작게 올릴 생각이다. 한 번에 전부 바꾸기보다 호출부 타입 추론이 깨지는 곳을 확인하면서 천천히 묶어야겠다.