| name | grpc-golang |
| description | 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. |
| type | skill |
| created | 2026-02-27T00:00:00.000Z |
| domain | software-development |
| category | backend |
| risk | safe |
| source | self |
| tags | ["skill","software-development","backend","grpc","golang"] |
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., ).
