Alright, let’s get our hands dirty with .proto files. This is where the magic starts, and where you’ll spend 80% of your time when designing a new gRPC system. Think of a .proto file as the single source of truth, the contract that both your server and all your clients will swear allegiance to. Get this right, and everything else flows smoothly. Get it wrong, and you’ll be living with a bad API decision for years. No pressure.

The first thing you do, before you even define a single message, is declare your proto3 version and your package. This isn’t just a formality; it’s your first line of defense against naming collisions.

syntax = "proto3";
package my.awesome.package;
option go_package = "github.com/yourname/yourrepo/awesomepb";

The syntax line is non-negotiable. Always proto3. The package directive is for protobuf namespace organization. The option go_package is arguably more important for us Go developers; it defines the full Go import path that the generated code will live in. This is what your import statement in your .go files will reference. Forget to set this, and the protoc compiler will yell at you, and rightly so.

Your First Message: It’s Just Data, Seriously

Messages are the nouns of your system. They are the structured data you send and receive. Defining them is straightforward, but the semantics of the field numbers are where most newcomers faceplant.

message CreateUserRequest {
  string username = 1;
  string email = 2;
  uint32 age = 3;
  bool is_subscribed = 4;
}

See those numbers? = 1, = 2, etc.? They are not default values. I repeat, they are not default values. They are permanent, immutable identifiers for that field in the binary encoded message. This is why Protobuf is so backward- and forward-compatible. The encoded data is basically a list of these numbers and their values. The names are for us humans; the numbers are for the wire.

The rules are simple, but critical:

  1. Never, ever change a field number for an existing field. Changing string email = 2; to string email = 999; is a breaking change. Don’t do it.
  2. You can add new fields. Just use a new number that has never been used before in that message.
  3. You can mark old fields as reserved. This prevents anyone from accidentally reusing that field number or name in the future, which could cause catastrophic data corruption.
// What we might do in the future
message CreateUserRequest {
  reserved 4; // reserved 'is_subscribed'
  reserved 10 to 20; // reserve a range of numbers
  string username = 1;
  string email = 2;
  uint32 age = 3;
  // ... new fields get new numbers
  string display_name = 21;
}

Defining a Service: The Verbs

This is where you define what your service can actually do. A service is just a collection of RPC methods. Each method has a request message and a response message. It’s that simple.

service UserService {
  rpc CreateUser (CreateUserRequest) returns (CreateUserResponse) {};
  rpc GetUser (GetUserRequest) returns (User) {};
}

But here’s the first “questionable choice” you’ll encounter. Notice how each RPC is defined with a single request and a single response? This is brilliant in its simplicity but can feel limiting. What if you want to stream data? You have to be explicit about it.

gRPC gives you four flavors of RPC:

  1. Unary: What we have above. One request, one response.

  2. Server Streaming: One request, a stream of responses. Perfect for sending back a large, chunkable dataset.

    rpc ListUsers (ListUsersRequest) returns (stream User) {};

  3. Client Streaming: A stream of requests, one response. Great for uploading large amounts of data that the server processes as a batch.

    rpc UploadUserProfilePhotos (stream PhotoChunk) returns (UploadStatus) {};

  4. Bidirectional Streaming: A stream of requests and a stream of responses. The two streams are independent. This is your WebSocket killer, perfect for real-time chat or games.

    rpc HaveAConversation (stream ChatMessage) returns (stream ChatMessage) {};

You must choose the right type from the start. Changing a unary method to a streaming one is a breaking change on par with changing a field number. Plan ahead.

Importing and Using Other Types

You don’t live in a vacuum. You’ll want to use well-known types like google.protobuf.Timestamp instead of rolling your own time format. This is where imports save you.

syntax = "proto3";
package my.awesome.package;
import "google/protobuf/timestamp.proto"; // Import the definition
option go_package = "github.com/yourname/yourrepo/awesomepb";

message User {
  string id = 1;
  string name = 2;
  google.protobuf.Timestamp created_at = 3; // Use the fully qualified name
}

When you run protoc later, you’ll need to point it to the directory containing these imported .proto files (usually by including the protoc-gen-go and googleapis common modules). It’s a bit of a fuss the first time you set it up, but it’s worth it for the sanity of using a standard, well-defined timestamp across your entire stack.

Naming and Style Conventions

This is where I get opinionated. The Protobuf spec doesn’t care. It will compile snake_case, camelCase, or PascalCase field names without complaint. However, the official Style Guide recommends using underscore_separated_names for message fields. Just do it. It looks cleaner, and when the protoc compiler generates your Go code, it will automatically convert field_name to FieldName (PascalCase) for exported struct fields. It’s one less thing to think about.

So there you have it. The .proto file is your blueprint. Be meticulous with your field numbers, deliberate with your RPC types, and consistent with your style. A well-designed proto contract is a thing of beauty that makes everything that comes after it—the code generation, the server implementation, the client calls—feel almost effortless. Almost.