JSON a TypeScript: tipos que correspondem à realidade

Por que os tipos escritos à mão mudam

Interfaces escritas a partir de documentação ou de memória tendem a ser otimistas. Eles marcam tudo o que está presente, assumem que um campo anulável está sempre lá e ignoram silenciosamente o objeto aninhado que só aparece em contas premium. TypeScript então impõe uma forma que o servidor nunca prometeu, e os primeiros `undefined` surgem na produção e não em tempo de compilação. Gerar a partir de respostas reais inverte o processo: o compilador está verificando uma forma observada em vez de uma forma esperada.

Lendo o arquivo gerado

Uma conversão útil nomeia objetos aninhados após suas chaves, mantém intactos os tipos de elementos da matriz e expressa a incerteza explicitamente. Fique atento aos três marcadores que carregam todo o significado:

                export interface Order {
  id: string;
  total: number;
  coupon?: string;            // absent in some responses
  shippedAt: string | null;   // present but null until shipped
  items: Array<OrderItem>;
}
              

A diferença entre `coupon?: string` e `shippedAt: string | null` não é cosmética. Opcional significa que a chave pode estar faltando; null significa que a chave está lá sem valor. As APIs fazem as duas coisas, geralmente na mesma carga útil, e combiná-las gera uma verificação nula no código que assumia uma string.

Use mais de uma amostra

Uma única resposta marca tudo o que é necessário. Cole duas ou três respostas – de preferência uma de uma conta vazia e outra de uma conta completa – e as chaves opcionais se revelam: um campo ausente em qualquer amostra torna-se `?`, e um campo que às vezes é nulo torna-se uma união com `null`. Esta é a atualização de correção mais barata disponível e é a razão pela qual os tipos gerados devem ser regenerados quando o API muda, em vez de serem gravados uma vez.

Nunca deixe que uma interface gerada seja a única descrição do seu API. Mantenha um esquema ou teste de contrato junto com ele, para que uma alteração no servidor falhe na construção em vez de na sessão do usuário.

Onde os tipos pertencem

• Uma pasta `types/` ou `api/` dedicada, não espalhada pelos componentes.
• Um arquivo por endpoint ou por recurso, com um comentário nomeando o endpoint e a data em que foi capturado.
• Uma nota de regeneração: qual chamada produziu a carga útil, para que a próxima pessoa possa repeti-la.
• Uma exportação consumida pela camada de busca e pelos componentes, portanto, uma alteração quebra exatamente um lugar.

Ative o modo estrito

Os tipos gerados só compensam com `strict` ativado, porque é isso que torna uma chave opcional um erro real quando acessada diretamente. Emparelhe interfaces geradas com `unknown` no limite de busca e estreite antes de usar: `JSON.parse` retorna `any`, portanto, uma conversão para a interface gerada deve ser o ponto onde você validou, não onde você espera.

Gere a partir de cargas que você não enviaria

API as respostas são as JSON mais sensíveis que a maioria dos desenvolvedores manipula — dados de contas, pedidos, tokens. Executar a conversão de JSON para TypeScript no navegador significa que a carga é analisada localmente e nunca transmitida, então você pode colar uma resposta real sem editá-la primeiro, e a ferramenta continua funcionando offline.