Golang Grpc

作者 bobmatnyc718070a7d622MIT77 个星标收录于 2026年10月8日更新于 2026年10月8日仓库2个月前更新

Production gRPC in Go: protobuf layout, codegen, interceptors, deadlines, error codes, streaming, health checks, TLS, and testing with bufconn

仅含说明Software Development
AI 生成的概览

指导在 Go 中构建生产级 gRPC 服务，涵盖 protobuf 布局、代码生成、拦截器、截止时间、流式传输、TLS 与测试。

功能
该技能为在 Go 中构建生产级 gRPC 服务提供参考指导。内容涵盖带版本号的 protobuf API 布局、代码生成命令、使用状态码与截止时间的服务端实现、拦截器、流式传输模式、健康检查、优雅关闭、TLS，以及使用 bufconn 的内存测试。它产出的是说明性示例与代码模式，而非可直接运行的产物。
适用场景
适用于构建需要类型化 RPC、流式传输、低延迟或基于 protobuf 的强客户端/服务端契约的 Go 微服务。也适合用截止时间、错误码、拦截器和测试来加固现有 gRPC 服务。
运行要求
不包含脚本，仅为说明性内容。按指导操作需要 Go 工具链、带 protoc-gen-go 与 protoc-gen-go-grpc 的 protoc，以及 gRPC/protobuf 的 Go 模块；TLS 示例需要证书与密钥文件。

Go gRPC (Production)

Overview

gRPC provides strongly-typed RPC APIs backed by Protocol Buffers, with first-class streaming support and excellent performance for service-to-service communication. This skill focuses on production defaults: versioned protos, deadlines, error codes, interceptors, health checks, TLS, and testability.

Quick Start

1) Define a versioned protobuf API

✅ Correct: versioned package

proto
// proto/users/v1/users.protosyntax = "proto3";
package users.v1;option go_package = "example.com/myapp/gen/users/v1;usersv1";
service UsersService {  rpc GetUser(GetUserRequest) returns (GetUserResponse);  rpc ListUsers(ListUsersRequest) returns (stream User);}
message GetUserRequest { string id = 1; }message GetUserResponse { User user = 1; }message ListUsersRequest { int32 page_size = 1; string page_token = 2; }
message User {  string id = 1;  string email = 2;  string display_name = 3;}

❌ Wrong: unversioned package (hard to evolve)

proto
package users;

2) Generate Go code

Install generators:

bash
go install google.golang.org/protobuf/cmd/protoc-gen-go@latestgo install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest

Generate:

bash
protoc -I proto \  --go_out=./gen --go_opt=paths=source_relative \  --go-grpc_out=./gen --go-grpc_opt=paths=source_relative \  proto/users/v1/users.proto

3) Implement server with deadlines and status codes

✅ Correct: validate + map errors to gRPC codes

go
package usersvc
import (    "context"
    "google.golang.org/grpc/codes"    "google.golang.org/grpc/status"
    usersv1 "example.com/myapp/gen/users/v1")
type Service struct {    usersv1.UnimplementedUsersServiceServer    Repo Repo}
type Repo interface {    GetUser(ctx context.Context, id string) (User, error)}
type User struct {    ID, Email, DisplayName string}
func (s *Service) GetUser(ctx context.Context, req *usersv1.GetUserRequest) (*usersv1.GetUserResponse, error) {    if req.GetId() == "" {        return nil, status.Error(codes.InvalidArgument, "id is required")    }
    u, err := s.Repo.GetUser(ctx, req.GetId())    if err != nil {        if err == ErrNotFound {            return nil, status.Error(codes.NotFound, "user not found")        }        return nil, status.Error(codes.Internal, "internal error")    }
    return &usersv1.GetUserResponse{        User: &usersv1.User{            Id:          u.ID,            Email:       u.Email,            DisplayName: u.DisplayName,        },    }, nil}

❌ Wrong: return raw errors (clients lose code semantics)

go
return nil, errors.New("user not found")

Core Concepts

Deadlines and cancellation

Make every call bounded; enforce server-side timeouts for expensive handlers.

✅ Correct: require deadline

go
if _, ok := ctx.Deadline(); !ok {    return nil, status.Error(codes.InvalidArgument, "deadline required")}

Metadata

Use metadata for auth/session correlation, not for primary request data.

✅ Correct: read auth token from metadata

go
md, _ := metadata.FromIncomingContext(ctx)auth := ""if vals := md.Get("authorization"); len(vals) > 0 {    auth = vals[0]}

Interceptors (Middleware)

Use interceptors for cross-cutting concerns: auth, logging, metrics, tracing, request IDs.

✅ Correct: unary interceptor with request ID

