AgentSkillsCN

grpc-development

以 gRPC 与 Protocol Buffers 为工具，构建高性能服务的最佳实践与使用指南。

SKILL.md
--- frontmatter
name: grpc-development
description: Best practices and guidelines for building high-performance services with gRPC and Protocol Buffers

gRPC Development

You are an expert in gRPC and Protocol Buffers development. Follow these best practices when building gRPC-based services and APIs.

Core Principles

  • •gRPC uses Protocol Buffers as both its Interface Definition Language (IDL) and message interchange format
  • •Design services around the idea of defining methods that can be called remotely with their parameters and return types
  • •Prioritize type safety, performance, and backward compatibility
  • •Leave NO todos, placeholders, or missing pieces in the implementation

Protocol Buffer Best Practices

File Organization (1-1-1 Pattern)

  • •Structure definitions with one top-level entity (message, enum, or extension) per .proto file
  • •Correspond each .proto file to a single build rule
  • •This promotes small, modular proto definitions
  • •Benefits include simplified refactoring, improved build times, and smaller binary sizes

Message Design

  • •Use structured messages for extensibility - Protocol Buffers supports adding fields without breaking existing clients
  • •Be careful to use structs in places you may want to add fields later
  • •Don't re-use messages across RPCs - APIs may change over time, avoid coupling separate RPC calls tightly together
  • •Fields should always be independent of each other - don't have one field influence the semantic meaning of another

Field Guidelines

  • •Use descriptive field names with underscore_separated_names
  • •Reserve field numbers for deleted fields to prevent future conflicts
  • •Use optional for fields that may not always be present
  • •Consider using oneof when users need to choose between mutually exclusive options

Enum Best Practices

  • •Ensure the first value is always 0
  • •Use an "UNSPECIFIED" default value (e.g., STATUS_UNSPECIFIED = 0)
  • •Use prefixes to avoid naming collisions (e.g., ORDER_STATUS_CREATED vs STATUS_PENDING)
  • •Reserve enum values that are removed to prevent accidental reuse

Style Guidelines

  • •Keep line length to 80 characters
  • •Prefer double quotes for strings
  • •Package names should be in lowercase
  • •Use CamelCase (with initial capital) for message names
  • •Use underscore_separated_names for field names
  • •Use CamelCase for service and RPC method names

Service Design

RPC Patterns

  • •Unary RPC: Client sends single request, server responds with single response
  • •Server Streaming: Client sends request, server responds with stream of messages
  • •Client Streaming: Client sends stream of messages, server responds with single response
  • •Bidirectional Streaming: Both sides send streams of messages

API Design

  • •Design clear, intuitive service interfaces
  • •Group related methods in the same service
  • •Use meaningful method names that describe the action
  • •Document each RPC with comments describing behavior, parameters, and return values

Performance Optimization

Channel Management

  • •Reuse channels when working with gRPC
  • •Creating a gRPC channel is costly as it creates a new HTTP/2 connection
  • •Implement connection pooling for high-throughput scenarios
  • •Configure keepalive settings appropriately

Message Optimization

  • •Keep messages reasonably sized - large messages impact performance
  • •Consider streaming for large data transfers
  • •Use compression for bandwidth-constrained environments
  • •Avoid deeply nested message structures

Error Handling

Status Codes

  • •Use appropriate gRPC status codes (OK, INVALID_ARGUMENT, NOT_FOUND, etc.)
  • •Include meaningful error messages in status details
  • •Use rich error details for complex error scenarios
  • •Document expected error conditions in service definitions

Retry Logic

  • •Implement retry with exponential backoff for transient failures
  • •Use deadlines/timeouts for all RPC calls
  • •Handle UNAVAILABLE and RESOURCE_EXHAUSTED with retries
  • •Don't retry non-idempotent operations blindly

Security

Authentication

  • •Use TLS for transport security in production
  • •Implement per-RPC authentication using metadata/headers
  • •Support multiple authentication mechanisms (JWT, OAuth2, mTLS)
  • •Validate credentials on every request

Authorization

  • •Implement method-level access control
  • •Use interceptors for centralized authorization logic
  • •Validate all input data regardless of authentication status
  • •Follow the principle of least privilege

Interceptors and Middleware

Server Interceptors

  • •Use interceptors for cross-cutting concerns (logging, auth, metrics)
  • •Order interceptors carefully - execution order matters
  • •Keep interceptors focused on single responsibilities
  • •Handle errors gracefully within interceptors

Client Interceptors

  • •Add metadata (headers) for tracing and authentication
  • •Implement request/response logging
  • •Add automatic retry logic
  • •Collect client-side metrics

Testing

Unit Testing

  • •Mock gRPC services for isolated testing
  • •Test message serialization/deserialization
  • •Verify error handling paths
  • •Test interceptor logic independently

Integration Testing

  • •Test with real gRPC connections where possible
  • •Verify streaming behavior end-to-end
  • •Test timeout and cancellation scenarios
  • •Load test with realistic traffic patterns

Observability

Distributed Tracing

  • •Use OpenTelemetry for distributed tracing across service boundaries
  • •Propagate trace context in metadata
  • •Instrument both client and server sides
  • •Start spans for each RPC call

Metrics

  • •Track RPC latency histograms
  • •Monitor error rates by method and status code
  • •Count active connections and streams
  • •Alert on anomalies and SLA violations

Logging

  • •Use structured logging with consistent fields
  • •Log RPC method, duration, and status
  • •Include trace IDs for correlation
  • •Avoid logging sensitive data

Language-Specific Guidelines

Go

  • •Use the official google.golang.org/grpc package
  • •Implement services as interface types
  • •Use context for cancellation and deadlines
  • •Leverage code generation with protoc-gen-go-grpc

Python

  • •Use grpcio and grpcio-tools packages
  • •Implement async services with grpcio-aio for better concurrency
  • •Use type hints with generated stubs
  • •Handle blocking calls appropriately in async contexts

Node.js/TypeScript

  • •Use @grpc/grpc-js (pure JavaScript implementation)
  • •Consider using nice-grpc for better TypeScript support
  • •Leverage async/await patterns
  • •Use static codegen for type safety