Wejście (JSON)

Wyjście (schemat .proto)

Co robi to narzędzie

Masz prawdziwy payload JSON — przykładową odpowiedź API, body z webhooka, wiersz z bazy NoSQL — i chcesz to opisać jako wiadomość Protocol Buffers? Pisanie schematu ręcznie jest powolne i łatwo o pomyłkę, zwłaszcza przy zagnieżdżonych obiektach i tablicach. Ten konwerter przechodzi przez JSON, wnioskuje typy Protobuf dla każdego pola i wypluwa czysty schemat proto3, który możesz od razu wkleić do projektu.

Wnioskowanie typów idzie tak, jak sam byś to napisał: string dla stringów, bool dla booli, int32 dla liczb całkowitych mieszczących się w 32 bitach, int64 dla reszty, double dla liczb niecałkowitych, repeated <T> dla tablic z jednorodnym typem elementu (jedna zagnieżdżona wiadomość ponownie używana dla tablic obiektów) i zagnieżdżone bloki message dla zagnieżdżonych obiektów. JSON nie odróżnia struktury od mapy, więc wszystkie obiekty wychodzą jako zagnieżdżone wiadomości — zamień ręcznie na map<K, V>, jeśli twoje dane to faktycznie mapa.

Nazwy pól są konwertowane z camelCase lub kebab-case na konwencjonalny w Protobufie snake_case. Numery pól są przydzielane 1, 2, 3, … w kolejności deklaracji. Wynik to poprawny proto3 — wklej go do pliku .proto, odpal protoc albo buf i masz wygenerowany kod w wybranym języku. Konwersja działa w całości w twojej przeglądarce — żaden JSON, żadne nazwy pól ani wartości nie są nigdzie wysyłane.

Jak tego używać

Trzy kroki. Działa z każdym poprawnie sformułowanym obiektem JSON — odpowiedziami API, wpisami logu, plikami z fixture’ami, czymkolwiek.

Wklej swój JSON

Wrzuć JSON do lewego edytora. Korzeń musi być obiektem ({ ... }) — jeśli twoje dane mają korzeń w postaci tablicy, najpierw owiń je w obiekt, np. { "items": [...] }. Używaj realnych danych: im bardziej reprezentatywna próbka, tym lepiej wywnioskowane typy będą pasowały do tego, co naprawdę chcesz na dłuższą metę.

Jeśli twój JSON ma niecytowane klucze, końcowe przecinki albo inne dziwactwa, najpierw przepuść go przez JSON Fixer — Protobuf chce czystego obiektu do pracy.

Naciśnij Konwertuj

Kliknij zielony przycisk Konwertuj. Konwerter przechodzi przez każdy klucz w JSON-ie, wybiera typ Protobuf, buduje zagnieżdżone bloki message dla zagnieżdżonych obiektów i emituje schemat z syntax = "proto3"; u góry. Numery pól są przydzielane w kolejności źródłowej.

Użyj .proto

Skopiuj schemat do pliku .proto w swoim repo. Przejrzyj wywnioskowane typy — przy polach, gdzie próbka JSON była pusta (pusta tablica, null), zobaczysz komentarz oznaczający, że typ został zgadnięty. Dostosuj, co trzeba, a potem odpal protoc albo buf generate, żeby wygenerować kod w swoim języku.

Kiedy to naprawdę oszczędza czas

Modelowanie zewnętrznego API jako Protobuf

Dostawca zwraca JSON. Twoja usługa trzyma Protobuf. Weź prawdziwą odpowiedź, wklej ją tutaj, dostań startowy schemat dla tego typu, potem dopracuj. Lepsze niż czytanie dokumentacji i klepanie 50 pól ręcznie.

Migracja usługi opartej na JSON do gRPC

Przenosisz mikroserwis HTTP+JSON do gRPC. Każdy kształt żądania i odpowiedzi potrzebuje .proto. Skonwertuj każdy złapany payload do schematu Protobuf, wklej je w jeden plik i masz szkic kontraktu.

