AgentSkillsCN

protobuf-go-ts-schema-exchange

以 Schema 优先的工作流，通过 JSON 传输、Buf codegen、protojson 以及 @bufbuild/protobuf，在 Go 与 TypeScript 之间共享由 protobuf 定义的负载。当您创建 proto schema、生成 Go/TS 代码、发出 JSON 负载、使用 fromJson 进行解码、处理 int64/Struct，或对端到端负载进行校验时，可选用此技能。

SKILL.md
--- frontmatter
name: protobuf-go-ts-schema-exchange
description: "Schema-first workflow for sharing protobuf-defined payloads between Go and TypeScript with JSON transport, Buf codegen, protojson, and @bufbuild/protobuf. Use when creating proto schemas, generating Go/TS code, emitting JSON payloads, decoding with fromJson, handling int64/Struct, or validating end-to-end payloads."

Protobuf Go/TS Schema Exchange

Quick start

  • •Define a protobuf schema with a schema_version field and stable package name.
  • •Configure Buf v2 with remote: plugins and generate Go + TS outputs.
  • •Emit JSON in Go using protojson (camelCase field names).
  • •Decode JSON in TS using fromJson and validate int64 and Struct behaviors.

Workflow

  1. •Author the protobuf schema (see references/templates.md).
  2. •Configure Buf v2 generation for Go + TS (see references/templates.md).
  3. •Generate outputs with buf generate.
  4. •Emit JSON in Go with protojson and a SEM-style envelope.
  5. •Decode in TS with fromJson and validate BigInt/Struct handling.
  6. •Run the validation checklist (see references/validation.md).

Pitfalls to avoid

  • •Use Buf v2 remote: plugin syntax in buf.gen.yaml.
  • •Match protoc-gen-es v2 with @bufbuild/protobuf v2.
  • •Expect int64 in JSON to be strings; fromJson yields bigint.
  • •google.protobuf.Struct becomes a JsonObject in TS, not a Struct message.
  • •With paths=source_relative, generated outputs keep the proto/ prefix; align go_package accordingly.

References

  • •references/templates.md
  • •references/validation.md