unknown vs any em TypeScript: o que escolher em 2025?

Introdução: por que este tópico explodiu no Stack Overflow?

\n

Se você já escreveu em TypeScript, certamente já enfrentou o dilema: unknown ou any? A pergunta, que acumulou milhares de visualizações no Stack Overflow, não perde a relevância em 2025. Parece que ambos os tipos permitem armazenar qualquer coisa — então qual é a diferença?

\n\n

Imagine que você está construindo uma casa. any é uma porta escancarada para todos, incluindo ladrões. unknown é uma porta com fechadura e olho mágico: você primeiro verifica quem chegou, depois deixa entrar. Neste artigo, vamos entender por que unknown se tornou o padrão ouro de segurança em TypeScript, e any — o mal que às vezes é justificado.

\n\n

Não vamos apenas recontar a documentação. Vamos mostrar casos reais da prática em 2025, analisar as melhores práticas e dar um algoritmo claro de escolha. Vamos lá!

\n\n

O que é any e por que todos o temem?

\n\n

any é o tipo mais "flexível" em TypeScript. Ele literalmente diz ao compilador: "Desligue o sistema de tipos, eu sei o que estou fazendo". Parece um superpoder, mas na prática é uma bomba-relógio.

\n\n

Exemplo: como any quebra os tipos

\n

function processUser(user: any) {\n    console.log(user.name.toUpperCase()); // Erro em tempo de execução se user for null\n}\n\nprocessUser(null); // TypeError: Cannot read property 'toUpperCase' of null

\n\n

O compilador TypeScript nem sequer avisará você sobre isso! any desativa todas as verificações, e o erro só aparecerá em produção. Em 2025, com projetos cada vez mais complexos, essa abordagem é o caminho para o caos.

\n\n

Quando any ainda é útil?

\n

\n
• Migração de JavaScript: ao reescrever um projeto antigo, any é uma muleta temporária.
\n
• Dados dinâmicos: por exemplo, respostas de APIs externas cuja estrutura muda.
\n
• Testes: em mocks, às vezes é mais fácil usar any do que descrever tipos complexos.
\n

\n\n

Mas lembre-se: any é como um cartão de crédito com limite infinito. É conveniente, até a conta chegar.

\n\n

Unknown: o guardião rigoroso na entrada

\n\n

unknown surgiu no TypeScript 3.0 como uma alternativa segura ao any. Ele também pode conter qualquer valor, mas proíbe trabalhar com ele sem uma verificação explícita. É um tipo-contêiner que exige verificação.

\n\n

Exemplo: unknown em ação

\n

function processUser(user: unknown) {\n    // Erro de compilação! A propriedade 'name' não existe no tipo 'unknown'\n    // console.log(user.name.toUpperCase()); \n    \n    // É necessária uma verificação\n    if (user && typeof user === 'object' && 'name' in user) {\n        const typedUser = user as { name: string };\n        console.log(typedUser.name.toUpperCase()); // Tudo ok\n    }\n}\n\nprocessUser({ name: "Alice" }); // ALICE\nprocessUser(null); // Não vai quebrar

\n\n

Notou a diferença? unknown não permite que você atire no próprio pé. Você é obrigado a verificar o tipo antes de usar. Isso é a tipagem segura.

\n\n

Comparação any vs unknown em tabela

\n\n

Para fixar o conteúdo, vamos ver as principais diferenças:

\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n

Critério	any	unknown
Atribuição de qualquer valor	✅ Sim	✅ Sim
Acesso a propriedades sem verificação	✅ Sim	❌ Não
Atribuição a outro tipo	✅ Qualquer um	❌ Apenas any ou unknown
Proteção contra erros em tempo de execução	❌ Não	✅ Sim (exige verificação)

\n\n

Como você pode ver, unknown vence