samber/cc-skills-golang已通過檢查
SKILL DETAIL
golang-grpc
samber/cc-skills-golang/golang-grpc
Provides gRPC usage guidelines, protobuf organization, and production-ready patterns for Golang microservices. Use when implementing, reviewing, or debugging gRPC servers/clients, writing proto files, setting up interceptors, handling gRPC errors with status codes, configuring TLS/mTLS, testing with bufconn, or working with streaming RPCs.
安裝量 · 320查看來源
Installation
npx skills add https://github.com/samber/cc-skills-golang --skill golang-grpc
技能檔案
SKILL.md
最近同步 · 2026年10月10日
evals/evals.json›
[
{
"id": 1,
"name": "raw-error-vs-status-error",
"description": "Tests that gRPC handlers return status.Errorf with specific codes, not raw errors",
"prompt": "Write a Go gRPC handler for GetUser that looks up a user from a repository. If the user is not found, return an appropriate error. If the repository returns an unexpected error, return that too.",
"trap": "Without the skill, the model may return fmt.Errorf or raw errors, which become codes.Unknown. The skill requires status.Errorf with specific codes.",
"assertions": [
{
"id": "1.1",
"text": "Uses status.Errorf (or status.Error) for the not-found case with codes.NotFound"
},
{
"id": "1.2",
"text": "Uses status.Errorf with codes.Internal for unexpected errors"
},
{
"id": "1.3",
"text": "Does NOT return a raw fmt.Errorf or errors.New as the gRPC error"
},
{
"id": "1.4",
"text": "Imports google.golang.org/grpc/status and google.golang.org/grpc/codes"
},
{
"id": "1.5",
"text": "Does NOT leak internal error details in the user-facing gRPC message for Internal errors"
}
]
},
{
"id": 2,
"name": "wrapper-messages-not-bare-types",
"description": "Tests that proto RPCs use Request/Response wrapper messages, not bare types",
"prompt": "Write a proto3 service definition for a product catalog with RPCs: GetProduct (takes product ID, returns product), DeleteProduct (takes product ID, returns nothing), SearchProducts (takes search query string, returns list of products).",
"trap": "Without the skill, the model may use bare types like string or google.protobuf.Empty. The skill requires Request/Response wrappers for backward-compatible evolution.",
"assertions": [
{
"id": "2.1",
"text": "Uses GetProductRequest/GetProductResponse wrapper messages, not bare string or Product"
},
{
"id": "2.2",
"text": "Uses DeleteProductRequest/DeleteProductResponse wrapper messages, not bare string or google.protobuf.Empty"
},
{
"id": "2.3",
"text": "Uses SearchProductsRequest/SearchProductsResponse wrapper messages"
},
{
"id": "2.4",
"text": "Each wrapper message has properly named fields (not just a single unnamed field)"
},
{ "id": "2.5", "text": "Includes go_package option in the proto file" }
]
},
{
"id": 3,
"name": "proto-directory-organization",
"description": "Tests proper proto file organization by domain with versioned directories",
"prompt": "I'm building a microservice with user management and order management. How should I organize my proto files? Show the directory layout and an example buf.gen.yaml.",
"trap": "Without the skill, the model may put all protos in a flat directory or skip versioning. The skill requires domain-based organization with v1 directories.",
"assertions": [
{
"id": "3.1",
"text": "Organizes proto files by domain (user/, order/ or similar domain grouping)"
},
{
"id": "3.2",
"text": "Includes version directories (v1/ under each domain)"
},
{
"id": "3.3",
"text": "Separates message definitions from service definitions (e.g. user.proto vs user_service.proto)"
},
{
"id": "3.4",
"text": "Includes a shared/ or common/ directory for shared messages"
},
{
"id": "3.5",
"text": "Shows buf.gen.yaml with go and go-grpc plugins configured"
}
]
},
{
"id": 4,
"name": "graceful-stop-with-timeout-fallback",
"description": "Tests proper gRPC server shutdown: GracefulStop with timeout fallback to Stop",
"prompt": "Write Go code for a gRPC server that handles shutdown signals properly. The server should try to drain in-flight requests before stopping.",
"trap": "Without the skill, the model may only call srv.Stop() or only srv.GracefulStop() without a timeout fallback. The skill requires GracefulStop with a timeout fallback to Stop.",
"assertions": [
{
"id": "4.1",
"text": "Calls srv.GracefulStop() first to drain in-flight RPCs"
},
{
"id": "4.2",
"text": "Has a timeout mechanism that falls back to srv.Stop() if GracefulStop takes too long"
},
{
"id": "4.3",
"text": "Uses a select statement or timer for the timeout"
},
{
"id": "4.4",
"text": "Listens for OS signals (SIGINT, SIGTERM or os.Interrupt)"
},
{ "id": "4.5", "text": "The timeout is reasonable (5-30 seconds)" }
]
},
{
"id": 5,
"name": "health-check-service-registration",
"description": "Tests that gRPC servers register the health check service for Kubernetes readiness probes",
"prompt": "Write a production-ready gRPC server setup in Go. Register a UserService and make it deployable to Kubernetes.",
"trap": "Without the skill, the model may not register the health check service. The skill says health check is required for Kubernetes probes.",
"assertions": [
{
"id": "5.1",
"text": "Registers grpc_health_v1.RegisterHealthServer (or equivalent health check service)"
},
{
"id": "5.2",
"text": "Uses health.NewServer() to create the health service"
},
{
"id": "5.3",
"text": "Registers interceptors using grpc.ChainUnaryInterceptor"
},
{
"id": "5.4",
"text": "Does NOT enable reflection (or explicitly disables it for production)"
},
{ "id": "5.5", "text": "Includes graceful shutdown handling" }
]
},
{
"id": 6,
"name": "client-connection-reuse-and-deadlines",
"description": "Tests that gRPC clients reuse connections and set deadlines on every call",
"prompt": "Write a Go gRPC client that calls a UserService. Create the client and make a GetUser call.",
"trap": "Without the skill, the model may create a new connection per request or not set a deadline. The skill requires connection reuse and context.WithTimeout on every call.",
"assertions": [
{
"id": "6.1",
"text": "Creates the connection once and reuses it (not creating a new connection per call)"
},
{
"id": "6.2",
"text": "Uses context.WithTimeout (or context.WithDeadline) for the RPC call"
},
{
"id": "6.3",
"text": "Uses grpc.NewClient (not the deprecated grpc.Dial)"
},
{
"id": "6.4",
"text": "Includes transport credentials (TLS or explicitly insecure for dev)"
},
{
"id": "6.5",
"text": "Properly defers cancel() from context.WithTimeout"
}
]
},
{
"id": 7,
"name": "bufconn-testing-pattern",
"description": "Tests that gRPC tests use bufconn for in-memory connections, not real network",
"prompt": "Write a test for a Go gRPC UserService that verifies GetUser returns the correct user and that requesting a non-existent user returns the proper error code.",
"trap": "Without the skill, the model may start a real TCP server for testing. The skill requires bufconn for in-memory connections.",
"assertions": [
{ "id": "7.1", "text": "Uses bufconn.Listen for an in-memory listener" },
{
"id": "7.2",
"text": "Uses grpc.WithContextDialer with the bufconn dialer"
},
{
"id": "7.3",
"text": "Verifies the gRPC status code for the not-found case using status.FromError"
},
{
"id": "7.4",
"text": "Checks that the error code is codes.NotFound specifically"
},
{
"id": "7.5",
"text": "Uses t.Cleanup or defer for cleaning up the server and connection"
}
]
},
{
"id": 8,
"name": "error-code-selection-judgment",
"description": "Tests correct gRPC error code selection across different scenarios",
"prompt": "Write a Go gRPC handler for CreateOrder that validates the request has a non-empty user_id and at least one item, checks the user exists, checks inventory availability, and creates the order. Return appropriate gRPC errors for each failure case.",
"trap": "Without the skill, the model may use codes.Internal for everything or pick wrong codes. The skill has a specific mapping table.",
"assertions": [
{
"id": "8.1",
"text": "Uses codes.InvalidArgument for missing user_id or empty items list"
},
{ "id": "8.2", "text": "Uses codes.NotFound for user not found" },
{
"id": "8.3",
"text": "Uses codes.FailedPrecondition for insufficient inventory (system not in required state)"
},
{
"id": "8.4",
"text": "Uses codes.Internal only for truly unexpected errors"
},
{
"id": "8.5",
"text": "Does NOT use codes.Unknown for any handled error case"
}
]
},
{
"id": 9,
"name": "unimplemented-server-embedding",
"description": "Tests that gRPC server implementations embed UnimplementedXxxServer, not UnsafeXxxServer",
"prompt": "Write a Go implementation of a gRPC server for an OrderService with CreateOrder and GetOrder RPCs. Show the struct definition and method signatures.",
"trap": "Without the skill, the model may embed UnsafeXxxServer or not embed any base server. The skill requires UnimplementedXxxServer for forward compatibility.",
"assertions": [
{
"id": "9.1",
"text": "Embeds UnimplementedOrderServiceServer in the server struct"
},
{ "id": "9.2", "text": "Does NOT embed UnsafeOrderServiceServer" },
{
"id": "9.3",
"text": "Implements the service methods with correct signatures (context, request pointer, response pointer and error return)"
},
{
"id": "9.4",
"text": "Uses status.Errorf for error returns in the handler methods"
},
{
"id": "9.5",
"text": "Registers the server with pb.RegisterOrderServiceServer"
}
]
},
{
"id": 10,
"name": "client-load-balancing-and-retry",
"description": "Tests knowledge of gRPC client-side load balancing and retry configuration",
"prompt": "I'm deploying a Go gRPC client in Kubernetes. The server has multiple replicas behind a headless service. How do I configure the client to distribute requests across all replicas and retry on transient failures?",
"trap": "Without the skill, the model may suggest a separate load balancer or basic round-robin without the dns:/// scheme. The skill shows the specific configuration.",
"assertions": [
{
"id": "10.1",
"text": "Uses the dns:/// scheme for service discovery with headless Kubernetes services"
},
{
"id": "10.2",
"text": "Configures round_robin load balancing policy via service config"
},
{
"id": "10.3",
"text": "Configures retry policy in the service config with retryableStatusCodes containing UNAVAILABLE"
},
{
"id": "10.4",
"text": "Sets maxAttempts, initialBackoff, maxBackoff in the retry policy"
},
{
"id": "10.5",
"text": "Does NOT suggest creating a new connection per request for load distribution"
}
]
},
{
"id": 11,
"name": "streaming-over-large-messages",
"description": "Tests preference for streaming over large single messages",
"prompt": "I need to send a result set of 50,000 records from a gRPC server to a client. Each record is about 1KB. What's the best approach?",
"trap": "Without the skill, the model may suggest increasing MaxRecvMsgSize and sending all records in one response. The skill recommends streaming to avoid per-message size limits and memory pressure.",
"assertions": [
{
"id": "11.1",
"text": "Recommends server streaming RPC to send records incrementally"
},
{
"id": "11.2",
"text": "Explains why a single large message is problematic (size limits, memory pressure)"
},
{
"id": "11.3",
"text": "Shows the server streaming pattern with stream.Send in a loop"
},
{
"id": "11.4",
"text": "Client reads with stream.Recv in a loop, checking for io.EOF"
},
{
"id": "11.5",
"text": "Does NOT just increase MaxRecvMsgSize as the primary solution"
}
]
}
]
references/protoc-reference.md›
# Protobuf & Code Generation Reference
## Table of Contents
- [Directory Layout](#directory-layout)
- [Proto File Conventions](#proto-file-conventions)
- [`go_package` conventions](#go_package-conventions)
- [Code Generation with `protoc`](#code-generation-with-protoc)
- [Common `protoc` flags](#common-protoc-flags)
- [Code Generation with `buf`](#code-generation-with-buf)
- [`buf.gen.yaml`](#bufgenyaml)
- [`buf.yaml`](#bufyaml)
- [Common `buf` commands](#common-buf-commands)
- [Generated Code Patterns](#generated-code-patterns)
## Directory Layout
Organize proto files by domain with versioned directories. Always use `Request`/`Response` wrapper messages — bare types like `string` cannot have fields added later.
```
proto/
├── user/v1/
│ ├── user.proto # Messages
│ └── user_service.proto # Service RPCs
├── order/v1/
│ ├── order.proto
│ └── order_service.proto
└── shared/v1/
└── common.proto # Pagination, timestamps, shared enums
```
## Proto File Conventions
```protobuf
syntax = "proto3";
package mycompany.user.v1;
option go_package = "github.com/mycompany/myservice/gen/user/v1;userv1";
service UserService {
rpc GetUser(GetUserRequest) returns (GetUserResponse);
rpc ListUsers(ListUsersRequest) returns (ListUsersResponse);
rpc CreateUser(CreateUserRequest) returns (CreateUserResponse);
rpc UpdateUser(UpdateUserRequest) returns (UpdateUserResponse);
rpc DeleteUser(DeleteUserRequest) returns (DeleteUserResponse);
}
message GetUserRequest {
string user_id = 1;
}
message GetUserResponse {
User user = 1;
}
message ListUsersRequest {
int32 page_size = 1;
string page_token = 2;
}
message ListUsersResponse {
repeated User users = 1;
string next_page_token = 2;
}
```
### `go_package` conventions
- Format: `"import/path;alias"` — the alias becomes the Go package name
- Convention: lowercase version suffix (e.g. `userv1`, `orderv1`)
- Generate into a `gen/` directory to keep generated code separate from hand-written code
## Code Generation with `protoc`
```bash
# Basic generation
protoc --go_out=gen --go_opt=paths=source_relative \
--go-grpc_out=gen --go-grpc_opt=paths=source_relative \
proto/user/v1/*.proto
# With validation (using buf-validate)
protoc --go_out=gen --go_opt=paths=source_relative \
--go-grpc_out=gen --go-grpc_opt=paths=source_relative \
--validate_out="lang=go:gen" \
proto/user/v1/*.proto
# Include external imports
protoc -I proto -I third_party \
--go_out=gen --go_opt=paths=source_relative \
--go-grpc_out=gen --go-grpc_opt=paths=source_relative \
proto/user/v1/*.proto
```
### Common `protoc` flags
| Flag | Purpose |
| -------------------------------- | --------------------------------------- |
| `--go_out=DIR` | Output directory for message types |
| `--go-grpc_out=DIR` | Output directory for service stubs |
| `--go_opt=paths=source_relative` | Place output relative to proto source |
| `-I DIR` | Add import path for proto dependencies |
| `--descriptor_set_out=FILE` | Emit binary descriptor (for reflection) |
## Code Generation with `buf`
`buf` is the recommended modern alternative to raw `protoc`. It manages dependencies, lints protos, and generates code from a single config.
### `buf.gen.yaml`
```yaml
version: v2
plugins:
- remote: buf.build/protocolbuffers/go
out: gen
opt: paths=source_relative
- remote: buf.build/grpc/go
out: gen
opt: paths=source_relative
```
### `buf.yaml`
```yaml
version: v2
modules:
- path: proto
lint:
use:
- STANDARD
breaking:
use:
- FILE
```
### Common `buf` commands
```bash
buf generate # Generate code from buf.gen.yaml
buf lint # Lint proto files
buf breaking --against '.git#branch=main' # Check backward compatibility
buf dep update # Update dependencies
buf build # Validate proto files compile
```
## Generated Code Patterns
After generation, import and use the generated code:
```go
import (
userv1 "github.com/mycompany/myservice/gen/user/v1"
)
// Server: implement the interface
type userServer struct {
userv1.UnimplementedUserServiceServer
}
// Client: use the generated client
client := userv1.NewUserServiceClient(conn)
resp, err := client.GetUser(ctx, &userv1.GetUserRequest{UserId: "123"})
```
Always embed `Unimplemented*Server` (not `Unsafe*Server`) — it provides forward compatibility when new RPCs are added to the proto definition.
references/testing.md›
# gRPC Testing Reference
## Table of Contents
- [Testing with `bufconn`](#testing-with-bufconn)
- [Basic Setup](#basic-setup)
- [Setup with Interceptors](#setup-with-interceptors)
- [Testing Error Codes](#testing-error-codes)
- [Table-Driven Error Code Tests](#table-driven-error-code-tests)
- [Testing Streaming RPCs](#testing-streaming-rpcs)
- [Server Streaming](#server-streaming)
- [Client Streaming](#client-streaming)
- [Testing Metadata](#testing-metadata)
- [Testing Deadlines](#testing-deadlines)
- [Integration Test Patterns](#integration-test-patterns)
## Testing with `bufconn`
`bufconn` creates in-memory connections that exercise the full gRPC stack (serialization, interceptors, metadata) without network overhead. This is the standard approach for gRPC unit and integration tests.
### Basic Setup
```go
func setupTest(t *testing.T) pb.UserServiceClient {
t.Helper()
lis := bufconn.Listen(1024 * 1024)
t.Cleanup(func() { lis.Close() })
srv := grpc.NewServer()
pb.RegisterUserServiceServer(srv, newTestService())
t.Cleanup(func() { srv.Stop() })
go srv.Serve(lis)
conn, err := grpc.NewClient("passthrough:///bufconn",
grpc.WithContextDialer(func(ctx context.Context, _ string) (net.Conn, error) {
return lis.DialContext(ctx)
}),
grpc.WithTransportCredentials(insecure.NewCredentials()),
)
if err != nil {
t.Fatalf("dial: %v", err)
}
t.Cleanup(func() { conn.Close() })
return pb.NewUserServiceClient(conn)
}
```
### Setup with Interceptors
Test your interceptors by including them in the test server:
```go
func setupTestWithInterceptors(t *testing.T) pb.UserServiceClient {
t.Helper()
lis := bufconn.Listen(1024 * 1024)
t.Cleanup(func() { lis.Close() })
srv := grpc.NewServer(
grpc.ChainUnaryInterceptor(
loggingInterceptor,
authInterceptor,
recoveryInterceptor,
),
)
pb.RegisterUserServiceServer(srv, newTestService())
t.Cleanup(func() { srv.Stop() })
go srv.Serve(lis)
conn, err := grpc.NewClient("passthrough:///bufconn",
grpc.WithContextDialer(func(ctx context.Context, _ string) (net.Conn, error) {
return lis.DialContext(ctx)
}),
grpc.WithTransportCredentials(insecure.NewCredentials()),
)
if err != nil {
t.Fatalf("dial: %v", err)
}
t.Cleanup(func() { conn.Close() })
return pb.NewUserServiceClient(conn)
}
```
## Testing Error Codes
Always verify that RPCs return the expected gRPC status codes — clients rely on codes for retry and error-handling logic.
```go
func TestGetUser_NotFound(t *testing.T) {
client := setupTest(t)
_, err := client.GetUser(context.Background(), &pb.GetUserRequest{UserId: "nonexistent"})
st, ok := status.FromError(err)
if !ok {
t.Fatalf("expected gRPC status error, got: %v", err)
}
if st.Code() != codes.NotFound {
t.Errorf("expected NotFound, got %s: %s", st.Code(), st.Message())
}
}
```
### Table-Driven Error Code Tests
```go
func TestGetUser_Errors(t *testing.T) {
client := setupTest(t)
tests := []struct {
name string
req *pb.GetUserRequest
wantCode codes.Code
}{
{
name: "empty user ID",
req: &pb.GetUserRequest{UserId: ""},
wantCode: codes.InvalidArgument,
},
{
name: "user not found",
req: &pb.GetUserRequest{UserId: "nonexistent"},
wantCode: codes.NotFound,
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
_, err := client.GetUser(context.Background(), tt.req)
st, ok := status.FromError(err)
if !ok {
t.Fatalf("expected gRPC status error, got: %v", err)
}
if st.Code() != tt.wantCode {
t.Errorf("code = %s, want %s; message: %s", st.Code(), tt.wantCode, st.Message())
}
})
}
}
```
## Testing Streaming RPCs
### Server Streaming
```go
func TestListUsers_Stream(t *testing.T) {
client := setupTest(t)
stream, err := client.ListUsers(context.Background(), &pb.ListUsersRequest{})
if err != nil {
t.Fatalf("ListUsers: %v", err)
}
var users []*pb.User
for {
user, err := stream.Recv()
if err == io.EOF {
break
}
if err != nil {
t.Fatalf("Recv: %v", err)
}
users = append(users, user)
}
if len(users) != 3 {
t.Errorf("got %d users, want 3", len(users))
}
}
```
### Client Streaming
```go
func TestBatchCreate_ClientStream(t *testing.T) {
client := setupTest(t)
stream, err := client.BatchCreateUsers(context.Background())
if err != nil {
t.Fatalf("BatchCreateUsers: %v", err)
}
for _, u := range testUsers {
if err := stream.Send(u); err != nil {
t.Fatalf("Send: %v", err)
}
}
resp, err := stream.CloseAndRecv()
if err != nil {
t.Fatalf("CloseAndRecv: %v", err)
}
if resp.Created != int32(len(testUsers)) {
t.Errorf("created = %d, want %d", resp.Created, len(testUsers))
}
}
```
## Testing Metadata
Verify that interceptors correctly read/write metadata:
```go
func TestAuth_Metadata(t *testing.T) {
client := setupTestWithInterceptors(t)
// Without auth token → Unauthenticated
_, err := client.GetUser(context.Background(), &pb.GetUserRequest{UserId: "1"})
if st, _ := status.FromError(err); st.Code() != codes.Unauthenticated {
t.Errorf("expected Unauthenticated without token, got %s", st.Code())
}
// With valid token → success
md := metadata.Pairs("authorization", "Bearer valid-token")
ctx := metadata.NewOutgoingContext(context.Background(), md)
resp, err := client.GetUser(ctx, &pb.GetUserRequest{UserId: "1"})
if err != nil {
t.Fatalf("expected success with valid token: %v", err)
}
if resp.User == nil {
t.Error("expected user in response")
}
}
```
## Testing Deadlines
```go
func TestGetUser_DeadlineExceeded(t *testing.T) {
client := setupTest(t) // server handler sleeps for 5s
ctx, cancel := context.WithTimeout(context.Background(), 50*time.Millisecond)
defer cancel()
_, err := client.GetUser(ctx, &pb.GetUserRequest{UserId: "slow"})
st, _ := status.FromError(err)
if st.Code() != codes.DeadlineExceeded {
t.Errorf("expected DeadlineExceeded, got %s", st.Code())
}
}
```
## Integration Test Patterns
For tests that hit real dependencies (database, external services), use build tags to separate them:
```go
//go:build integration
func TestUserService_Integration(t *testing.T) {
// Connect to real gRPC server
conn, err := grpc.NewClient("localhost:50051",
grpc.WithTransportCredentials(insecure.NewCredentials()),
)
if err != nil {
t.Fatalf("dial: %v", err)
}
defer conn.Close()
client := pb.NewUserServiceClient(conn)
// Test full roundtrip
created, err := client.CreateUser(context.Background(), &pb.CreateUserRequest{
Name: "integration-test",
Email: "[email protected]",
})
if err != nil {
t.Fatalf("CreateUser: %v", err)
}
got, err := client.GetUser(context.Background(), &pb.GetUserRequest{
UserId: created.User.Id,
})
if err != nil {
t.Fatalf("GetUser: %v", err)
}
if got.User.Name != "integration-test" {
t.Errorf("name = %q, want %q", got.User.Name, "integration-test")
}
}
```
Run integration tests separately:
```bash
go test -tags=integration ./...
```
SKILL.md›
---
name: golang-grpc
description: "Provides gRPC usage guidelines, protobuf organization, and production-ready patterns for Golang microservices. Use when implementing, reviewing, or debugging gRPC servers/clients, writing proto files, setting up interceptors, handling gRPC errors with status codes, configuring TLS/mTLS, testing with bufconn, or working with streaming RPCs."
user-invocable: true
license: MIT
compatibility: Designed for Claude Code, Codex or similar harness, and for projects using Golang.
metadata:
author: samber
version: "1.2.2"
openclaw:
emoji: "🌐"
homepage: https://github.com/samber/cc-skills-golang
requires:
bins:
- go
- protoc
install:
- kind: brew
formula: protobuf
bins: [protoc]
allowed-tools: Read Edit Write Glob Grep Bash(go:*) Bash(golangci-lint:*) Bash(git:*) Agent WebFetch mcp__context7__resolve-library-id mcp__context7__query-docs Bash(protoc:*) AskUserQuestion Bash(godig:*) Bash(gopls:*) LSP mcp__gopls__*
paths:
- "**/*.go"
---
**Persona:** You are a Go distributed systems engineer. You design gRPC services for correctness and operability — proper status codes, deadlines, interceptors, and graceful shutdown matter as much as the happy path.
**Modes:**
- **Build mode** — implementing a new gRPC server or client from scratch.
- **Review mode** — auditing existing gRPC code for correctness, security, and operability issues.
**Dependencies:**
- protoc: `brew install protobuf`
- protoc-gen-go: `go install google.golang.org/protobuf/cmd/protoc-gen-go@latest`
- protoc-gen-go-grpc: `go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest`
# Go gRPC Best Practices
Treat gRPC as a pure transport layer — keep it separate from business logic. The official Go implementation is `google.golang.org/grpc`.
This skill is not exhaustive — refer to library documentation and code examples for more information:
- For Go package docs, symbols, versions, importers, and known vulnerabilities, → See `samber/cc-skills-golang@golang-pkg-go-dev` skill (`godig`), preferred over Context7 for Go package facts.
- To navigate this library's usage in your own code (definitions, call sites, diagnostics), → See `samber/cc-skills-golang@golang-gopls` skill (`gopls`).
- Context7 remains a fallback for docs not indexed on pkg.go.dev.
## Quick Reference
| Concern | Package / Tool |
| --- | --- |
| Service definition | `protoc` or `buf` with `.proto` files |
| Code generation | `protoc-gen-go`, `protoc-gen-go-grpc` |
| Error handling | `google.golang.org/grpc/status` with `codes` |
| Rich error details | `google.golang.org/genproto/googleapis/rpc/errdetails` |
| Interceptors | `grpc.ChainUnaryInterceptor`, `grpc.ChainStreamInterceptor` |
| Middleware ecosystem | `github.com/grpc-ecosystem/go-grpc-middleware` |
| Testing | `google.golang.org/grpc/test/bufconn` |
| TLS / mTLS | `google.golang.org/grpc/credentials` |
| Health checks | `google.golang.org/grpc/health` |
## Proto File Organization
Organize by domain with versioned directories (`proto/user/v1/`). Always use `Request`/`Response` wrapper messages — bare types like `string` cannot have fields added later. Generate with `buf generate` or `protoc`.
[Proto & code generation reference](references/protoc-reference.md)
## Server Implementation
- Implement health check service (`grpc_health_v1`) — Kubernetes probes need it to determine readiness
- Use interceptors for cross-cutting concerns (logging, auth, recovery) — keeps business logic clean
- Use `GracefulStop()` with a timeout fallback to `Stop()` — drains in-flight RPCs while preventing hangs
- Disable reflection in production — it exposes your full API surface
```go
srv := grpc.NewServer(
grpc.ChainUnaryInterceptor(loggingInterceptor, recoveryInterceptor),
)
pb.RegisterUserServiceServer(srv, svc)
healthpb.RegisterHealthServer(srv, health.NewServer())
go srv.Serve(lis)
// On shutdown signal:
stopped := make(chan struct{})
go func() { srv.GracefulStop(); close(stopped) }()
select {
case <-stopped:
case <-time.After(15 * time.Second):
srv.Stop()
}
```
### Interceptor Pattern
```go
func loggingInterceptor(ctx context.Context, req any, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (any, error) {
start := time.Now()
resp, err := handler(ctx, req)
log.Printf("method=%s duration=%s code=%s", info.FullMethod, time.Since(start), status.Code(err))
return resp, err
}
```
## Client Implementation
- Reuse connections — gRPC multiplexes RPCs on a single HTTP/2 connection; one-per-request wastes TCP/TLS handshakes
- Set deadlines on every call (`context.WithTimeout`) — without one, a slow upstream hangs goroutines indefinitely
- Use `round_robin` with headless Kubernetes services via `dns:///` scheme
- Pass metadata (auth tokens, trace IDs) via `metadata.NewOutgoingContext`
```go
conn, err := grpc.NewClient("dns:///user-service:50051",
grpc.WithTransportCredentials(creds),
grpc.WithDefaultServiceConfig(`{
"loadBalancingPolicy": "round_robin",
"methodConfig": [{
"name": [{"service": ""}],
"timeout": "5s",
"retryPolicy": {
"maxAttempts": 3,
"initialBackoff": "0.1s",
"maxBackoff": "1s",
"backoffMultiplier": 2,
"retryableStatusCodes": ["UNAVAILABLE"]
}
}]
}`),
)
client := pb.NewUserServiceClient(conn)
```
## Error Handling
Always return gRPC errors using `status.Error` with a specific code — a raw `error` becomes `codes.Unknown`, telling the client nothing actionable. Clients use codes to decide retry vs fail-fast vs degrade.
| Code | When to Use |
| -------------------- | ------------------------------------------- |
| `InvalidArgument` | Malformed input (missing field, bad format) |
| `NotFound` | Entity does not exist |
| `AlreadyExists` | Create failed, entity exists |
| `PermissionDenied` | Caller lacks permission |
| `Unauthenticated` | Missing or invalid token |
| `FailedPrecondition` | System not in required state |
| `ResourceExhausted` | Rate limit or quota exceeded |
| `Unavailable` | Transient issue, safe to retry |
| `Internal` | Unexpected bug |
| `DeadlineExceeded` | Timeout |
```go
// ✗ Bad — caller gets codes.Unknown, can't decide whether to retry
return nil, fmt.Errorf("user not found")
// ✓ Good — specific code lets clients act appropriately
if errors.Is(err, ErrNotFound) {
return nil, status.Errorf(codes.NotFound, "user %q not found", req.UserId)
}
return nil, status.Errorf(codes.Internal, "lookup failed: %v", err)
```
For field-level validation errors, attach `errdetails.BadRequest` via `status.WithDetails`.
## Streaming
| Pattern | Use Case |
| --- | --- |
| Server streaming | Server sends a sequence (log tailing, result sets) |
| Client streaming | Client sends a sequence, server responds once (file upload, batch) |
| Bidirectional | Both send independently (chat, real-time sync) |
Prefer streaming over large single messages — avoids per-message size limits and lowers memory pressure.
```go
func (s *server) ListUsers(req *pb.ListUsersRequest, stream pb.UserService_ListUsersServer) error {
for _, u := range users {
if err := stream.Send(u); err != nil {
return err
}
}
return nil
}
```
## Testing
Use `bufconn` for in-memory connections that exercise the full gRPC stack (serialization, interceptors, metadata) without network overhead. Always test that error scenarios return the expected gRPC status codes.
[Testing patterns and examples](references/testing.md)
## Security
- TLS MUST be enabled in production — credentials travel in metadata
- For service-to-service auth, use mTLS or delegate to a service mesh (Istio, Linkerd)
- For user auth, implement `credentials.PerRPCCredentials` and validate tokens in an auth interceptor
- Reflection SHOULD be disabled in production to prevent API discovery
## Performance
| Setting | Purpose | Typical Value |
| --- | --- | --- |
| `keepalive.ServerParameters.Time` | Ping interval for idle connections | 30s |
| `keepalive.ServerParameters.Timeout` | Ping ack timeout | 10s |
| `grpc.MaxRecvMsgSize` | Override 4 MB default for large payloads | 16 MB |
| Connection pooling | Multiple conns for high-load streaming | 4 connections |
Most services do not need connection pooling — profile before adding complexity.
## Common Mistakes
| Mistake | Fix |
| --- | --- |
| Returning raw `error` | Becomes `codes.Unknown` — client can't decide whether to retry. Use `status.Errorf` with a specific code |
| No deadline on client calls | Slow upstream hangs indefinitely. Always `context.WithTimeout` |
| New connection per request | Wastes TCP/TLS handshakes. Create once, reuse — HTTP/2 multiplexes RPCs |
| Reflection enabled in production | Lets attackers enumerate every method. Enable only in dev/staging |
| `codes.Internal` for all errors | Wrong codes break client retry logic. `Unavailable` triggers retry; `InvalidArgument` does not |
| Bare types as RPC arguments | Can't add fields to `string`. Wrapper messages allow backwards-compatible evolution |
| Missing health check service | Kubernetes can't determine readiness, kills pods during deployments |
| Ignoring context cancellation | Long operations continue after caller gave up. Check `ctx.Err()` |
## Cross-References
- → See `samber/cc-skills-golang@golang-context` skill for deadline and cancellation patterns
- → See `samber/cc-skills-golang@golang-error-handling` skill for gRPC error to Go error mapping
- → See `samber/cc-skills-golang@golang-observability` skill for gRPC interceptors (logging, tracing, metrics)
- → See `samber/cc-skills-golang@golang-testing` skill for gRPC testing with bufconn