gRPC Golang (gRPC-Go)
Overview
Comprehensive guide for designing and implementing production-grade gRPC services in Go. Covers contract standardization with Buf, transport layer security via mTLS, and deep observability with OpenTelemetry interceptors.
Use this skill when
- Designing microservices communication with gRPC in Go.
- Building high-performance internal APIs using Protobuf.
- Implementing streaming workloads (unidirectional or bidirectional).
- Standardizing API contracts using Protobuf and Buf.
- Configuring mTLS for service-to-service authentication.
Do not use this skill when
- Building pure REST/HTTP public APIs without gRPC requirements.
- Modifying legacy
.proto files without the ability to introduce a new API version (e.g., api.v2) or ensure backward compatibility.
- Managing service mesh traffic routing (e.g., Istio/Linkerd), which is outside the application code scope.
Step-by-Step Guide
- Confirm Technical Context: Identify Go version, gRPC-Go version, and whether the project uses Buf or raw protoc.
- Confirm Requirements: Identify mTLS needs, load patterns (unary/streaming), SLOs, and message size limits.
- Plan Schema: Define package versioning (e.g.,
api.v1), resource types, and error mapping.
- Security Design: Implement mTLS for service-to-service authentication.
- Observability: Configure interceptors for tracing, metrics, and structured logging.
- Verification: Always run
buf lint and breaking change checks before finalizing code generation.
Refer to resources/implementation-playbook.md for detailed patterns, code examples, and anti-patterns.
Examples
Example 1: Defining a Service & Message (v1 API)
syntax = "proto3";
package api.v1;
option go_package = "github.com/org/repo/gen/api/v1;apiv1";
service UserService {
rpc GetUser(GetUserRequest) returns (GetUserResponse);
}
message User {
string id = 1;
string name = 2;
}
message GetUserRequest {
string id = 1;
}
message GetUserResponse {
User user = 1;
}
Best Practices
- ✅ Do: Use Buf to standardize your toolchain and linting with
buf.yaml and buf.gen.yaml.
- ✅ Do: Always use semantic versioning in package paths (e.g.,
package api.v1).
- ✅ Do: Enforce mTLS for all internal service-to-service communication.
- ✅ Do: Handle
ctx.Done() in all streaming handlers to prevent resource leaks.
- ✅ Do: Map domain errors to standard gRPC status codes (e.g.,
codes.NotFound).
- ❌ Don't: Return raw internal error strings or stack traces to gRPC clients.
- ❌ Don't: Create a new
grpc.ClientConn per request; always reuse connections.
Troubleshooting
- Error: Inconsistent Gen: If the generated code does not match the schema, run
buf generate and verify the go_package option.
- Error: Context Deadline: Check client timeouts and ensure the server is not blocking infinitely in streaming handlers.
- Error: mTLS Handshake: Ensure the CA certificate is correctly added to the
x509.CertPool on both client and server sides.
Limitations
- Does not cover service mesh traffic routing (Istio/Linkerd configuration).
- Does not cover gRPC-Web or browser-based gRPC integration.
- Assumes Go 1.21+ and gRPC-Go v1.60+; older versions may have different APIs (e.g.,
grpc.Dial vs grpc.NewClient).
- Does not cover L7 gRPC-aware load balancer configuration (e.g., Envoy, NGINX).
- Does not address Protobuf schema registry or large-scale schema governance beyond Buf lint.
Resources
Related Skills
- @golang-pro - General Go patterns and performance optimization outside the gRPC layer.
- @go-concurrency-patterns - Advanced goroutine lifecycle management for streaming handlers.
- @api-design-principles - Resource naming and versioning strategy before writing
.proto files.
- @docker-expert - Containerizing gRPC services and configuring TLS cert injection via Docker secrets.
1---2name: grpc-golang3description: "Build production-ready gRPC services in Go with mTLS, streaming, and observability. Use when designing Protobuf contracts with Buf or implementing secure service-to-service transport."4risk: safe5source: self6metadata:7 source: https://skillmd.com/skills/mayurrathi/grpc-golang8---910# gRPC Golang (gRPC-Go)1112## Overview1314Comprehensive guide for designing and implementing production-grade gRPC services in Go. Covers contract standardization with Buf, transport layer security via mTLS, and deep observability with OpenTelemetry interceptors.1516## Use this skill when1718- Designing microservices communication with gRPC in Go.19- Building high-performance internal APIs using Protobuf.20- Implementing streaming workloads (unidirectional or bidirectional).21- Standardizing API contracts using Protobuf and Buf.22- Configuring mTLS for service-to-service authentication.2324## Do not use this skill when2526- Building pure REST/HTTP public APIs without gRPC requirements.27- Modifying legacy `.proto` files without the ability to introduce a new API version (e.g., `api.v2`) or ensure backward compatibility.28- Managing service mesh traffic routing (e.g., Istio/Linkerd), which is outside the application code scope.2930## Step-by-Step Guide31321. **Confirm Technical Context**: Identify Go version, gRPC-Go version, and whether the project uses Buf or raw protoc.332. **Confirm Requirements**: Identify mTLS needs, load patterns (unary/streaming), SLOs, and message size limits.343. **Plan Schema**: Define package versioning (e.g., `api.v1`), resource types, and error mapping.354. **Security Design**: Implement mTLS for service-to-service authentication.365. **Observability**: Configure interceptors for tracing, metrics, and structured logging.376. **Verification**: Always run `buf lint` and breaking change checks before finalizing code generation.3839Refer to `resources/implementation-playbook.md` for detailed patterns, code examples, and anti-patterns.4041## Examples4243### Example 1: Defining a Service & Message (v1 API)4445```proto46syntax = "proto3";47package api.v1;48option go_package = "github.com/org/repo/gen/api/v1;apiv1";4950service UserService {51 rpc GetUser(GetUserRequest) returns (GetUserResponse);52}5354message User {55 string id = 1;56 string name = 2;57}5859message GetUserRequest {60 string id = 1;61}6263message GetUserResponse {64 User user = 1;65}66```6768## Best Practices6970- ✅ **Do:** Use Buf to standardize your toolchain and linting with `buf.yaml` and `buf.gen.yaml`.71- ✅ **Do:** Always use semantic versioning in package paths (e.g., `package api.v1`).72- ✅ **Do:** Enforce mTLS for all internal service-to-service communication.73- ✅ **Do:** Handle `ctx.Done()` in all streaming handlers to prevent resource leaks.74- ✅ **Do:** Map domain errors to standard gRPC status codes (e.g., `codes.NotFound`).75- ❌ **Don't:** Return raw internal error strings or stack traces to gRPC clients.76- ❌ **Don't:** Create a new `grpc.ClientConn` per request; always reuse connections.7778## Troubleshooting7980- **Error: Inconsistent Gen**: If the generated code does not match the schema, run `buf generate` and verify the `go_package` option.81- **Error: Context Deadline**: Check client timeouts and ensure the server is not blocking infinitely in streaming handlers.82- **Error: mTLS Handshake**: Ensure the CA certificate is correctly added to the `x509.CertPool` on both client and server sides.8384## Limitations8586- Does not cover service mesh traffic routing (Istio/Linkerd configuration).87- Does not cover gRPC-Web or browser-based gRPC integration.88- Assumes Go 1.21+ and gRPC-Go v1.60+; older versions may have different APIs (e.g., `grpc.Dial` vs `grpc.NewClient`).89- Does not cover L7 gRPC-aware load balancer configuration (e.g., Envoy, NGINX).90- Does not address Protobuf schema registry or large-scale schema governance beyond Buf lint.9192## Resources9394- `resources/implementation-playbook.md` for detailed patterns, code examples, and anti-patterns.95- [Google API Design Guide](https://cloud.google.com/apis/design)96- [Buf Docs](https://buf.build/docs)97- [gRPC-Go Docs](https://grpc.io/docs/languages/go/)98- [OpenTelemetry Go Instrumentation](https://opentelemetry.io/docs/instrumentation/go/)99100## Related Skills101102- @golang-pro - General Go patterns and performance optimization outside the gRPC layer.103- @go-concurrency-patterns - Advanced goroutine lifecycle management for streaming handlers.104- @api-design-principles - Resource naming and versioning strategy before writing `.proto` files.105- @docker-expert - Containerizing gRPC services and configuring TLS cert injection via Docker secrets.