Wejście (schemat .proto)

Wyjście (sformatowany .proto)

Co robi to narzędzie

Wklejasz schemat Protocol Buffers z mieszanymi wcięciami, posklejanymi deklaracjami pól lub przypadkowymi pustymi liniami z kopiuj-wklej, i chcesz, żeby wyglądał jak reszta repozytorium. Ten formatter przepisze plik z dwuspacjowym wcięciem na każdy poziom klamry, dokładnie jedną spacją wokół =, jedną spacją po , i co najwyżej jedną pustą linią między blokami. Komentarze — i te liniowe //, i blokowe /* ... */ — zostają dokładnie tam, gdzie je postawiłeś.

Nie parsuje ani nie waliduje schematu, więc zadziała na lekko popsutym wejściu, którego buf format albo opcja "Format Document" twojego edytora może nie ruszyć. Jeśli twój .proto ma gdzieś błąd składni, reszta pliku i tak zostanie wokół niego sformatowana. Wada: nie potrafi przestawić pól, znormalizować kolejności importów ani usunąć nieużywanych opcji, jak zrobiłby prawdziwy formatter parserowy. Do tego odpal buf format w pipeline buildu.

Wszystko dzieje się w przeglądarce — żadnego uploadu, żadnego rate limitu, żaden schemat nigdzie nie jedzie. Przydatne, gdy schemat zawiera wewnętrzne nazwy paczek, nazwy typów albo cokolwiek, czego nie chciałbyś wysłać do API trzeciej strony. Działa na każdym rozmiarze, jaki przeglądarka utrzyma w pamięci; nawet dziesiątki tysięcy linii formatuje się w znacznie krótszym czasie niż sekunda.

Jak go używać

Trzy kroki. Wyjście odświeża się około 300 ms po tym, jak przestaniesz pisać.

Wklej swój schemat .proto

Rzuć schemat do lewego edytora. syntax, package, dyrektywy import, bloki message, zagnieżdżone enumy, oneof, map<K, V> — wszystko obsłużone. Mieszane końcówki linii (CRLF) na wyjściu zostają znormalizowane do LF.

Formatter niczego nie przestawia — pola, importy i opcje zostają w kolejności, w jakiej je napisałeś. Jeśli chcesz porządku kanonicznego, później odpal buf format.

Przeczytaj sformatowane wyjście

Po prawej: ten sam schemat, wcięty 2 spacjami na każdy poziom {. Linie zaczynające się od } przed wypisaniem cofają się o jeden poziom. Wiele kolejnych pustych linii zwija się do jednej. Białe znaki na końcu linii są usuwane. Komentarze są zachowane co do litery, łącznie z położeniem względem reszty.

Skorzystaj z wyniku

Skopiuj z powrotem do edytora albo pobierz jako formatted.proto. Z punktu widzenia protoc wyjście jest bajt w bajt równoważne wejściu — zmieniają się tylko białe znaki — więc możesz je wrzucić z powrotem bez obaw o różnice w wire format czy wygenerowanym kodzie. Sprawdź to: odpal protoc --descriptor_set_out=before.pb input.proto i to samo na sformatowanym wyjściu — deskryptory się zgodzą.

Kiedy faktycznie oszczędza czas

Czyszczenie .proto wklejonego z czatu albo dokumentacji

Kolega wkleja kawałek schematu na Slacku, wcięcia są w strzępkach, a ty chcesz to mieć w repo. Wrzuć tutaj, skopiuj sformatowaną wersję, wklej do swojego pliku. Szybciej niż taniec "zaznacz wszystko, retabuluj" w edytorze.

Standaryzacja starych .proto w wiekowym repo

Odziedziczyłeś repo Protobuf, w którym każdy plik ma inne wcięcie. Przepuść każdy plik przez ten formatter, wypchnij to jako jeden commit normalizujący, a potem włącz buf format w CI, żeby tak już zostało.

Szybki rzut oka na wygenerowany .proto

Niektóre generatory kodu (JSON Schema → Protobuf, OpenAPI → Protobuf) wypluwają poprawne, ale brzydkie schematy. Sformatuj wynik, rzuć okiem, zdecyduj, czy zostawić generator, czy poprawić ręcznie.

Kiedy nie możesz zainstalować protoc ani buf

Siedzisz na zamkniętej maszynie, w sieci dla gości albo po prostu robisz review PR-a w przeglądarce. Formatter chodzący wyłącznie w przeglądarce daje ten sam czytelny wynik bez instalacji toolchaina Protocol Buffers.

Częste pytania

Czy mój schemat jest gdzieś wysyłany?

Nie. Formatter działa w całości w twojej przeglądarce jako JavaScript. Nic ze schematu — nazwy message, ścieżki paczek, komentarze — nie opuszcza twojej maszyny. Otwórz DevTools i zerknij na zakładkę Network, kiedy wklejasz; zobaczysz zero requestów.

Czy zachowuje komentarze?

Tak — i komentarze liniowe //, i blokowe /* ... */ zostają dokładnie tam, gdzie je postawiłeś. Komentarze w osobnych liniach trzymają swoją pozycję względem reszty; komentarze w trailing-pozycji na końcu linii pola zostają przyklejone do tego pola. Podejście oparte o linie zostało wybrane właśnie po to, żeby komentarze przeżyły w nienaruszonym stanie.

Czym to się różni od buf format?

buf format parsuje schemat do drzewa składniowego i wypisuje go na nowo. To daje silniejsze gwarancje — kanoniczna kolejność opcji, spójna wielkość liter w enumach itd. — ale wymaga, żeby schemat parsował się czysto. Ten formatter jest liniowy, więc działa na lekko popsutym wejściu, którego buf by nie chciał, i nie wymusza kanonicznej kolejności. Do skończonego kodu odpal buf format. Do schematów w trakcie edycji albo cudzych fragmentów — użyj tego.

Czy zmienia semantykę schematu?

Nie — zmieniają się tylko białe znaki. protoc wyprodukowałby ten sam FileDescriptorProto z wejścia i z wyjścia. Możesz to potwierdzić: odpal protoc --descriptor_set_out=before.pb input.proto na wejściu i to samo na sformatowanym pliku; binarne deskryptory są identyczne, pomijając ewentualne zmiany spanów w source-info (to są metadane refleksji, a nie wire format).

A szerokość wcięcia — mogę zejść z 2 spacji?

Wyjście jest na sztywno ustawione na 2 spacje na poziom klamry, zgodnie z konwencją z oficjalnego style guide’a Protocol Buffers. Jeśli potrzebujesz 4 spacji albo tabów, przepuść wynik przez sed albo zamianę tabów w edytorze. Trzymanie wyjścia formattera w postaci kanonicznej eliminuje rozjazd konfiguracji między zespołami.

Czy obsługuje końcówki linii CRLF?

Tak — wejściowy CRLF (\r\n) na wyjściu jest normalizowany do LF (\n). Jeśli potrzebujesz CRLF w zapisanym pliku, twój edytor i tak przekoduje to przy zapisie zgodnie z własnym ustawieniem końca linii.

Powiązane narzędzia

Jeśli pracujesz ze schematami Protobuf, te dobrze grają razem:

Formatter Protobuf