TypeScript 제네릭 | Generics 완벽 가이드

들어가며

제네릭이란?

제네릭(Generics)은 타입을 매개변수처럼 넘겨 같은 뼈대로 여러 종류의 값을 안전하게 다루는 기능입니다. 비유(틀): 과자를 찍는 틀은 하나인데, 반죽만 바꿔 초콜릿·쿠키를 모두 찍을 수 있습니다. 제네릭은 함수·클래스에 형태만 맞는 틀을 끼우고, 구체적인 타입은 호출하는 쪽에서 넣는 방식입니다.

JavaScript에서 TypeScript로의 전환

“런타임 에러는 프로덕션에서 터진다”는 말이 있습니다. JavaScript로 개발하던 시절, 이 말을 뼈저리게 체감했습니다. 테스트는 다 통과했는데 배포 후 사용자가 이상한 데이터를 입력하면 앱이 터지는 거죠. 특히 팀 프로젝트에서 다른 사람이 작성한 함수의 반환 타입을 잘못 이해해서 버그가 발생하는 일이 잦았습니다. TypeScript를 도입한 후 가장 먼저 느낀 건 안심이었습니다. IDE가 자동완성을 정확히 해주고, 타입이 맞지 않으면 빨간 줄로 미리 알려줍니다. 리팩토링할 때도 “이 함수를 바꾸면 어디가 깨질까?” 걱정할 필요가 없어졌죠. 물론 처음엔 타입 정의 작성이 번거로웠지만, 몇 달 후 그 타입 정의 덕분에 버그를 미리 잡는 경험을 하고 나니 돌아갈 수 없었습니다.

1. 제네릭 기본

문제 상황

다양한 타입을 받아야 하는 함수를 만들 때 any를 사용하면 타입 안정성을 잃습니다:

// any 사용 (타입 안정성 상실)
function identity(value: any): any {
    return value;
}
const result1 = identity("hello");  // any 타입
const result2 = identity(123);      // any 타입
// 문제점:
// 1. 반환 타입이 any라서 타입 체크가 안 됨
// 2. result1.toFixed()를 호출해도 컴파일 에러가 안 남 (런타임 에러 발생)
// 3. 입력 타입과 출력 타입의 관계를 표현할 수 없음

제네릭 해결

제네릭을 사용하면 타입 안정성을 유지하면서 재사용 가능한 코드를 작성할 수 있습니다:

// 제네릭 사용
// <T>: 타입 매개변수 선언 (T는 관례적 이름, Type의 약자)
// value: T: 매개변수 타입이 T
// : T: 반환 타입이 T (입력과 같은 타입)
function identity<T>(value: T): T {
    return value;
}
// 명시적 타입 지정
const result1 = identity<string>("hello");  // string 타입
const result2 = identity<number>(123);      // number 타입
// 타입 추론 (권장)
// TypeScript가 전달된 값을 보고 T를 자동으로 추론
const result3 = identity("hello");  // T = string으로 추론
const result4 = identity(123);      // T = number로 추론
// 이제 타입 안정성 확보
// result3.toUpperCase();  // ✅ OK - string 메서드
// result3.toFixed();      // ❌ 컴파일 에러 - string에는 toFixed 없음
// result4.toFixed(2);     // ✅ OK - number 메서드

제네릭의 장점:

1. 타입 안정성: 컴파일 타임에 타입 체크
2. 재사용성: 하나의 함수로 모든 타입 처리
3. 가독성: 타입 관계를 명확히 표현
4. 자동 완성: IDE가 정확한 메서드 제안 제네릭 vs any: | 특성 | 제네릭 (<T>) | any | |-----|--------------|-----| | 타입 안정성 | ✅ 유지 | ❌ 상실 | | 타입 추론 | ✅ 가능 | ❌ 불가 | | 자동 완성 | ✅ 정확 | ❌ 없음 | | 런타임 에러 | ✅ 방지 | ❌ 발생 가능 |

---

2. 함수 제네릭

기본 사용

function getFirstElement<T>(arr: T[]): T | undefined {
    return arr[0];
}
const numbers = [1, 2, 3];
const first = getFirstElement(numbers);  // number | undefined
const strings = ["a", "b", "c"];
const firstStr = getFirstElement(strings);  // string | undefined

여러 타입 매개변수

function pair<T, U>(first: T, second: U): [T, U] {
    return [first, second];
}
const result1 = pair("hello", 123);     // [string, number]
const result2 = pair(true, "world");    // [boolean, string]

화살표 함수

const map = <T, U>(arr: T[], fn: (item: T) => U): U[] => {
    return arr.map(fn);
};
const numbers = [1, 2, 3];
const doubled = map(numbers, (n) => n * 2);        // number[]
const strings = map(numbers, (n) => n.toString()); // string[]

---

3. 인터페이스 제네릭

