TypeScript interface vs type 차이: 언제 무엇을 쓸까

객체의 모양을 기술하는 데는 interface와 type이 같은 일을 하고, 모양이 맞으면 한쪽의 값을 다른 쪽에 대입할 수 있습니다. 차이는 가장자리에 있습니다. type은 인터페이스가 이름 붙일 수 없는 것(유니언, 튜플, 계산된 타입)에 이름을 붙일 수 있고, 인터페이스는 타입 별칭이 할 수 없는 몇 가지(병합, 검사되는 extends)를 할 수 있습니다.

interface PointI {
  x: number;
  y: number;
}

type PointT = {
  x: number;
  y: number;
};

const a: PointI = { x: 1, y: 2 };
const b: PointT = a; // same shape, so they are interchangeable
const c: PointI = b;

function show(p: PointI): string {
  return `(${p.x}, ${p.y})`;
}

console.log(show(b), show(c)); // (1, 2) (1, 2)

TypeScript는 객체 타입을 구조로 비교하므로, 대입 가능성에는 선언의 이름이 중요하지 않습니다. 이어지는 내용은 선택이 실제로 중요해지는 곳의 목록입니다.

비교표

type만 할 수 있는 것

객체 모양 하나가 아닌 것은 모두 타입 별칭이 필요합니다.

type Status = "idle" | "loading" | "done";                   // union of literals
type Coordinates = [lat: number, lng: number];               // tuple
type Handler = (event: string) => void;                      // function type
type ID = string | number;                                   // union of primitives
type Flags<T> = { [K in keyof T]: boolean };                 // mapped type
type ElementOf<T> = T extends readonly (infer U)[] ? U : T;  // conditional type

const current: Status = "loading";
const here: Coordinates = [51.5, -0.12];
const onSave: Handler = (e) => console.log("saved:", e);
const flags: Flags<{ dark: string; beta: number }> = { dark: true, beta: false };
const first: ElementOf<string[]> = "a";

onSave(current);
console.log(here, flags, first);
// saved: loading
// [ 51.5, -0.12 ] { dark: true, beta: false } a

이 중 어느 것도 interface로는 쓸 수 없습니다(마지막 두 가지는 매핑된 타입과 조건부 타입에서 다룹니다). 객체 모양에 무엇을 쓰든 모든 코드베이스가 결국 어딘가에서 type을 쓰게 되는 실질적인 이유입니다.

interface만 할 수 있는 것: 선언 병합

같은 스코프에서 같은 이름의 interface 선언 두 개는 하나로 합쳐집니다. 같은 이름의 type 선언 두 개는 오류 TS2300, Duplicate identifier입니다.

interface Settings {
  theme: string;
}
interface Settings {
  fontSize: number;
}
const s: Settings = { theme: "dark", fontSize: 14 }; // needs both

type Options = { a: number };
type Options = { b: number }; // error TS2300: Duplicate identifier 'Options'.

병합은 라이브러리 타입을 밖에서 확장하는 방법입니다. 전역 Window, Express의 Request, 라이브러리의 테마 타입에 속성을 추가하는 식입니다. 사용자가 보강해야 할 수도 있는 타입을 배포한다면 인터페이스를 쓰세요. 자신의 애플리케이션 코드에서는 뜻하지 않은 병합(스크립트 파일 두 개가 같은 이름의 전역 인터페이스를 선언하는 경우)이, 둘이 같은 속성을 다른 타입으로 선언하지 않는 한 조용히 일어납니다. 일부 팀이 type을 선호하는 이유 중 하나입니다.

extends와 교차 타입

인터페이스는 extends로, 타입 별칭은 &로 확장합니다. 대부분 같은 결과를 내지만, 충돌하는 속성을 다루는 방식이 다릅니다. extends는 선언에서 충돌을 보고합니다.

// This does not compile: id cannot change from string to number
interface Base {
  id: string;
  name: string;
}

interface Broken extends Base {
  id: number;
}

const x: Broken = { id: 1, name: "a" };
console.log(x);

index.ts(7,11): error TS2430: Interface 'Broken' incorrectly extends interface 'Base'.
  Types of property 'id' are incompatible.
    Type 'number' is not assignable to type 'string'.

교차 타입은 같은 충돌을 조용히 받아들이고 그 속성을 never(number이기도 한 string)로 만듭니다. 오류는 나중에 값을 만들려고 할 때에야 나타납니다.

