Visão geral
interface é ideal para definir contratos de objetos e classes. type (type alias) é mais geral: pode representar uniões, interseções, tuplas, primitivos e tipos mapeados. Em muitos casos de objeto, ambos funcionam de forma intercambiável — a escolha final costuma ser mais sobre convenção do time do que sobre capacidade técnica.
Uma regra prática ajuda a decidir: se a forma é um objeto e existe a intenção de estendê-la, use interface. Se a forma envolve composição — união, interseção, tupla ou primitivo — use type. Fora desses casos, a consistência dentro do projeto vale mais do que a escolha em si.
Diferenças principais
| Aspecto | interface | type |
|---|---|---|
| Extensão (herança) | Suporta extends e declaração conjunta (merging) | Suporta interseção &; não faz declaration merging |
| União / Interseção | Limitado (melhor com type) | Excelente para A | B, A & B |
| Primitivos / Tuplas | Não permitido | Permitido (type ID = string | number) |
| Classes | Pode ser implementado por class implements | Também pode, mas interface é mais idiomático |
| Declaration merging | Sim (útil para augmentação de libs) | Não |
| Erros de mensagem | Mensagens mais claras e específicas | Mensagens mais genéricas em unions |
Exemplos práticos
Extensão com interface
interface User {
id: number;
name: string;
}
interface Admin extends User {
permissions: string[];
}União com type
type Status = "loading" | "success" | "error";
type Result =
| { status: "success"; data: User }
| { status: "error"; message: string };Note o uso de união discriminada: o campo status funciona como discriminante e permite ao TypeScript estreitar o tipo dentro de cada ramo do if. É o padrão mais seguro para modelar estados de requisição.
Interseção
type Timestamped = { createdAt: Date; updatedAt: Date };
type UserWithTimestamps = User & Timestamped;Mesma forma, duas sintaxes
interface Point { x: number; y: number }
type Point = { x: number; y: number }
// Equivalentes para o compilador — mas apenas a interface
// aceita declaration merging e `extends`.Quando usar cada um?
- Use
interfacepara definir formas de objetos que podem ser estendidas por outras partes do código (component props, entidades de domínio, contratos de API). - Use
typepara uniões, interseções, tuplas, primitivos, tipos utilitários e casos mais complexos. - Em código TypeScript moderno, muitos times adotam:
interfacepor padrão para objetos;typequando precisa de união/interseção. Não há regra rígida. - Para props de componentes React, o padrão da comunidade é
interface— o que permite a augmentação de tipos por bibliotecas. - Para resultados de API gerados automaticamente, ambos funcionam; a escolha depende de o tipo precisar ser estendido depois.
Armadilhas comuns
- Declaration merging é acidental. Duas
interfacecom o mesmo nome no mesmo escopo são combinadas silenciosamente. Comtype, isso gera erro de compilação — um dos motivos para preferirtypequando a duplicata seria um bug. - Propriedades opcionais não são
undefined. Emstrict,name?: stringsignificastring | undefined— o compilador obriga você a checar antes de usar. - Index signatures exigem rótulo explícito.
[key: string]: unknowné diferente de{ [key: string]: unknown }e o segundo caso é o correto. - União de objetos é mais estrita que interseção. Em
{ a: string } | { b: number }, o objeto precisa satisfazer um dos ramos completos, o que costuma ser mais rígido do que o esperado.
Conclusão
A diferença prática é menor hoje, mas entender extends vs &, declaration merging e suporte a uniões ajuda a tomar a decisão certa. Para a maioria dos casos, priorize clareza e consistência: defina uma convenção no projeto, aplique-a em code review e você evita metade das discussões sobre estilo. Quando os tipos vierem de respostas de API, use JSON to TypeScript para gerar a base automaticamente — o guia completo está em como converter JSON em TypeScript.