기본 사용

interface Box<T> {
    value: T;
}
const numberBox: Box<number> = { value: 123 };
const stringBox: Box<string> = { value: "hello" };
// 중첩 제네릭
const boxOfBoxes: Box<Box<number>> = {
    value: { value: 123 }
};

실전 예제: API 응답

interface ApiResponse<T> {
    success: boolean;
    data: T;
    error?: string;
}
interface User {
    id: string;
    name: string;
    email: string;
}
interface Product {
    id: string;
    name: string;
    price: number;
}
const userResponse: ApiResponse<User> = {
    success: true,
    data: {
        id: "U001",
        name: "홍길동",
        email: "[email protected]"
    }
};
const productResponse: ApiResponse<Product[]> = {
    success: true,
    data: [
        { id: "P001", name: "노트북", price: 1000000 },
        { id: "P002", name: "마우스", price: 30000 }
    ]
};

---

4. 클래스 제네릭

기본 사용

제네릭 클래스를 사용하면 다양한 타입에서 동작하는 자료구조를 만들 수 있습니다:

// Stack<T>: T 타입의 요소를 저장하는 스택 클래스
class Stack<T> {
    // private items: 외부에서 직접 접근 불가
    // T[]: T 타입의 배열
    private items: T[] = [];
    
    // push: 스택에 요소 추가 (LIFO - Last In First Out)
    push(item: T): void {
        // item의 타입은 T로 제한됨
        // numberStack이면 number만, stringStack이면 string만 추가 가능
        this.items.push(item);
    }
    
    // pop: 스택에서 마지막 요소 제거 및 반환
    // 반환 타입: T | undefined (스택이 비어있으면 undefined)
    pop(): T | undefined {
        return this.items.pop();
    }
    
    // peek: 마지막 요소 확인 (제거하지 않음)
    peek(): T | undefined {
        return this.items[this.items.length - 1];
    }
    
    // isEmpty: 스택이 비어있는지 확인
    isEmpty(): boolean {
        return this.items.length === 0;
    }
    
    // size: 스택의 크기 반환
    size(): number {
        return this.items.length;
    }
}
// 사용: number 타입 스택
const numberStack = new Stack<number>();
numberStack.push(1);
numberStack.push(2);
numberStack.push(3);
console.log(numberStack.pop());   // 3 (마지막에 추가된 것)
console.log(numberStack.peek());  // 2 (제거하지 않고 확인)
// numberStack.push("hello");     // ❌ 컴파일 에러: string은 number가 아님
// 사용: string 타입 스택
const stringStack = new Stack<string>();
stringStack.push("hello");
stringStack.push("world");
console.log(stringStack.pop());  // world
// stringStack.push(123);        // ❌ 컴파일 에러: number는 string이 아님

제네릭 클래스의 장점:

• 하나의 클래스로 모든 타입 지원
• 타입별로 별도 클래스를 만들 필요 없음
• 타입 안정성 유지 (잘못된 타입 추가 방지)
• 코드 재사용성 극대화 실제 사용 예시:

// 같은 Stack 클래스로 다양한 타입 처리
const taskStack = new Stack<Task>();        // Task 객체 스택
const undoStack = new Stack<Action>();      // Action 객체 스택
const historyStack = new Stack<string>();   // 문자열 스택

---

5. 제네릭 제약 조건

extends

// 특정 프로퍼티를 가진 타입만 허용
interface Lengthwise {
    length: number;
}
function logLength<T extends Lengthwise>(value: T): void {
    console.log(value.length);
}
logLength("hello");        // ✅ 5
logLength([1, 2, 3]);      // ✅ 3
// logLength(123);         // ❌ 에러: number에는 length 없음

keyof

function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {
    return obj[key];
}
const user = {
    name: "홍길동",
    age: 25,
    email: "[email protected]"
};
const name = getProperty(user, "name");    // string
const age = getProperty(user, "age");      // number
// const invalid = getProperty(user, "invalid");  // ❌ 에러

---

6. 실전 예제

예제 1: 배열 유틸리티

function chunk<T>(arr: T[], size: number): T[][] {
    const result: T[][] = [];
    for (let i = 0; i < arr.length; i += size) {
        result.push(arr.slice(i, i + size));
    }
    return result;
}
const numbers = [1, 2, 3, 4, 5, 6];
console.log(chunk(numbers, 2));  // [[1, 2], [3, 4], [5, 6]]
const strings = ["a", "b", "c", "d"];
console.log(chunk(strings, 3));  // [["a", "b", "c"], [d]]

예제 2: 캐시 시스템

class Cache<K, V> {
    private store = new Map<K, V>();
    
    set(key: K, value: V): void {
        this.store.set(key, value);
    }
    
    get(key: K): V | undefined {
        return this.store.get(key);
    }
    
