gRPC-Go: gRPC Go Framework for Go Microservices

What is gRPC-Go

gRPC-Go is the Go implementation of gRPC, an RPC framework built with mobile clients and HTTP/2 as priorities from the start. It ships as the `google.golang.org/grpc` package, generates Go code from `.proto` service definitions, and runs calls over HTTP/2 instead of plain HTTP/1.1. The repo also carries `Documentation/` and `examples/` folders.

Core capabilities of gRPC-Go

• ✓Implements gRPC over HTTP/2, generating Go client and server code straight from .proto service definitions instead of hand-writing request/response plumbing.
• ✓Installs as a plain Go import (`google.golang.org/grpc`) - no separate binary; `go build`/`run`/`test` fetch the dependency automatically via Go modules.
• ✓Ships a `keepalive` package with tunables like `MaxConnectionAgeGrace` (documented in the FAQ) for controlling when the server terminates aging connections.
• ✓Includes a built-in logger you switch to verbose mode with the `GRPC_GO_LOG_VERBOSITY_LEVEL` and `GRPC_GO_LOG_SEVERITY_LEVEL` environment variables.
• ✓Comes with an `examples/` directory and a `Documentation/` folder of low-level technical docs in the repo, on top of the hosted API reference and quick start at grpc.io.
• ✓Links to a public performance benchmark dashboard instead of asking you to take throughput numbers on faith.

When to use gRPC-Go

• •Go services calling other Go services internally, where you want a typed contract compiled from a shared `.proto` definition instead of hand-written JSON handlers.
• •Projects already on Go modules that want RPC as a plain dependency (`go get google.golang.org/grpc`) rather than standing up a separate broker or gateway process.
• •Teams debugging flaky internal connections, since the FAQ ships documented causes and a logging switch (`GRPC_GO_LOG_VERBOSITY_LEVEL`) specifically for diagnosing dropped RPCs.
• •Codebases built or deployed from mainland China or other networks where `golang.org` is blocked - the README documents a `go mod replace` workaround for exactly that case.

Adding gRPC-Go to a Go project

Add the import line `import google.golang.org/grpc` to your Go source, then run `go build`, `go run`, or `go test` - Go's module system fetches google.golang.org/grpc and its dependencies automatically. The README lists one prerequisite: any one of the two latest major Go releases. If the golang.org domain is blocked on your network (the README specifically calls out access from China), replace the import path with a `go mod edit -replace=google.golang.org/grpc=github.com/grpc/grpc-go@latest` line, then run `go mod tidy` and `go mod vendor` to pull the code from GitHub instead of golang.org.

Defining and running a gRPC service in Go

Short version: the walkthrough isn't in this file. The README points you to the Go quick start at grpc.io/docs/languages/go/quickstart and the API reference on pkg.go.dev/google.golang.org/grpc for actual code. What you get in this repo instead is a `Documentation/` folder of low-level technical docs and an `examples/` directory, not an inline tutorial. If your service already throws 'transport is closing' or a similar error during development, the FAQ documents that as a symptom of misconfigured transport credentials, a proxy interfering with the connection, a server-side shutdown, or aggressive keepalive settings - turn on logging with GRPC_GO_LOG_VERBOSITY_LEVEL=99 and GRPC_GO_LOG_SEVERITY_LEVEL=info on both sides to see which applies.

Alternatives to gRPC-Go for Go projects

Frequently asked questions

The problem it solves

Two Go services that need to talk to each other usually end up either hand-rolling a JSON-over-HTTP client/server pair with no shared contract, or reaching for a heavier general-purpose message bus when all they actually need is a typed function call across a network boundary. gRPC-Go solves that specific gap: define the contract once in a `.proto` file, generate matching Go client and server code, and get HTTP/2 transport without writing that layer by hand.

Who should try it — and who should skip

Go teams building internal microservices, who control both client and server, want a typed contract via Protocol Buffers, and care about low-latency internal calls should try it. Skip it if you're exposing a public API to third-party consumers who expect plain JSON/REST, if your team doesn't want a protoc code-generation step in the build, or if you're on a network where golang.org is blocked and you're not willing to set up the go mod replace workaround.

Related repositories