type Base = { id: string; name: string };
type Broken = Base & { id: number }; // no error here

// id is string & number, which is never: no object can satisfy Broken
// @ts-expect-error: Type 'number' is not assignable to type 'never'.
const x: Broken = { id: 1, name: "a" };

console.log("the alias compiled; only using it failed");

오류는 원인이 된 선언에서 멀리 떨어진 객체를 가리킵니다. 다른 객체 타입으로 객체 타입을 만들 때는 extends가 더 나은 메시지를 줍니다.

인덱스 시그니처: 놓치기 쉬운 차이

객체 타입의 타입 별칭은 암묵적 인덱스 시그니처를 받으므로 Record<string, unknown>이 기대되는 곳에 넘길 수 있습니다. 인터페이스는 그렇지 않습니다. 의도된 설계입니다. TypeScript 팀의 설명(TypeScript 저장소의 이슈 #15300)에 따르면 인터페이스는 나중의 선언으로 보강될 수 있으므로 인덱스 시그니처를 추론하는 것이 덜 안전하고, 지금 규칙을 바꾸면 너무 많은 코드가 깨집니다.

interface UserI { name: string; age: number }
type UserT = { name: string; age: number };

function logFields(fields: Record<string, unknown>) {
  for (const [key, value] of Object.entries(fields)) {
    console.log(`${key}=${String(value)}`);
  }
}

const t: UserT = { name: "Ada", age: 36 };
const i: UserI = { name: "Alan", age: 41 };

logFields(t); // fine

// @ts-expect-error: Index signature for type 'string' is missing in type 'UserI'.
logFields(i);

logFields({ ...i }); // a spread copy is a fresh object type, so it is accepted

@ts-expect-error로 표시한 호출도 그대로 실행되어 Alan의 필드를 출력합니다. 컴파일 시점의 규칙이기 때문입니다. Record<string, ...>으로 타입이 지정된 로깅, 직렬화, 쿼리 헬퍼에 인터페이스 값을 넘길 때 헷갈리는 오류가 나는 흔한 이유입니다. 그 선언 하나를 type으로 바꾸거나, 값을 펼치거나, 헬퍼의 매개변수를 인터페이스나 제네릭으로 지정하세요.

성능과 오류 메시지

TypeScript 위키의 Performance 페이지("Preferring Interfaces Over Intersections" 절)는 객체 타입을 조합할 때 type Foo = Bar & Baz & { ... }보다 interface Foo extends Bar, Baz { ... }를 권합니다. 이유는 이렇습니다. 인터페이스는 속성 충돌을 감지하는 하나의 평평한 객체 타입이고, 인터페이스 사이의 타입 관계는 캐시되며(교차 타입 전체는 캐시되지 않습니다), 교차 타입에 대해 값을 검사하면 평평해진 타입보다 먼저 모든 구성 요소를 검사합니다. 조합된 타입이 많은 대규모 코드베이스에서는 차이가 나지만, 평범한 객체 모양 몇 개로는 측정되지 않을 것입니다.

같은 페이지는 인터페이스가 더 잘 표시된다고도 말합니다. 인터페이스는 마우스를 올렸을 때와 오류 메시지에서 이름으로 표시되지만, 교차 타입 별칭은 종종 구성 요소로 펼쳐서 출력되어 긴 메시지를 읽기 어렵게 만듭니다.

무엇을 쓸까

잘 통하는 규칙:

1. 객체 모양: interface. 검사되는 extends, 큰 조합에서의 더 명확한 오류를 주고, 라이브러리 사용자가 보강할 수 있게 합니다. TypeScript 핸드북의 경험칙 "use interface until you need to use features from type"(type의 기능이 필요할 때까지는 interface를 쓰라)과 일치합니다.
2. 그 밖의 모든 것: type. 유니언, 튜플, 함수 타입, 리터럴 타입, 그리고 매핑된 타입, 조건부 타입, 템플릿 리터럴 타입으로 만든 모든 것.
3. 예외: Record<string, ...> 매개변수에 맞아야 하는 객체 모양이거나 일부러 병합을 막고 싶을 때는 type을 쓰세요.

모든 것에 type을 쓰는 것도 일관된 선택이고, 많은 코드베이스가 그렇게 합니다. 피해야 할 유일한 선택은 둘을 무작위로 섞는 것입니다. 읽는 사람이 차이가 의도된 것인지 궁금해하게 되기 때문입니다.