Interface vs type w TypeScript: różnice i kiedy czego użyć

Przy opisywaniu kształtu obiektu interface i type robią to samo, a wartości jednego da się przypisać do drugiego, gdy kształty się zgadzają. Różnice leżą na obrzeżach: type może nazwać rzeczy, których interfejs nie nazwie (unie, krotki, typy wyliczane), a interfejs potrafi kilka rzeczy niedostępnych dla aliasu typu (łączenie, sprawdzane 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 porównuje typy obiektowe według struktury, więc nazwa deklaracji nie ma znaczenia dla przypisywalności. Poniżej jest lista miejsc, w których wybór naprawdę ma znaczenie.

Tabela porównawcza

Co potrafi tylko type

Wszystko, co nie jest pojedynczym kształtem obiektu, wymaga aliasu typu:

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

Żadnego z nich nie da się zapisać przez interface (dwa ostatnie opisują strony o mapped types i conditional types). To praktyczny powód, dla którego każdy projekt w końcu gdzieś używa type, niezależnie od tego, czego używa do kształtów obiektów.

Co potrafi tylko interface: łączenie deklaracji

Dwie deklaracje interface o tej samej nazwie w tym samym zasięgu łączą się w jedną. Dwie deklaracje type o tej samej nazwie to błąd 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'.

Łączenie pozwala rozszerzać typy bibliotek z zewnątrz: dodać właściwość do globalnego Window, do Request z Expressa albo do typu motywu biblioteki. Jeśli publikujesz typy, które użytkownicy mogą chcieć rozszerzyć, używaj interfejsów. We własnym kodzie aplikacji przypadkowe połączenie (dwa pliki skryptów deklarujące tę samą nazwę globalnego interfejsu) dzieje się po cichu, chyba że obie deklaracje mają tę samą właściwość z różnymi typami. To jeden z argumentów, którymi niektóre zespoły uzasadniają wybór type.

extends kontra przecięcie

Interfejs rozszerza się przez extends, alias typu przez &. Zwykle dają ten sam wynik, ale inaczej traktują sprzeczną właściwość. extends zgłasza konflikt przy deklaracji:

// 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'.

Przecięcie przyjmuje ten sam konflikt po cichu i zamienia właściwość w never (string, który jest też number). Błąd pojawia się dopiero później, przy próbie utworzenia wartości:

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");

Błąd wskazuje na obiekt, daleko od deklaracji, która go spowodowała. Przy budowaniu typów obiektowych z innych typów obiektowych extends daje lepszy komunikat.

Sygnatury indeksu: łatwa do przeoczenia różnica

Alias typu obiektowego dostaje niejawną sygnaturę indeksu, więc można go przekazać tam, gdzie oczekiwany jest Record<string, unknown>. Interfejs jej nie dostaje. To celowe: zespół TypeScript wyjaśnia (issue #15300 w repozytorium TypeScript), że interfejs może zostać rozszerzony przez późniejsze deklaracje, więc wnioskowanie dla niego sygnatury indeksu jest mniej bezpieczne, a zmiana reguły teraz zepsułaby zbyt dużo kodu.

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

Wywołanie oznaczone @ts-expect-error i tak się wykonuje i wypisuje pola Alana: to reguła czasu kompilacji. To typowa przyczyna mylącego błędu, gdy wartość interfejsu trafia do funkcji pomocniczej do logowania, serializacji albo zapytań, otypowanej jako Record<string, ...>. Zmień tę jedną deklarację na type, rozwiń wartość spreadem albo otypuj parametr funkcji pomocniczej interfejsem lub generykiem.

Wydajność i komunikaty błędów

Strona Performance w wiki TypeScript (sekcja "Preferring Interfaces Over Intersections") zaleca interface Foo extends Bar, Baz { ... } zamiast type Foo = Bar & Baz & { ... } przy składaniu typów obiektowych. Powody: interfejs to jeden płaski typ obiektowy, który wykrywa konflikty właściwości, relacje typów między interfejsami są cache'owane (przecięcia jako całość nie), a sprawdzenie wartości względem przecięcia sprawdza każdy składnik przed spłaszczonym typem. Różnica ma znaczenie w dużych projektach z wieloma złożonymi typami; przy kilku zwykłych kształtach obiektów jej nie zmierzysz.

Ta sama strona zauważa, że interfejsy lepiej się wyświetlają. Interfejs jest pokazywany pod swoją nazwą w podpowiedziach i komunikatach błędów, a alias przecięcia często jest rozwijany na części, przez co długie komunikaty trudniej się czyta.

Czego używać

Reguła, która działa:

1. Kształty obiektów: interface. Daje sprawdzane extends, czytelniejsze błędy przy dużych złożeniach i pozwala użytkownikom biblioteki go rozszerzać. To zgodne z heurystyką z handbooka TypeScript: „używaj interface, dopóki nie potrzebujesz funkcji type”.
2. Wszystko inne: type. Unie, krotki, typy funkcji, typy literałowe i wszystko, co powstaje z mapped types, conditional types albo template literal types.
3. Wyjątek: używaj type dla kształtu obiektu, który musi pasować do parametrów Record<string, ...>, albo gdy celowo chcesz zablokować łączenie.

Używanie type do wszystkiego to też spójny wybór i wiele projektów tak robi. Jedyna opcja, której warto unikać, to losowe mieszanie obu: czytelnik zaczyna się wtedy zastanawiać, czy różnica była zamierzona.