JSON a TypeScript: tipos que se ajustan a la realidad

¿Por qué los tipos escritos a mano se desvían?

Las interfaces escritas a partir de documentación o de memoria tienden a ser optimistas. Marcan todo lo presente, asumen que siempre hay un campo anulable y silenciosamente pasan por alto el objeto anidado que solo aparece en cuentas premium. Luego, TypeScript impone una forma que el servidor nunca prometió, y el primer `undefined` aparece en producción en lugar de en tiempo de compilación. Generar a partir de respuestas reales invierte el proceso: el compilador comprueba una forma observada en lugar de una esperada.

Leyendo el archivo generado

Una conversión útil nombra objetos anidados después de sus claves, mantiene intactos los tipos de elementos de la matriz y expresa la incertidumbre explícitamente. Esté atento a los tres marcadores que contienen todo el 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>;
}
              

La diferencia entre `coupon?: string` y `shippedAt: string | null` no es cosmética. Opcional significa que puede faltar la clave; nulo significa que la clave está ahí sin valor. Las API hacen ambas cosas, a menudo en la misma carga útil, y al combinarlas se genera una verificación nula en el código que asume una cadena.

Utilice más de una muestra

Una sola respuesta marca todo lo requerido. Pegue dos o tres respuestas (idealmente una de una cuenta vacía y otra de una llena) y las claves opcionales se revelarán: un campo que falta en cualquier muestra se convierte en `?`, y un campo que a veces es nulo se convierte en una unión con `null`. Esta es la actualización de corrección más barata disponible y es la razón por la que los tipos generados deben regenerarse cuando cambia el API en lugar de escribirse una vez.

Nunca permita que una interfaz generada sea la única descripción de su API. Mantenga un esquema o una prueba de contrato junto a él, de modo que un cambio de servidor falle en una compilación en lugar de en una sesión de usuario.

Donde pertenecen los tipos

• Una carpeta dedicada `types/` o `api/`, que no se encuentre dispersa entre los componentes.
• Un archivo por punto final o por recurso, con un comentario que nombra el punto final y la fecha en que se capturó.
• Una nota de regeneración: qué llamada produjo la carga útil, para que la siguiente persona pueda repetirla.
• Una exportación consumida tanto por la capa de recuperación como por los componentes, por lo que un cambio se interrumpe exactamente en un lugar.

Activar el modo estricto

Los tipos generados solo dan resultados con `strict` habilitado, porque eso es lo que hace que una clave opcional sea un error real cuando se accede directamente. Empareje las interfaces generadas con `unknown` en el límite de recuperación y estreche antes de usarlas: `JSON.parse` devuelve `any`, por lo que una conversión a la interfaz generada debe ser el punto donde ha validado, no donde espera.

Generar a partir de cargas útiles que no cargarías

Las respuestas API son las JSON más sensibles que manejan la mayoría de los desarrolladores: datos de cuentas, pedidos, tokens. Ejecutar la conversión de JSON a TypeScript en el navegador significa que la carga útil se analiza localmente y nunca se transmite, por lo que puedes pegar una respuesta real sin redactarla primero y la herramienta sigue funcionando sin conexión.