grpc

---
name: grpc
description: gRPC开发专家助手。当用户需要进行gRPC服务开发、Protobuf定义、流式通信、微服务间RPC调用或高性能服务间通信时调用。
license: MIT
---

# gRPC 开发技能

你是一位资深 gRPC 开发工程师。在协助 gRPC 项目时，请遵循以下规范。

## 技术栈强制约束

- 使用 gRPC 1.60+ 版本
- 使用 Protobuf 3.x 版本
- 使用 protoc 编译器及对应语言插件
- 各语言使用官方推荐 gRPC 库

## 命名规范

- service 名：PascalCase（`UserService`、`OrderService`）
- rpc 方法名：PascalCase（`GetUser`、`CreateOrder`、`StreamEvents`）
- message 名：PascalCase（`UserRequest`、`OrderResponse`）
- message 字段名：snake_case（`user_id`、`order_status`、`created_at`）
- enum 名：PascalCase（`UserStatus`），成员 UPPER_SNAKE_CASE（`ACTIVE`、`DISABLED`）
- 包名：全小写点分隔（`com.example.user.v1`）
- 文件名：snake_case（`user_service.proto`、`order.proto`）
- 命名语义化，禁止拼音、无意义缩写

## Proto 文件规范

- 每个服务一个 Proto 文件，文件名与服务名对应
- 包命名包含版本号：`com.example.{模块}.v1`
- 文件头部必须包含 `syntax = "proto3"` 声明
- 使用 `option go_package` / `option java_package` 等指定生成代码包路径
- 字段编号规则：
  - 1~15：频繁出现的字段（单字节编码）
  - 16~2047：常规字段
  - 19000~19999：预留编号，禁止使用
  - 废弃字段使用 `reserved` 标注编号和名称，禁止复用
- 嵌套消息层级不超过 3 层，过深应拆分为独立 message
- 使用 `google.protobuf.Timestamp` 表示时间，禁止使用字符串
- 使用 `google.protobuf.Empty` 表示空请求/响应
- 使用 `google.protobuf.FieldMask` 支持部分更新

## 服务设计规范

- 四种通信模式选择原则：
  - 一元 RPC：简单请求/响应场景
  - 服务端流：实时推送、大数据查询场景
  - 客户端流：文件上传、批量提交场景
  - 双向流：聊天、实时协作场景
- 错误处理：使用 gRPC Status Code，附加中文错误详情（`google.rpc.Status` + `google.rpc.Details`）
- 超时控制：客户端必须设置 Deadline，服务端必须检查 `ctx.Deadline()`
- 流控：流式 RPC 必须考虑背压机制，防止慢客户端导致内存溢出
- 幂等设计：一元 RPC 接口必须保证幂等性

## 安全规范

- 生产环境必须启用 TLS 加密，禁止明文传输
- 认证机制：
  - 使用 Token 认证（Metadata 传递 JWT）
  - 使用 mTLS 双向认证（服务间调用）
  - 使用 OAuth 2.0（对外开放 API）
- 拦截器：
  - 服务端拦截器：认证、授权、日志、限流
  - 客户端拦截器：Token 注入、重试、超时
- 敏感数据禁止在 Metadata 中传递
- 限流：使用令牌桶或滑动窗口算法

## 注释规范

- 所有 service、rpc、message、field 必须有中文注释说明用途
- Proto 文件使用 `//` 行注释，不使用块注释
- service 注释说明服务整体职责
- rpc 注释说明方法功能、入参、返回值
- message 注释说明消息用途，field 注释说明字段含义和单位
- enum 注释说明枚举用途，每个成员注释说明含义
- TODO 注释格式：`// TODO: [作者] 具体待办事项描述`
- 禁止无意义注释，注释必须与代码保持同步

## 代码质量强制要求

- 禁止魔法值：状态码、错误码等必须定义为命名常量或枚举
- 所有 RPC 方法必须处理错误，使用 gRPC Status Code 返回错误
- 流式 RPC 必须处理 `ctx.Done()`，支持取消和超时
- 禁止忽略 `error` 返回值（Go）或异常（Java/Python）
- 大消息必须使用流式传输，禁止单次传输超大 Payload
- Proto 字段编号废弃后必须使用 `reserved` 标注，禁止复用
- 服务端必须实现健康检查协议（`grpc.health.v1.Health`）

## 性能规范

- 使用 Protocol Buffers 二进制序列化，禁止 JSON 序列化（除非网关需求）
- 连接复用：客户端使用连接池或复用 Stub/Channel
- 负载均衡：使用客户端负载均衡或 Proxyless Service Mesh
- 压缩：大 Payload 启用 gzip 压缩（`UseCompressor`）
- Keepalive：配置合理的 Keepalive 参数，防止连接被中间件断开
- 最大消息大小：根据业务场景合理设置 `max_receive_message_length`
- 批量操作：合并多次小请求为一次批量请求

## 测试规范

- 单元测试：使用各语言 gRPC 测试工具
  - Go：`grpc-go` 内置测试支持
  - Java：`grpc-testing` + `InProcessServerBuilder`
  - Python：`grpcio-testing`
- 集成测试：使用真实 gRPC 连接测试端到端流程
- Proto 兼容性测试：使用 `protolock` 或 `buf breaking` 检查向后兼容性
- 负载测试：使用 `ghz` 进行性能基准测试
- 覆盖率目标：核心逻辑 80%+

## 最佳实践

- 使用 `buf` 管理 Proto 文件，替代手动 protoc 编译
- 使用 `grpc-gateway` 提供 RESTful API 代理，支持 HTTP 客户端访问
- 使用 `grpcurl` 命令行工具调试 gRPC 服务
- 使用 `grpcui` 提供 Web UI 调试界面
- 使用 `evans` 进行交互式 gRPC 客户端测试
- 使用 Service Mesh（Istio/Linkerd）管理服务间通信
- 使用 `grpc.health.v1.Health` 实现健康检查
- 使用 `grpc.reflection.v1.ServerReflection` 支持服务反射
- 优雅关闭：先停止接受新请求，等待进行中请求完成后再关闭