Una mostra JSON revela les estructures i els valors que han aparegut en una resposta concreta. No demostra el contracte complet d’una API. Convertir-la a TypeScript continua sent útil: redueix la transcripció repetitiva, proporciona un punt de partida compilable i fa visibles les incerteses amb unions, propietats opcionals i unknown[].
Aquesta guia introdueix dos registres sintètics al convertidor de JSON a TypeScript. Hi apareixen una propietat nul·la, una propietat absent en un registre, un objecte imbricat amb un membre opcional, nombres i matrius buides. El resultat es revisa com un esborrany que cal contrastar amb la documentació i amb la validació de dades en execució.
Defineix què pot demostrar la mostra
Si dos objectes d’una matriu contenen una propietat amb tipus diferents, el generador pot formar una unió. Si una propietat falta en un dels objectes, pot marcar-la com a opcional. Si apareix null explícitament, pot incorporar null al tipus. Totes aquestes conclusions deriven dels valors que realment s’han proporcionat.
Que una propietat no aparegui en una mostra petita no demostra que mai existeixi. Que aparegui sempre tampoc demostra que sigui obligatòria. Una matriu buida no aporta cap element per inferir-ne el tipus; per això unknown[] expressa millor la incertesa que any[] o un tipus de domini inventat. Les declaracions ajuden el compilador, però no inspeccionen les respostes futures de la xarxa.
Una mostra que exposa la incertesa
Utilitza exactament aquest JSON:
[
{
"id": 1,
"tag": "alpha",
"active": true,
"notes": [],
"meta": { "source": "api" }
},
{
"id": 2,
"tag": null,
"notes": [],
"meta": { "source": "cache", "age": 3 }
}
]
Tria ApiResponse com a nom arrel i type com a declaració. L’arrel descriu una matriu d’objectes fusionats. id és number; tag combina string i null; active és opcional perquè falta al segon objecte. notes és unknown[] perquè totes dues matrius són buides. Dins de meta, age també és opcional.
El generador produeix TypeScript determinista i compilable. Els espais i la disposició dels objectes en línia són detalls de format; la comprovació semàntica ha de mirar els tipus i l’opcionalitat. Conserva la mostra exacta per poder comparar futures versions de l’eina sense atribuir a un canvi de format una diferència real en el contracte.
Genera, compila i posa a prova la declaració
Obre l’eina, enganxa l’exemple, introdueix ApiResponse, selecciona type i genera. Copia la sortida a un fitxer .ts d’un projecte amb comprovació estricta. Afegeix valors que coincideixin amb els dos registres observats i executa el compilador. La declaració i aquestes assignacions han de compilar sense diagnòstics.
Introdueix després una incompatibilitat deliberada, com ara un id de tipus cadena. El compilador ha de rebutjar-la. Això demostra que la declaració participa en la comprovació estàtica, però no que una resposta HTTP es validarà automàticament. Per comprovar dades en execució, analitza la resposta i aplica un esquema o una guarda explícita abans de tractar-la com a ApiResponse.
Repeteix la generació amb interface. Les formes d’objecte poden expressar-se amb interfícies; una arrel que sigui matriu o valor primitiu necessita un àlies de tipus. Compara el significat, sense exigir que cada línia comenci amb la paraula seleccionada. Descarrega el resultat i compila aquest mateix fitxer abans d’incorporar-lo al projecte.
Com combina el generador les observacions
El generador examina tots els objectes d’una matriu, no només el primer. Uneix els conjunts de propietats, afegeix ? quan en falta alguna i combina els tipus observats en unions estables. Els objectes imbricats es representen amb tipus d’objecte interns. Les matrius consideren tots els elements disponibles, de manera que una matriu heterogènia pot produir una unió.
Els nombres JSON es converteixen en number: una mostra no estableix si el domini només admet enters ni quin rang és correcte. Les cadenes continuen sent string; no s’infereixen dates, URL especialitzades, enumeracions ni unions de literals a partir de pocs exemples. Un null explícit es conserva i és diferent d’una propietat absent. Amb comprovació estricta de nul·litat, qui utilitzi el valor ha de gestionar aquesta possibilitat.
Les claus que no són identificadors vàlids s’escriuen entre cometes i amb els escapaments necessaris. El nom arrel, en canvi, ha de seguir la sintaxi d’identificador ASCII admesa i no pot ser un nom reservat. Les claus i els tipus primitius s’ordenen de manera determinista perquè una nova generació sigui revisable i no produeixi diferències arbitràries.
Resol els errors d’entrada i de generació
Un error JSON s’ha de corregir a l’origen. Busca comes finals, claus sense cometes, claudàtors desparellats o prefixos copiats d’un registre. La guia d’errors JSON ajuda a aïllar aquests problemes. Una expressió d’objecte JavaScript no és necessàriament JSON vàlid, encara que visualment s’hi assembli.
Un nom arrel invàlid pot contenir espais, puntuació, començar per un dígit o ser reservat. Utilitza un nom descriptiu com ApiResponse, no una ruta, un nom de fitxer o una URL. Les propietats del JSON no tenen la mateixa restricció, perquè el generador les pot representar amb cometes. No canviïs les claus de les dades només per evitar una propietat textual al tipus.
Es rebutgen entrades de més de 200 KiB en UTF-8 o més de 50 nivells de contenidors imbricats, comptant el contenidor arrel com a primer nivell. Redueix la mostra a registres representatius i sintètics. No eliminis tancaments arbitraris per fer-la més curta. Una estructura recursiva profunda necessita un model dissenyat, no una expansió mecànica indefinida de tipus en línia.
Converteix l’esborrany en un contracte mantingut
Contrasta la declaració amb l’esquema oficial de l’API i amb respostes representatives: èxit, resultat buit, permisos parcials, registres antics i errors. Ajusta unions i propietats opcionals a partir de comportaments documentats. Posa nom als conceptes imbricats que es reutilitzen i afegeix comentaris que identifiquin la versió del contracte, no només la data de la mostra.
Combina els tipus estàtics amb validació en el punt d’entrada de dades externes. Els tipus TypeScript desapareixen quan s’executa JavaScript. Una asserció de tipus pot silenciar el compilador sense comprovar cap valor. Analitza JSON, valida l’entrada desconeguda i exposa després el resultat comprovat al codi tipat de l’aplicació.
No utilitzis respostes reals de clients com a exemples si contenen informació innecessària. El convertidor treballa al navegador, però una mostra copiada, un fitxer descarregat, una captura o una incorporació al repositori poden revelar dades. Minimitza els exemples i substitueix identificadors i text lliure. La guia de privacitat de les eines amplia aquests criteris.
Quan una declaració ja té revisions manuals, conserva-les de manera conscient. Tornar a generar pot eliminar noms útils o restriccions afegides segons la documentació. Compara el canvi i incorpora només allò que reflecteixi un canvi real de contracte. La mostra és una evidència, però no ha de substituir automàticament decisions de modelatge ja justificades.
Límits dels tipus derivats de mostres
L’eina només infereix a partir del JSON proporcionat. No descobreix variants absents, requisits condicionals, intervals numèrics, formats semàntics ni canvis futurs. No fa peticions de xarxa, no llegeix OpenAPI, no genera validadors en execució i no garanteix que la mostra sigui representativa. Un tipus compilable pot continuar sent massa ampli o massa restrictiu per a l’API real.
Tots els nombres es representen amb number; les cadenes no esdevenen dates; les matrius buides es representen amb unknown[]. Les propietats només es marquen opcionals quan el conjunt observat mostra absència. Mantén presents el límit de 200 KiB i la profunditat de 50. Revisa especialment les suposicions que la mostra no permet provar, encara que el resultat sembli complet.
Comprovacions finals de TypeScript
Utilitza JSON vàlid i sintètic, i un identificador arrel admès. Inclou diversos objectes si cal observar unions o absències. Revisa cada ?, null, unió, objecte imbricat i unknown[]. Escull interface o type segons les convencions del projecte, acceptant l’àlies quan l’arrel no sigui un objecte.
Compila el fitxer descarregat amb les opcions estrictes del projecte. Prova una assignació vàlida i una altra deliberadament incorrecta. Contrasta el resultat amb la documentació oficial i valida les respostes externes en execució. Anota els casos utilitzats i repeteix la inferència quan canviï el contracte. Revisa sempre les diferències abans de substituir declaracions que ja estiguin mantingudes.
Fonts: manual TypeScript: tipus d’objecte, manual TypeScript: unions i interseccions i RFC 8259: format JSON.