    has(key: K): boolean {
        return this.store.has(key);
    }
    
    delete(key: K): boolean {
        return this.store.delete(key);
    }
    
    clear(): void {
        this.store.clear();
    }
}
// 사용
const userCache = new Cache<string, User>();
userCache.set("U001", { id: "U001", name: "홍길동", email: "[email protected]" });
const user = userCache.get("U001");
console.log(user?.name);  // 홍길동

예제 3: Promise 래퍼

class AsyncResult<T> {
    constructor(private promise: Promise<T>) {}
    
    async map<U>(fn: (value: T) => U): Promise<AsyncResult<U>> {
        const value = await this.promise;
        return new AsyncResult(Promise.resolve(fn(value)));
    }
    
    async flatMap<U>(fn: (value: T) => Promise<U>): Promise<AsyncResult<U>> {
        const value = await this.promise;
        return new AsyncResult(fn(value));
    }
    
    async unwrap(): Promise<T> {
        return await this.promise;
    }
}
// 사용
const result = new AsyncResult(Promise.resolve(10));
result
    .map((x) => x * 2)
    .then((r) => r.unwrap())
    .then((value) => console.log(value));  // 20

---

7. 고급 패턴

조건부 타입

type IsString<T> = T extends string ? true : false;
type A = IsString<string>;   // true
type B = IsString<number>;   // false

매핑 타입

type Readonly<T> = {
    readonly [K in keyof T]: T[K];
};
interface User {
    name: string;
    age: number;
}
type ReadonlyUser = Readonly<User>;
// { readonly name: string; readonly age: number; }

---

8. 자주 하는 실수

실수 1: 제네릭 제약 없이 프로퍼티 접근

// ❌ 잘못된 사용
function getLength<T>(value: T): number {
    return value.length;  // 에러: T에 length가 있다는 보장 없음
}
// ✅ 올바른 사용
function getLength<T extends { length: number }>(value: T): number {
    return value.length;
}

실수 2: 불필요한 제네릭

// ❌ 불필요한 제네릭
function log<T>(message: string): void {
    console.log(message);
}
// ✅ 제네릭 제거
function log(message: string): void {
    console.log(message);
}

---

정리

핵심 요약

1. 제네릭: 타입을 매개변수화
2. 함수: function fn<T>(value: T): T
3. 인터페이스: interface Box<T>
4. 클래스: class Stack<T>
5. 제약: <T extends Type>
6. keyof: 객체 키 타입

다음 단계

• TypeScript 유틸리티 타입
• TypeScript 데코레이터
• TypeScript 고급 패턴

---

관련 글

• C++ 템플릿 |
• TypeScript 고급 타입 | Union, Intersection, Literal 타입
• TypeScript 인터페이스 | Interface 완벽 가이드
• C++ numeric_limits |
• C++ Union과 Variant |

심화 부록: 구현·운영 관점

이 부록은 앞선 본문에서 다룬 주제(「TypeScript 제네릭 | Generics 완벽 가이드」)를 구현·런타임·운영 관점에서 다시 압축합니다. 도메인별 세부 구현은 글마다 다르지만, 입력 검증 → 핵심 연산 → 부작용(I/O·네트워크·동시성) → 관측의 흐름으로 장애를 나누면 원인 추적이 빨라집니다.

내부 동작과 핵심 메커니즘

flowchart TD
  A[입력·요청·이벤트] --> B[파싱·검증·디코딩]
  B --> C[핵심 연산·상태 전이]
  C --> D[부작용: I/O·네트워크·동시성]
  D --> E[결과·관측·저장]

sequenceDiagram
  participant C as 클라이언트/호출자
  participant B as 경계(런타임·게이트웨이·프로세스)
  participant D as 의존성(API·DB·큐·파일)
  C->>B: 요청/이벤트
  B->>D: 조회·쓰기·RPC
  D-->>B: 지연·부분 실패·재시도 가능
  B-->>C: 응답 또는 오류(코드·상관 ID)

• 불변 조건(Invariant): 버퍼 경계, 프로토콜 상태, 트랜잭션 격리, FD 상한 등 단계별로 문장으로 적어 두면 디버깅 비용이 줄어듭니다.
• 결정성: 순수 층과 시간·네트워크·스케줄에 의존하는 층을 분리해야 테스트와 장애 분석이 쉬워집니다.
• 경계 비용: 직렬화, 인코딩, syscall 횟수, 락 경합, 할당·GC, 캐시 미스를 의심 목록에 둡니다.
• 백프레셔: 생산자가 소비자보다 빠를 때 버퍼·큐·스트림에서 속도를 줄이는 신호를 어디에 둘지 정의합니다.

프로덕션 운영 패턴

