Generating Go Code

You do not write the Go types for a protobuf message by hand. A compiler writes them for you. That compiler is protoc, and on its own it knows nothing about Go: it parses .proto files and hands the result to a plugin, which is a separate program that emits code for one language.

The two plugins

Go needs two. protoc-gen-go writes user.pb.go, holding the structs and their getters. protoc-gen-go-grpc writes user_grpc.pb.go, holding the client stub (a Go type whose methods make network calls) and the server interface you implement. You ask for them with --go_out and --go-grpc_out. protoc locates a plugin by name alone: --go_out looks for a program called protoc-gen-go on your PATH.

Where the files land

Add paths=source_relative to each plugin and every generated file is written next to the .proto file it came from. Without it, protoc rebuilds the directory tree from the go_package import path, which is almost never what you want in a single module.

Commit the output

Check the generated files into version control. A fresh clone then builds with go build and no protoc installed, review can see exactly what changed when a message changed, and continuous integration needs no extra toolchain. Record the command in a //go:generate comment, which is the short way of writing the long protoc line once and then typing go generate ./.... Since Go 1.24 you can also pin the plugins in go.mod with go get -tool and run them as go tool protoc-gen-go, rather than trusting whatever an earlier go install left in your PATH.

package main

import (
	"fmt"

	"google.golang.org/protobuf/types/known/wrapperspb"
)

func main() {
	// Generated code carries a descriptor: the .proto definition, compiled in.
	// Int32Value was generated from wrappers.proto by protoc-gen-go, exactly
	// the way your own messages are.
	md := (&wrapperspb.Int32Value{}).ProtoReflect().Descriptor()
	fmt.Println("message:", md.FullName())

	fields := md.Fields()
	for i := range fields.Len() { // range over an int: Go 1.22 and later
		f := fields.Get(i)
		fmt.Printf("field %d: %s (%s)\n", f.Number(), f.Name(), f.Kind())
	}
}

// Output:
// message: google.protobuf.Int32Value
// field 1: value (int32)

# Record both plugins in go.mod (Go 1.24 and later) so every machine
# and CI job uses the same versions.
go get -tool google.golang.org/protobuf/cmd/protoc-gen-go@latest
go get -tool google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest

# protoc needs the plugins as programs on PATH, so put them in ./bin.
GOBIN=$PWD/bin go install tool

PATH=$PWD/bin:$PATH protoc \
	--go_out=. --go_opt=paths=source_relative \
	--go-grpc_out=. --go-grpc_opt=paths=source_relative \
	api/user/v1/user.proto

// Package api holds the generated protobuf and gRPC code for this service.
//
// After editing any .proto file, run: go generate ./...
package api

//go:generate protoc --go_out=. --go_opt=paths=source_relative --go-grpc_out=. --go-grpc_opt=paths=source_relative user/v1/user.proto

// user_grpc.pb.go, written by protoc-gen-go-grpc. Do not edit.

// The client stub: one method per rpc, each one a network call.
type UserServiceClient interface {
	GetUser(ctx context.Context, in *GetUserRequest, opts ...grpc.CallOption) (*User, error)
}

// The server side: the interface your own type must satisfy.
type UserServiceServer interface {
	GetUser(context.Context, *GetUserRequest) (*User, error)
	mustEmbedUnimplementedUserServiceServer()
}

// Embedding this struct supplies that unexported method, and a default
// implementation of every rpc you have not written yet.
type UnimplementedUserServiceServer struct{}