Wejście (schemat .proto)

Wyjście (TypeScript)

Co robi to narzędzie

Masz schemat Protocol Buffers i frontend w TypeScript, który musi gadać z backendem gRPC lub transcodowanym po HTTP, serwującym te wiadomości. Oficjalny toolchain codegen (protoc z ts-proto lub protobuf-ts) wymaga instalacji narzędzi, konfiguracji pluginów i podpięcia kroku build. Ten konwerter robi to samo w przeglądarce — wklej, skopiuj wyjście, wrzuć do projektu.

Mapowanie typów odzwierciedla to, jak ręcznie pisane typy wyglądają w prawdziwych kodach: string/bytes → string/Uint8Array, bool → boolean, mniejsze typy numeryczne (int32, uint32, float, double) → number, oraz typy 64-bitowych intów (int64, uint64, fixed64, sfixed64, sint64) → string, żeby pasowało do specyfikacji mapowania JSON proto3. repeated T staje się T[], map<K, V> staje się Record<K, V>, zagnieżdżone wiadomości stają się zagnieżdżonymi deklaracjami interface.

Nazwy pól są konwertowane z snake_case (konwencja Protobuf) do camelCase (konwencja JavaScript/TypeScript) — zgodnie z domyślnym zachowaniem enkodera JSON proto3. Enumy stają się typami union literałów łańcuchowych (type OrderStatus = 'ORDER_STATUS_UNSPECIFIED' | 'ORDER_STATUS_PENDING' | ...), czego większość kodów TypeScript naprawdę chce — bez narzutu w runtime jaki ma enum. Konwerter działa w całości w Twojej przeglądarce; nic ze schematu nie opuszcza strony.

Jak go używać

Trzy kroki. Wyjście jest gotowe do wklejenia w plik <code>.ts</code> w kilka sekund.

Wklej swój schemat .proto

Wrzuć schemat do lewego edytora. syntax = "proto3"; na górze jest OK, ale opcjonalne. Parser obsługuje zagnieżdżone bloki message, deklaracje enum, oneof, map<K, V> i opcje pól. Importy są rozpoznawane, ale pomijane — wklej importowane typy inline, jeśli są potrzebne.

Konwersja nazw pól dzieje się automatycznie: order_id w .proto staje się orderId w TypeScript. Nazwy wiadomości i enumów zostają jak są (już w PascalCase).

Przeczytaj wyjście

Po prawej: TypeScript z export interface dla każdej wiadomości i export type z unionem literałów łańcuchowych dla każdego enuma. Typy zagnieżdżone idą przed swoim rodzicem, więc plik jest w kolejności deklaracji. Dodaj plik do projektu i zaimportuj interfejsy z klienta gRPC lub handlera fetch.

Użyj typów

Podłącz interfejsy do swojego klienta fetch / gRPC-Web / Connect-RPC. Kształt pasuje do kodowania JSON proto3, więc odpowiedzi JSON parsują się prosto do typowanego kształtu bez ręcznej konwersji. Dostosuj obsługę int64, jeśli serwer używa niestandardowego kodowania JSON.

Kiedy to naprawdę oszczędza czas

Szkicowanie typów dla nowego frontu gRPC

Budujesz nową aplikację TS na istniejącym serwisie gRPC. Pełny codegen jeszcze nie jest potrzebny — tylko kształty interfejsów do otypowania wywołań fetch. Wklej .proto, wrzuć wyjście do types.ts, masz typy.

Przegląd zmiany w API Protobuf

Kolega z backendu dodał pola do wiadomości. Chcesz zobaczyć, jak to wpływa na typy frontu, bez odpalania builda. Wklej nowy .proto, zrób diff wyjścia TypeScript z bieżącymi typami, zostaw konkretny komentarz w review.

Krzyżowe sprawdzanie generowanych typów

Twój build używa protobuf-ts albo ts-proto, które generują typy z własnymi konwencjami. Wklej tu schemat, żeby mieć czystą referencję jak wyglądają zwykłe interfejsy TS — przydatne do dokumentacji albo planowania migracji.

Skrypty jednorazowe i doraźne integracje

Piszesz szybki skrypt Node, który POST-uje JSON do gRPC-gateway. Stawianie pełnego toolchaina Protobuf dla 30-liniowego skryptu to przesada. Weź interfejsy stąd i masz bezpieczeństwo typów bez ceremoniału.

Częste pytania

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

Nie. Parser i emitter TS działają w całości w przeglądarce jako JavaScript. Otwórz DevTools i obserwuj zakładkę Network podczas wklejania — zero żądań. Przydatne, gdy schemat zawiera wewnętrzne nazwy typów, ścieżki pakietów lub cokolwiek, czego nie chciałbyś wysyłać do serwisu zewnętrznego.

Dlaczego pola int64 są typowane jako string?

JavaScriptowe Number to double IEEE-754, które tracą precyzję powyżej 2^53. Oficjalne mapowanie JSON proto3 wymaga, żeby int64, uint64, fixed64, sfixed64 i sint64 były kodowane jako stringi JSON. Stąd interfejs TS używa dla nich string — pasuje to do tego, co serwer faktycznie wysyła. Jeśli wolisz bigint, zrób find-replace na wyjściu.

Czemu enumy to uniony stringów, a nie enumy TS?

Większość projektów TypeScript dziś preferuje uniony literałów łańcuchowych zamiast enumów TS — brak kosztu w runtime, lepszy tree-shaking, i pasują do kodowania JSON proto3 (które serializuje enumy ich nazwą string). Jeśli potrzebujesz const enuma albo enuma numerycznego, konwersja z uniona jest mechaniczna.

Jak obsługuje map<K, V>?

Renderuje jako Record<K, V>. Mapy Protobuf z kluczami innymi niż string (np. map<int32, string>) stają się Record<number, string>. JSON ma tylko klucze stringowe, więc w runtime klucze będą stringami nawet, gdy proto mówi int — to dziwactwo specyfikacji JSON proto3, nie konwertera.

Czy pola są oznaczane jako opcjonalne?

Nie. Pola proto3 są zawsze obecne w wyjściu JSON (z domyślnymi wartościami — pusty string, 0, false, [], {}), więc interfejs TypeScript oznacza każde pole jako wymagane. Jeśli naprawdę chcesz pól opcjonalnych (bo Twój runtime może je pominąć), dopisz ? ręcznie po nazwie każdego pola.

Czy obsługuje oneof?

Każde pole oneof jest emitowane jako zwykłe pole interfejsu. Wyjście nie wymusza ograniczenia "dokładnie jedno", które niesie oneof — do tego potrzebny byłby union dyskryminowany, a to zależy od semantyki Twojego runtime. Jeśli potrzebujesz ściślejszych typów, edytuj wyjście ręcznie.

Powiązane narzędzia

Jeśli pracujesz z Protobuf, JSON i TypeScript, te dobrze ze sobą grają:

Konwerter Protobuf do TypeScript