Input (schema .proto)

Output (.proto formattato)

Cosa fa questo strumento

Incolli uno schema Protocol Buffers con indentazione mista, dichiarazioni di campo appiccicate o righe vuote sparse rimaste da un copia-incolla, e vuoi che assomigli al resto del repo. Questo formattatore riscrive il file con due spazi di indentazione per livello di parentesi graffa, esattamente uno spazio attorno a =, uno spazio dopo , e al massimo una riga vuota consecutiva tra blocchi. I commenti — sia quelli di riga // sia i commenti di blocco /* ... */ — restano esattamente dove li hai messi.

Non fa parsing né valida lo schema, il che significa che funziona anche su input leggermente rotti, dove buf format o il "Format Document" del tuo editor potrebbero non farcela. Se il tuo .proto ha un errore di sintassi da qualche parte, il resto del file viene comunque formattato attorno. Il rovescio della medaglia: non può riordinare i campi, normalizzare l’ordine degli import o rimuovere opzioni inutilizzate come farebbe un vero formattatore basato su parser. Per quello, lancia buf format nella tua pipeline di build.

Tutto gira nel tuo browser — niente upload, niente rate limit, nessuno schema spedito da nessuna parte. Utile quando lo schema contiene nomi di package interni, nomi di tipo o qualunque cosa che non vorresti spedire a un’API di terzi. Funziona su qualunque dimensione il tuo browser riesca a tenere in memoria; anche decine di migliaia di righe vengono formattate in molto meno di un secondo.

Come si usa

Tre passi. L’output si aggiorna circa 300 ms dopo che smetti di digitare.

Incolla il tuo schema .proto

Buttalo nell’editor di sinistra. syntax, package, direttive import, blocchi message, enum annidati, oneof, map<K, V> — tutto gestito. I terminatori di riga misti (CRLF) vengono normalizzati a LF in uscita.

Il formattatore non riordina nulla — campi, import e opzioni restano nell’ordine in cui li hai scritti. Se vuoi un ordinamento canonico, lancia dopo buf format.

Leggi l’output formattato

A destra: lo stesso schema, indentato di 2 spazi per ogni livello di {. Le righe che iniziano con } vengono de-indentate prima di essere emesse. Più righe vuote consecutive vengono compresse in una. Lo spazio bianco a fine riga viene rimosso. I commenti sono preservati alla lettera, posizione relativa inclusa.

Usa il risultato

Copialo nel tuo editor o scaricalo come formatted.proto. Per protoc l’output è byte per byte equivalente all’input — cambiano solo gli spazi — quindi puoi rimetterlo dentro senza preoccuparti di differenze a livello di wire format o di codice generato. Verificalo lanciando protoc --descriptor_set_out=before.pb input.proto e lo stesso sull’output formattato: i descriptor coincideranno.

Quando fa davvero risparmiare tempo

Pulire un .proto incollato da chat o documentazione

Un collega incolla un frammento di schema su Slack, l’indentazione è fatta a pezzi, e tu lo vuoi nel tuo repo. Buttalo qui, copia la versione formattata, incolla nel tuo file. Più rapido del balletto "seleziona tutto, ritabula" nell’editor.

Standardizzare .proto legacy in un vecchio repo

Hai ereditato un repo Protobuf in cui ogni file usa un’indentazione diversa. Passa ogni file in questo formattatore, fai un singolo commit di normalizzazione e poi attiva buf format in CI per mantenerlo così.

Controllare velocemente un .proto generato

Alcuni generatori di codice (JSON Schema → Protobuf, OpenAPI → Protobuf) producono schemi validi ma brutti. Formatta l’output, dagli un’occhiata, decidi se tenere il generatore o sistemare a mano.

Quando non puoi installare protoc o buf

Sei su una macchina blindata, su una rete ospite o stai solo recensendo una PR dal browser. Il formattatore solo-browser ti dà lo stesso output leggibile senza dover installare la toolchain di Protocol Buffers.

Domande frequenti

Il mio schema viene spedito da qualche parte?

No. Il formattatore gira interamente nel tuo browser come JavaScript. Niente dello schema — nomi di message, percorsi di package, commenti — esce dalla tua macchina. Apri i DevTools e guarda il tab Network mentre incolli; vedrai zero richieste.

Conserva i commenti?

Sì — sia i commenti di riga // sia quelli di blocco /* ... */ restano esattamente dove li hai messi. I commenti su una propria riga mantengono la posizione relativa; i commenti in coda a una riga di campo restano agganciati a quel campo. L’approccio basato sulle righe è stato scelto proprio per far sopravvivere i commenti intatti.

In cosa è diverso da buf format?

buf format fa parsing dello schema in un albero sintattico e lo riemette. Questo dà garanzie più forti — ordinamento canonico delle opzioni, casing coerente degli enum, ecc. — ma richiede che lo schema parsi pulito. Questo formattatore è basato sulle righe, quindi funziona su input leggermente rotti che buf rifiuterebbe, e non impone un ordinamento canonico. Per codice finito, lancia buf format. Per schemi a metà modifica o frammenti di terze parti, usa questo.

Cambia la semantica dello schema?

No — cambiano solo gli spazi. protoc emetterebbe lo stesso FileDescriptorProto sia dall’input sia dall’output. Puoi verificarlo con protoc --descriptor_set_out=before.pb input.proto contro lo stesso comando sul file formattato; i descriptor binari sono identici a parte eventuali variazioni di span nelle source-info (che sono metadati di reflection, non wire format).

E la larghezza dell’indentazione — posso cambiarla da 2 spazi?

L’output è fissato a 2 spazi per livello di parentesi graffa, in linea con la convenzione della guida di stile ufficiale di Protocol Buffers. Se ti servono 4 spazi o tab, passa l’output attraverso sed o la conversione tab del tuo editor. Tenere l’output del formattatore canonico evita la deriva di configurazione tra team.

Gestisce i terminatori di riga CRLF?

Sì — l’input CRLF (\r\n) viene normalizzato a LF (\n) in uscita. Se ti serve CRLF nel file salvato, sarà il tuo editor a ricodificare al salvataggio in base alla sua impostazione di line-ending.

Strumenti correlati

Se stai lavorando con schemi Protobuf, questi vanno bene insieme:

Formattatore Protobuf