Production Protobuf

Real-world protobuf usage:

Schema management:

• Single source of truth: .proto files in a shared repo.
• Buf Schema Registry, Confluent Schema Registry: hosted.
• Versioning: tag-based (commit hash) or explicit versions.

Build pipelines:

• Pre-commit regen.
• CI breaks if generated code missing or stale.
• Buf lint + breaking: enforce style + compatibility.

Naming conventions:

• Field names snake_case.
• Message names CamelCase.
• Service names CamelCase.
• Don't use reserved words.

Common pitfalls:

• Tag reuse: catastrophic. If you removed field 5 (int32 age) and added field 5 (string email), old binaries decode email's bytes as age = wrong number.
• Default values: proto3 dropped explicit "missing" detection. To distinguish "not set" from "0", use wrappers (google.protobuf.Int32Value).
• Map ordering: not preserved. Sort if you need deterministic.
• Large messages: protobuf limit 2 GB; default parse limit 64 MB. Stream chunks instead.

Performance:

• Encoding ~5x faster than JSON.
• Decoding ~10x faster.
• 3-10x smaller wire size.
• BUT: setup cost (schema sharing, code gen).

Schema design:

• Plan for evolution: leave space in tag numbers (1-15 for hot fields).
• Avoid required (proto2). Even in proto2.
• Use enums for stable categories.
• Use oneof for mutually-exclusive variants.
• Use Timestamp / Duration well-known types.

Common message patterns:

• Pagination: page_token + page_size.
• Sparse field updates: FieldMask.
• Batch operations: repeated request/response.
• Long-running operations: Operation message + polling.

Avoid:

• Embedding huge blobs (use separate storage + URL).
• Recursive messages with no depth limit (DOS).
• Public APIs without schema versioning.

Tools to know:

• protoc: official compiler.
• buf: modern toolchain.
• prototool (deprecated, replaced by buf).
• grpcurl: like curl for gRPC.
• bloomrpc / kreya: GUI clients.

Don't hand-roll wire format. Use generated code.