go
func unaryRequestID() grpc.UnaryServerInterceptor {    return func(ctx context.Context, req any, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (any, error) {        id := uuid.NewString()        ctx = context.WithValue(ctx, requestIDKey{}, id)        resp, err := handler(ctx, req)        return resp, err    }}

Streaming patterns

Server streaming (paginate or stream results)

✅ Correct: stop on ctx.Done()

go
func (s *Service) ListUsers(req *usersv1.ListUsersRequest, stream usersv1.UsersService_ListUsersServer) error {    users, err := s.Repo.ListUsers(stream.Context(), int(req.GetPageSize()))    if err != nil {        return status.Error(codes.Internal, "internal error")    }
    for _, u := range users {        select {        case <-stream.Context().Done():            return stream.Context().Err()        default:        }
        if err := stream.Send(&usersv1.User{            Id:          u.ID,            Email:       u.Email,            DisplayName: u.DisplayName,        }); err != nil {            return err        }    }    return nil}

Unary vs streaming decision

  • Use unary for single request/response and simple retries.
  • Use server streaming for large result sets or continuous updates.
  • Use client streaming for bulk uploads with one final response.
  • Use bidirectional streaming for interactive protocols.

Production Hardening

Health checks and reflection

Add health service; enable reflection only in non-production environments.

✅ Correct: health + conditional reflection

go
hs := health.NewServer()grpc_health_v1.RegisterHealthServer(s, hs)
if env != "production" {    reflection.Register(s)}

Graceful shutdown

Prefer GracefulStop with a deadline.

✅ Correct: graceful stop

go
stopped := make(chan struct{})go func() {    grpcServer.GracefulStop()    close(stopped)}()
select {case <-stopped:case <-time.After(10 * time.Second):    grpcServer.Stop()}

TLS

Use TLS (or mTLS) in production; avoid insecure credentials outside local dev.

✅ Correct: server TLS

go
creds, err := credentials.NewServerTLSFromFile("server.crt", "server.key")if err != nil { return err }
grpcServer := grpc.NewServer(grpc.Creds(creds))

Testing (bufconn)

Test gRPC handlers without opening real sockets using bufconn.

✅ Correct: in-memory gRPC test server

go
const bufSize = 1024 * 1024
lis := bufconn.Listen(bufSize)srv := grpc.NewServer()usersv1.RegisterUsersServiceServer(srv, &Service{Repo: repo})
go func() { _ = srv.Serve(lis) }()
ctx := context.Background()conn, err := grpc.DialContext(    ctx,    "bufnet",    grpc.WithContextDialer(func(context.Context, string) (net.Conn, error) { return lis.Dial() }),    grpc.WithTransportCredentials(insecure.NewCredentials()),)if err != nil { t.Fatal(err) }defer conn.Close()
client := usersv1.NewUsersServiceClient(conn)resp, err := client.GetUser(ctx, &usersv1.GetUserRequest{Id: "1"})_ = resp_ = err

Anti-Patterns

  • Ignore deadlines: unbounded handlers cause tail latency and resource exhaustion.

  • Return string errors: map domain errors to codes.* with status.Error or status.Errorf.

  • Stream without backpressure: stop on ctx.Done() and handle Send errors.

  • Expose reflection in production: treat reflection as a discovery surface.

Troubleshooting

Symptom: clients see UNKNOWN errors

Actions:

  • Return status.Error(codes.X, "...") instead of raw errors.
  • Wrap domain errors into typed errors, then map to gRPC codes.

Symptom: slow/hanging requests

Actions:

  • Require deadlines and propagate ctx to downstream calls.
  • Add server-side timeouts and bounded concurrency in repositories.

Symptom: flaky streaming

Actions:

  • Stop streaming on ctx.Done() and handle stream.Send errors.
  • Avoid buffering entire result sets before sending.

Resources

来源与署名

来源：bobmatnyc/claude-mpm-skills位于toolchains/golang/golang-grpc提交718070a

许可证： MIT

内容归原作者所有。SourceWeft 从公开仓库中收录这些内容。

举报或申请下架

更多来自 bobmatnyc/claude-mpm-skills 的技能

Wordpress Security Validation

bobmatnyc

讲解以安全为先的 WordPress 开发模式，涵盖 nonce、清理、验证与输出转义。

Security772个月前更新

Bug Fix

bobmatnyc

提供结构化的缺陷修复流程：复现、定位根因、修复、验证、补充回归测试并记录 PR。

Software Development772个月前更新

Threat Modeling

bobmatnyc

运行轻量级 STRIDE 威胁建模工作坊，并将识别出的风险转化为缓解措施、工单和测试。

Security772个月前更新

Webapp Testing

bobmatnyc

提供 Playwright 模式的参考指南，用于编写 Web 应用测试，涵盖选择器、等待、断言与调试。

Software Development772个月前更新

Opentelemetry

bobmatnyc

提供使用 OpenTelemetry 为服务埋点并通过 Collector 导出 OTLP 遥测的参考指导。

DevOps & Cloud772个月前更新

Skill Creator

bobmatnyc

指导如何创建、组织并打包模块化的智能体技能，并运用渐进式披露。

AI & Agents772个月前更新

更多Software Development技能

Playground

anthropics

精选

构建自包含的交互式 HTML 演练场，包含控件、实时预览和可复制的提示词输出。

Software Development37K今天更新

M5 Onboard

anthropics

精选

通过 USB 检测 M5Stack ESP32 开发板，刷写 UIFlow 2.0 固件并安装 MicroPython 应用包。

Software Development37K今天更新

Cardputer Buddy

anthropics

精选

指导迭代 Cardputer-Adv 的 MicroPython 应用包：添加应用、通过 USB 串口推送文件、查看日志并运行 REPL 命令。

Software Development37K今天更新

Web Design Guidelines

vercel-labs

精选

依据从远程来源获取的 Web Interface Guidelines 审查 UI 代码，并以 file:line 形式报告问题。

Software Development32K5周前更新

Vercel React Native Skills

vercel-labs

精选

React Native 与 Expo 最佳实践规则，涵盖列表性能、动画、导航、UI 模式、状态与 monorepo 配置。

Software Development32K5周前更新

Vercel React Best Practices

vercel-labs

精选

Vercel 的 React 与 Next.js 性能指南，以 70 条规则的形式用于编写、审查和重构代码。

Software Development32K5周前更新