영역	운영 관점 질문
관측성	요청 단위 상관 ID, 에러율·지연 p95/p99, 의존성 타임아웃·재시도가 대시보드에 보이는가
안전성	입력 검증·권한·비밀·감사 로그가 코드 경로마다 일관적인가
신뢰성	재시도는 멱등 연산에만 적용되는가, 서킷 브레이커·백오프·DLQ가 있는가
성능	캐시·배치 크기·커넥션 풀·인덱스·백프레셔가 데이터 규모에 맞는가
배포	롤백 룬북, 카나리/블루그린, 마이그레이션·피처 플래그가 문서화되어 있는가
용량	피크 트래픽·디스크·FD·스레드 풀 상한을 주기적으로 검증하는가

스테이징은 데이터 양·네트워크 RTT·동시성을 프로덕션에 가깝게 맞출수록 재현율이 올라갑니다.

확장 예시: 엔드투엔드 미니 시나리오

앞선 본문 주제(「TypeScript 제네릭 | Generics 완벽 가이드」)를 배포·운영 흐름에 맞춰 옮긴 체크리스트입니다. 도메인에 맞게 단계 이름만 바꿔 적용할 수 있습니다.

1. 입력 계약 고정: 스키마·버전·최대 페이로드·타임아웃·에러 코드를 경계에 둔다.
2. 핵심 경로 계측: 요청 ID, 단계별 지연, 외부 호출 결과 코드를 로그·메트릭·트레이스에서 한 흐름으로 본다.
3. 실패 주입: 의존성 타임아웃·5xx·부분 데이터·락 대기를 스테이징에서 재현한다.
4. 호환·롤백: 설정/마이그레이션/클라이언트 버전을 되돌릴 수 있는지 확인한다.
5. 부하 후 검증: 피크 대비 p95/p99, 에러율, 리소스 상한, 알림 임계값을 점검한다.

handle(request):
  ctx = newCorrelationId()
  validated = validateSchema(request)
  authorize(validated, ctx)
  result = domainCore(validated)
  persistOrEmit(result, idempotentKey)
  recordMetrics(ctx, latency, outcome)
  return result

문제 해결(Troubleshooting)

증상	가능 원인	조치
간헐적 실패	레이스, 타임아웃, 외부 의존성, DNS	최소 재현 스크립트, 분산 트레이스·로그 상관관계, 재시도·서킷 설정 점검
성능 저하	N+1, 동기 I/O, 락 경합, 과도한 직렬화, 캐시 미스	프로파일러·APM으로 핫스팟 확인 후 한 가지씩 제거
메모리 증가	캐시 무제한, 구독/리스너 누수, 대용량 버퍼, 커넥션 미반납	상한·TTL·힙/FD 스냅샷 비교
빌드·배포만 실패	환경 변수, 권한, 플랫폼 차이, lockfile	CI 로그와 로컬 diff, 런타임·이미지 버전 핀
설정 불일치	프로필·시크릿·기본값, 리전	스키마 검증된 설정 단일 소스와 배포 매트릭스 표준화
데이터 불일치	비멱등 재시도, 부분 쓰기, 캐시 무효화 누락	멱등 키·아웃박스·트랜잭션 경계 재검토

권장 순서: (1) 최소 재현 (2) 최근 변경 범위 축소 (3) 환경·의존성 차이 (4) 관측으로 가설 검증 (5) 수정 후 회귀·부하 테스트.

배포 전에는 git add → git commit → git push 후 npm run deploy 순서를 권장합니다.

---

자주 묻는 질문 (FAQ)

Q. 이 내용을 실무에서 언제 쓰나요?

A. TypeScript 제네릭: Generics 완벽 가이드. 제네릭 기본·함수 제네릭로 흐름을 잡고 원리·코드·실무 적용을 한글로 정리합니다. TypeScript·Generics·제네릭 중심으로 설명합니다. Start… 실무에서는 위 본문의 예제와 선택 가이드를 참고해 적용하면 됩니다.

Q. 선행으로 읽으면 좋은 글은?

A. 각 글 하단의 이전 글 또는 관련 글 링크를 따라가면 순서대로 배울 수 있습니다. C++ 시리즈 목차에서 전체 흐름을 확인할 수 있습니다.

Q. 더 깊이 공부하려면?

A. cppreference와 해당 라이브러리 공식 문서를 참고하세요. 글 말미의 참고 자료 링크도 활용하면 좋습니다.

---

같이 보면 좋은 글 (내부 링크)

이 주제와 연결되는 다른 글입니다.

• TypeScript 인터페이스 | Interface 완벽 가이드
• TypeScript 유틸리티 타입 | Partial, Pick, Omit, Record
• TypeScript 고급 타입 | Union, Intersection, Literal 타입

---

이 글에서 다루는 키워드 (관련 검색어)

TypeScript, Generics, 제네릭, 타입 등으로 검색하시면 이 글이 도움이 됩니다.