A Batalha: type versus interface no TypeScript — Quando Usar Cada Um?
Chegamos a uma das maiores e mais frequentes discussões de toda a comunidade: type alias vs interface. Ambos modelam a forma de objetos, ambos aceitam generics e ambos suportam herança — afinal, qual é a diferença real, o que acontece sob o capô do compilador e qual deles você deve escolher no seu dia a dia profissional?
📑 Índice do Conteúdo
1. O Território Comum: O Que Ambos Fazem
Historicamente, nas primeiras versões do TypeScript (1.x e 2.x), interface e type possuíam fronteiras bem mais demarcadas. Ao longo da evolução da linguagem, no entanto, a equipe do TypeScript trabalhou para que ambos compartilhassem quase todas as capacidades de modelagem de dados.
Na imensa maioria das situações cotidianas de desenvolvimento, ambos são intercambiáveis para definir o shape (formato) de um objeto:
// 1. Modelagem de Objetos
interface UsuarioInterface {
id: string;
nome: string;
email: string;
}
type UsuarioType = {
id: string;
nome: string;
email: string;
};
// 2. Extensão e Composição
// Interface estende via "extends":
interface AdministradorInterface extends UsuarioInterface {
nivelAcesso: 'total' | 'restrito';
}
// Type estende via interseção "&":
type AdministradorType = UsuarioType & {
nivelAcesso: 'total' | 'restrito';
};
// 3. Assinatura de Funções
interface CalculadoraInterface {
(a: number, b: number): number;
}
type CalculadoraType = (a: number, b: number) => number;
// 4. Implementação em Classes Orientadas a Objetos
class ServicoUsuario implements UsuarioInterface {
id = "usr_01";
nome = "Carlos";
email = "[email protected]";
}
class ServicoUsuarioTipo implements UsuarioType {
id = "usr_02";
nome = "Mariana";
email = "[email protected]";
}
Como visto no exemplo acima, ambos funcionam com classes (implements), ambos suportam parâmetros genéricos (interface Caixa<T> vs type Caixa<T>) e ambos podem ser compostos. Onde, então, residem as divergências que definem a arquitetura de uma aplicação?
2. Diferença Crucial 1: Declaration Merging (Fusão Automática)
A maior e mais impactante distinção conceitual é o Declaration Merging (Mesclagem de Declarações). Se você declarar duas interfaces com o mesmo identificador no mesmo escopo ou módulo, o TypeScript automaticamente une todas as suas propriedades em uma única interface resultante.
Já os Type Aliases proíbem terminantemente a re-declaração, emitindo um erro estático imediato de compilação:
// ==========================================
// INTERFACE: Permite Declaration Merging (Fusão)
// ==========================================
interface JanelaNavegador {
largura: number;
}
// Em outro arquivo ou linha subsequente:
interface JanelaNavegador {
altura: number;
}
// O TypeScript mesclou as duas definições!
const janela: JanelaNavegador = {
largura: 1920,
altura: 1080 // Ambas são obrigatórias!
};
// ==========================================
// TYPE ALIAS: Erro de Compilação Imediato!
// ==========================================
type JanelaConfig = {
largura: number;
};
// ❌ Erro de compilação: TS2300: Duplicate identifier 'JanelaConfig'.
type JanelaConfig = {
altura: number;
};
window no navegador, o objeto process.env no Node.js ou o Request do Express.js quando adiciona middlewares de autenticação (ex: injetar req.usuarioAutenticado). Sem interfaces, estender tipos de terceiros seria impossível!
3. Diferença Crucial 2: Primitivos, Uniões, Tuplas e Tipos Computados
O Type Alias é muito mais amplo e expressivo do que a interface quando o assunto não se limita a objetos literais. Um type é literalmente um apelido para qualquer construção válida do sistema de tipos:
// 1. Apelidar Tipos Primitivos (Interface NÃO pode fazer isso)
type ID = string | number;
type Moeda = 'BRL' | 'USD' | 'EUR';
// 2. Uniões Literais Diretas (Interface NÃO pode fazer união na raiz)
type StatusPedido = 'pendente' | 'pago' | 'enviado' | 'cancelado';
// ❌ Sintaxe Inválida: Não existe "interface Status = 'a' | 'b';"
// 3. Tuplas Estritas (Interface não expressa tuplas de forma idiomática)
type Ponto3D = [x: number, y: number, z: number];
const coordenadas: Ponto3D = [10.5, 20.8, -5.2];
// 4. Tipos Utilitários e Tipos Computados (Mapped Types / Conditional Types)
type ApenasStrings<T> = {
[K in keyof T as T[K] extends string ? K : never]: T[K];
};
Interfaces são restritas a estruturas orientadas a objetos (formas de dicionário e chamáveis). Elas não podem declarar uniões puras na raiz, tipos literais ou mapeamentos dinâmicos de propriedades.
4. Diferença Crucial 3: Desempenho do Compilador e Mensagens de Erro
Nos bastidores, o compilador do TypeScript trata interface e type de maneiras ligeiramente distintas na fase de checagem:
- Cache Nominal de Interfaces: O compilador cria nós nomeados e cacheados em memória para interfaces. Quando ele precisa verificar compatibilidade estrutural em projetos corporativos de grande porte com dezenas de milhares de arquivos, checar uma
interfaceé ligeiramente mais performático do que computar a união ou interseção de múltiplostype. - Legibilidade das Mensagens de Erro: Ao violar um contrato tipado, o TypeScript frequentemente exibe o nome limpo da
interface(ex:Property 'nome' is missing in type '{ id: number; }' but required in type 'Usuario'). Já em tipos compostos gerados por múltiplas interseções detype(A & B & C & D), a mensagem de erro pode despejar todas as propriedades mescladas inline, tornando a leitura do log mais árdua.
5. Sintaxe de Conflitos: extends vs Interseção (&)
Existe uma diferença sutil, mas perigosa, sobre como o compilador lida com conflitos de tipos em propriedades de mesmo nome ao herdar ou combinar definições:
// ==========================================
// INTERFACE: Detecta e Rejeita Conflitos Imediatamente
// ==========================================
interface Base {
id: string;
}
// ❌ Erro de compilação detectado na declaração:
// Interface 'Sub' incorrectly extends interface 'Base'.
// Types of property 'id' are incompatible. Type 'number' is not assignable to type 'string'.
interface Sub extends Base {
id: number;
}
// ==========================================
// TYPE ALIAS: Conflito resulta silenciosamente no tipo 'never'
// ==========================================
type BaseType = {
id: string;
};
// Aqui NÃO há erro na declaração!
// Porém 'id' se torna: string & number => NEVER!
type SubType = BaseType & {
id: number;
};
// ❌ O erro só aparece na hora de instanciar o objeto:
// Type 'string' is not assignable to type 'never'.
const item: SubType = {
id: "123" // Impossível atribuir qualquer valor, pois o campo virou ___WZW_STR_1___!
};
6. Matriz de Decisão: Quando Usar Cada Um?
Abaixo está o quadro de referência definitivo para guiar as escolhas de arquitetura no seu time de desenvolvimento:
| Cenário de Modelagem | interface | type | Recomendação da Indústria |
|---|---|---|---|
| Objetos de Domínio e Entidades | ✅ Excelente | ✅ Excelente | interface (mais limpa, extensível e idiomática) |
| APIs Públicas, SDKs e Bibliotecas | ✅ Suporta fusão | ❌ Não permite fusão | interface (permite que consumidores estendam contratos) |
| Uniões Literais e Primitivos | ❌ Impossível | ✅ Nativo | type (única opção viável para 'a' | 'b') |
| Tuplas Estruturadas | ⚠️ Complexo | ✅ Simples | type (sintaxe direta como [x, y, z]) |
| Tipos Condicionais e Mapeados | ❌ Não suportado | ✅ Suporte total | type (exclusivo do mecanismo de types) |
| Implementação em Classes (OOP) | ✅ implements |
✅ implements |
interface (padrão canônico da Programação Orientada a Objetos) |
interface até que você realmente precise das funcionalidades exclusivas de type“. Essa convenção garante modelos de domínio consistentes, alta legibilidade nas mensagens de erro do compilador e deixa os arquivos abertos para extensão saudável via declaration merging.
window, o Request do Express e bibliotecas npm de terceiros de forma 100% segura.
Aplique o que você aprendeu nesta lição
Utilize nossas ferramentas online gratuitas para experimentar os conceitos ou teste o código ao vivo no Playground IDE.
Editor de Códigos Web Online
Ambiente com destaque de sintaxe para você testar tags, tabelas e scripts na hora.
Abrir Ferramenta OnlinePlayground Web Online
Escreva seu código HTML, CSS ou JavaScript e veja o resultado renderizado ao vivo no navegador com zero configuração.
⚡ Codificar no Playground IDE