Input (schema .proto)

Output (esempio JSON)

Cosa fa questo strumento

Hai uno schema Protocol Buffers e ti serve un esempio JSON di come uno di quei messaggi appare — per una fixture di test, un esempio OpenAPI, una risposta gRPC mockata, qualunque cosa. Scrivere a mano una forma JSON da un file .proto lungo è noioso e ti fa sbagliare. Questo convertitore legge lo schema, prende l'ultimo message dichiarato (il tipico tipo "esterno") e produce un oggetto JSON corrispondente, campo per campo.

L'output usa i valori di default proto3 ufficiali: stringa vuota per string e bytes, 0 per i tipi numerici, false per bool, [] per repeated, {} per map e la costante enum a valore zero per i campi enum. I messaggi annidati vengono espansi ricorsivamente. Gli interi a 64 bit escono come stringhe JSON per stare alla spec del mapping JSON proto3 — non puoi mettere un int64 in un Number JS senza perdere precisione.

Tutto avviene localmente nel browser — nessun upload del .proto, nessuno schema mandato a un server, nessuna chiamata di inferenza. Solo un parser fatto in casa che gestisce le direttive syntax/package/import, i commenti (riga e blocco), i blocchi annidati message ed enum, oneof, map<K, V>, repeated, optional e le opzioni di campo (lette ma ignorate). Se ti serve una runtime completa stile protobufjs, è un altro problema — ma per "dammi una forma JSON da questo schema", questo è più rapido.

Come si usa

Tre passi. Il JSON in uscita è pronto per essere incollato in una fixture, in un blocco di esempio o nel body di una richiesta.

Incolla il tuo schema .proto

Metti lo schema nell'editor di sinistra. syntax = "proto3"; in cima va bene ma è opzionale — al parser non importa. Commenti, dichiarazioni di package e istruzioni import vengono saltati senza problemi. Se hai più messaggi, il parser usa l'ultimo message di livello root (tipicamente il tipo esterno/composto) come radice.

Vuoi convertire un altro messaggio? Sposta quello che ti interessa in fondo al file. Lo schema può contenere tipi annidati, enum e blocchi oneof — tutto si risolve.

Premi Convert

Clicca il bottone verde Convert. Il parser tokenizza lo schema, costruisce un albero di messaggi e percorre il messaggio root emettendo i default proto3 per ogni campo. I messaggi annidati vengono espansi inline. I campi repeated producono un array di un elemento come indizio della forma dell'elemento — un array vuoto non mostrerebbe la struttura.

Usa il JSON

Copia il risultato nella tua fixture di test, nel tuo blocco di esempio OpenAPI, nel mock gRPC-Web o ovunque ti serva una forma di richiesta/risposta. Le chiavi corrispondono esattamente ai nomi dei campi del .proto — passa a camelCase dopo se il tuo codegen fa così.

Quando ti fa davvero risparmiare tempo

Stub di risposte gRPC per i test

Il tuo service handler ritorna una risposta Protobuf. Lo unit test ha bisogno di una fixture JSON che corrisponda alla forma del messaggio. Incolli il <code>.proto</code>, prendi il JSON, lo metti nella cartella delle fixture. Basta scrivere a mano 30 campi e dimenticarne uno.

Esempi OpenAPI per un gRPC-gateway

Stai usando grpc-gateway o simili per esporre servizi Protobuf come REST? Ogni operazione vuole un esempio JSON. Converti ogni messaggio .proto in uno scheletro JSON e incollalo sotto la chiave example nella tua spec.

Bootstrap di JSON Schema

Vuoi validare richieste JSON che combacino con un contratto <code>.proto</code>. Converti prima in un esempio JSON, passalo a un tool JSON-Schema-from-sample e hai uno schema iniziale in pochi secondi.

Riempire i body di richiesta nei client API

Stai testando un'API gRPC transcodificata su HTTP in Postman o con curl? Incolla il .proto, copia lo scheletro JSON nel body della richiesta, riempi i valori che vuoi davvero mandare.

Domande frequenti

Il mio schema .proto viene mandato da qualche parte?

No. Il parsing avviene interamente nel browser via JavaScript. Niente del tuo schema — nomi dei messaggi, nomi dei campi, path di package — esce dalla tua macchina. Apri i DevTools e guarda il tab Network mentre clicchi Convert. Zero richieste.

Gestisce proto2 oltre a proto3?

Per lo più sì. Il parser gestisce token di sintassi proto2 come required e optional, ma i valori di output usano i default proto3 (cioè quel che specifica il mapping JSON proto3). Se hai un file proto2 con default espliciti via [default = ...], quei default non vengono applicati all'output.

Come sceglie quale messaggio convertire?

Usa l'ultimo message di livello top dichiarato nel file. Negli schemi reali il tipo esterno/composto si dichiara di solito dopo le sue dipendenze, quindi questo combacia con quel che vuoi. Se sceglie quello sbagliato, riordina il file in modo che il messaggio voluto sia ultimo.

Perché i valori int64 sono stringhe nell'output?

Perché JSON ha solo double IEEE-754, che perdono precisione sopra 2^53. Il mapping JSON proto3 ufficiale chiede che int64, uint64, fixed64, sfixed64, sint64 siano codificati come stringhe JSON. Seguiamo quella convenzione.

E oneof, map e repeated?

Tutti e tre funzionano. I campi oneof vengono parsati come campi normali (l'oggetto JSON li include tutti invece di sceglierne uno — di solito cancelli quelli che non vuoi). map<K, V> emette un oggetto {} vuoto. repeated emette un array di un singolo elemento che mostra la forma dell'elemento — puoi duplicare o cancellare per adattare ai tuoi dati reali.

Segue gli import?

No. Le istruzioni import vengono riconosciute e saltate. I tipi di messaggio cross-file si risolvono in null nell'output. Se serve la risoluzione cross-file, incolla i messaggi pertinenti dei file importati nello stesso input.

Quanto grande può essere uno schema?

Decine di migliaia di righe, nessun problema. Tutto è locale, quindi niente upload, niente rate limit, niente latenza di rete.

Strumenti correlati

Se stai armeggiando con Protobuf, JSON e schemi, questi vanno bene insieme:

Convertitore da Protobuf a JSON