Bootstrap modułu Buf

Stawiasz nowy moduł Buf i potrzebujesz realnych schematów na start? Skonwertuj swoje istniejące fixture’y JSON i użyj wyniku jako zalążka dla swoich plików .proto — dużo szybciej niż klepać je od zera.

Pisanie fixture’ów testowych dla kodu Protobuf

Twój zespół ma dane testowe w JSON. Nowy kod konsumuje Protobuf. Wygeneruj <code>.proto</code> z JSON-a, niech codegen zbuduje typy — fixture’y i kod zostają zsynchronizowane.

Częste pytania

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

Nie. Konwerter działa w całości w twojej przeglądarce jako JavaScript. Twój JSON — klucze, wartości, cokolwiek wrażliwego — nigdy nie opuszcza twojej maszyny. Otwórz DevTools i obserwuj zakładkę Network, klikając Konwertuj. Zero żądań.

Jak wybiera między int32, int64 a double?

Dla wartości całkowitych sprawdza, czy wartość mieści się w 32-bitowym zakresie ze znakiem (-2^31 do 2^31-1). Jeśli tak — int32. Jeśli nie — int64. Liczby niecałkowite zawsze trafiają do double. Jeśli wiesz, że twoje dane są bez znaku, albo chcesz konkretnej szerokości jak fixed32, edytuj wynik — pełny zestaw dostępnych typów liczbowych i ich kompromisów na warstwie wire znajdziesz w tabeli typów skalarnych.

Kiedy obiekt staje się mapą, a kiedy zagnieżdżoną wiadomością?

Zawsze zagnieżdżoną wiadomością — nigdy mapą. JSON nie odróżnia struktury od mapy, więc zgadywanie jednego albo drugiego myli się mniej więcej w połowie przypadków. Jeśli twoje dane to faktycznie mapa klucz-wartość (np. metadane, nagłówki, feature flagi), otwórz wynik i ręcznie zamień message Foo { ... } na map<string, V> foo = N;. Poprawka jest mechaniczna i oczywista, gdy spojrzysz na dane.

A null i puste tablice?

Oba dają w wyniku komentarz mówiący, że typ został zgadnięty na podstawie zdegenerowanej próbki. null domyślnie ustawia się na string z notatką "nullable". Puste tablice domyślnie ustawiają się na repeated string z notatką "empty array". Zamień te typy na to, czego rzeczywiście oczekujesz.

Dlaczego tablice mieszanych typów wychodzą jako repeated string?

Protobuf nie wspiera heterogenicznych list bezpośrednio. Jeśli twoja tablica JSON ma mieszane typy (część stringi, część liczby), nie ma czystego odpowiednika w Protobufie — potrzebujesz google.protobuf.Value, oneof albo refaktoru kształtu danych. Konwerter zaznacza to komentarzem, żebyś sam zdecydował.

Czy radzi sobie z głęboko zagnieżdżonym JSON-em?

Tak. Każdy zagnieżdżony obiekt staje się zagnieżdżoną message z nazwą wyprowadzoną w PascalCase. Głębokość zagnieżdżenia jest ograniczona tylko głębokością stosu, a nie konwerterem — nawet mocno zagnieżdżone odpowiedzi API konwertują się czysto.

Czy mogę robić round-trip JSON ↔ Protobuf tymi dwoma narzędziami?

W większości tak. JSON do Protobuf daje schemat; Protobuf do JSON daje próbkę. Kształty zgadzają się dla pól, w których próbka JSON miała reprezentatywną wartość. Tam, gdzie JSON miał null albo puste tablice, wywnioskowany typ Protobuf jest zgadywany i round-trip będzie dokładny dopiero po poprawieniu typu.

Powiązane narzędzia

Jeśli przerabiasz JSON i schematy, te dobrze ze sobą grają:

Konwerter JSON do Protobuf