Input (.proto-skema)

Output (TypeScript)

Hvad værktøjet gør

Du har et Protocol Buffers-skema og en TypeScript-frontend, der skal tale med en gRPC- eller HTTP-transcoded backend, som serverer disse beskeder. Den officielle codegen-toolchain (protoc med ts-proto eller protobuf-ts) kræver, at du installerer værktøjer, konfigurerer plugins og kobler et build-trin på. Denne konverter klarer det samme i din browser — indsæt, kopiér output, smid det ind i dit projekt.

Type-mapping følger, hvordan håndskrevne typer ser ud i rigtige kodebaser: string/bytes → string/Uint8Array, bool → boolean, de mindre numeriske typer (int32, uint32, float, double) → number, og 64-bit heltalstyperne (int64, uint64, fixed64, sfixed64, sint64) → string for at matche proto3 JSON-mapping-specen. repeated T bliver til T[], map<K, V> bliver til Record<K, V>, indlejrede beskeder bliver til indlejrede interface-deklarationer.

Feltnavne konverteres fra snake_case (Protobuf-konvention) til camelCase (JavaScript/TypeScript-konvention) — det matcher standardadfærden i proto3 JSON-encoderen. Enums bliver til string-literal union-typer (type OrderStatus = 'ORDER_STATUS_UNSPECIFIED' | 'ORDER_STATUS_PENDING' | ...), hvilket er det, de fleste TypeScript-kodebaser faktisk vil have — ingen runtime-overhead fra en enum. Konverteren kører fuldt ud i din browser; intet fra dit skema forlader siden.

Sådan bruger du den

Tre trin. Outputtet er klar til at indsætte i en <code>.ts</code>-fil på få sekunder.

Indsæt dit .proto-skema

Smid skemaet i den venstre editor. syntax = "proto3"; i toppen er fint, men valgfrit. Parseren håndterer indlejrede message-blokke, enum-deklarationer, oneof, map<K, V> og felt-options. Imports bliver genkendt, men sprunget over — indsæt importerede typer inline, hvis du har brug for dem.

Konverteringen af feltnavne er automatisk: order_id i .proto bliver til orderId i TypeScript. Message- og enum-navne forbliver, som de er (allerede PascalCase).

Læs outputtet

Til højre: TypeScript med export interface for hver besked og export type med en string-literal union for hver enum. Indlejrede typer kommer før deres parent, så filen er i deklarationsrækkefølge. Tilføj filen til dit projekt og importér interfacene fra din gRPC-klient eller fetch-handler.

Brug typerne

Kobl interfacene til din fetch- / gRPC-Web- / Connect-RPC-klient. Formen matcher proto3 JSON-kodningen, så JSON-svar parses direkte ind i den typestærke form uden manuel konvertering. Justér int64-håndteringen, hvis din server bruger en non-standard JSON-kodning.

Hvornår det rent faktisk sparer tid

Skitsér typer til en ny gRPC-frontend

Du bygger en ny TS-app oven på en eksisterende gRPC-tjeneste. Du har ikke brug for fuld codegen endnu — bare interface-formerne til at type dine fetch-kald. Indsæt .proto, smid outputtet i types.ts, så er du typet.

Gennemgå en Protobuf-API-ændring

En backend-kollega tilføjede felter til en besked. Du vil se, hvordan det påvirker frontend-typerne uden at køre builden. Indsæt det nye .proto, diff TypeScript-outputtet mod dine nuværende typer, og efterlad en målrettet review-kommentar.

Krydstjek genererede typer

Din build bruger protobuf-ts eller ts-proto, som producerer typer med deres egne konventioner. Indsæt skemaet her for at få en ren reference på, hvordan rene TS-interfaces ser ud — nyttigt til dokumentation eller migrationsplanlægning.

Engangs-scripts og enkeltstående integrationer

Du skriver et hurtigt Node-script, der POSTer JSON til en gRPC-gateway. At sætte den fulde Protobuf-toolchain op for 30 linjer er overkill. Tag interfacene herfra, og du har typesikkerhed uden ceremoni.

Almindelige spørgsmål

Bliver mit skema sendt nogen steder hen?

Nej. Parseren og TS-emitteren kører fuldt ud i din browser som JavaScript. Åbn DevTools og kig i Network-fanen, mens du indsætter — nul requests. Praktisk, når dit skema indeholder interne typenavne, package-stier eller noget, du ikke ville sende til en tredjepartstjeneste.

Hvorfor er int64-felter typet som string?

JavaScript Numbers er IEEE-754-doubles, som mister præcision over 2^53. Den officielle proto3 JSON-mapping kræver, at int64, uint64, fixed64, sfixed64 og sint64 kodes som JSON-strenge. Derfor bruger TS-interfacet string for dem — det matcher det, din server faktisk sender. Hvis du hellere vil have bigint, så lav find-replace i outputtet.

Hvorfor er enums string-unions i stedet for TS-enums?

De fleste TypeScript-projekter foretrækker i dag string-literal unions frem for TS-enums — ingen runtime-omkostning, bedre tree-shaking, og de matcher proto3 JSON-kodningen (som serialiserer enums som deres strengnavn). Vil du have en const enum eller en numerisk enum, er konverteringen fra unionen mekanisk.

Hvordan håndterer den map<K, V>?

Renderes som Record<K, V>. Protobuf-maps med ikke-string-nøgler (f.eks. map<int32, string>) bliver til Record<number, string>. JSON har kun strengnøgler, så ved runtime bliver nøglerne strenge, selvom proto siger int — det er en finurlighed ved proto3 JSON-specen, ikke ved konverteren.

Bliver felter markeret som valgfrie?

Nej. proto3-felter er altid til stede i JSON-outputtet (med default-værdier — tom streng, 0, false, [], {}), så TypeScript-interfacet markerer hvert felt som påkrævet. Hvis du virkelig vil have valgfrie felter (fordi din runtime kan udelade dem), så tilføj ? manuelt efter hvert feltnavn.

Håndterer den oneof?

Hvert felt i en oneof emitteres som et almindeligt interface-felt. Outputtet håndhæver ikke "præcis én"-begrænsningen, som oneof antyder — til det ville du have brug for en diskrimineret union, hvilket afhænger af din runtimes semantik. Redigér outputtet i hånden, hvis du har brug for strammere typer.

Relaterede værktøjer

Hvis du arbejder med Protobuf, JSON og TypeScript, så passer disse godt sammen:

Protobuf til TypeScript-konverter