gRPC开发者快速入门

gRPC 开发者快速入门

精简版快速入门，只保留核心概念与上手步骤。

目录

1. 一句话了解 gRPC

gRPC 是高性能、跨语言的 RPC 框架：用 Protocol Buffers 在 .proto 里定义服务，用 HTTP/2 传输，由工具生成多语言客户端/服务端代码，让你像调本地函数一样调远程接口。

为什么用 gRPC？

• 性能好：二进制序列化 + HTTP/2 多路复用
• 强类型：.proto 即契约，编译期检查
• 自动代码生成：少写样板、多语言一致
• 支持流式：一元 / 客户端流 / 服务端流 / 双向流

2. 核心概念（4 步）

三个关键抽象：

• Channel：到服务端的逻辑连接（含解析、负载均衡、连接管理）
• Stub：客户端侧的类型安全接口，由 .proto 生成
• Service：服务端实现的业务逻辑，对应 .proto 里的 service

3. 四种 RPC 类型

4. 5 分钟上手（以 Python 为例）

4.1 安装

pip install grpcio grpcio-tools

其他语言安装：

4.2 定义服务 helloworld.proto

syntax = "proto3";
package helloworld;

service Greeter {
rpc SayHello (HelloRequest) returns (HelloReply) {}
}

message HelloRequest { string name = 1; }
message HelloReply { string message = 1; }

Proto 语法速览： 字段编号 1–15 编码更省；repeated 表示列表；optional 表示可选；常用类型有 string、int32、int64、bool、bytes。服务里用 stream 表示流式，例如 rpc StreamReply (Req) returns (stream Resp) {}。

4.3 生成代码

python -m grpc_tools.protoc -I. –python_out=. –grpc_python_out=. helloworld.proto

得到 helloworld_pb2.py（消息）和 helloworld_pb2_grpc.py（服务/存根）。

4.4 服务端（最简）

import grpc
from concurrent import futures
import helloworld_pb2
import helloworld_pb2_grpc

class Greeter(helloworld_pb2_grpc.GreeterServicer):
def SayHello(self, request, context):
return helloworld_pb2.HelloReply(message=f"Hello, {request.name}!")

server = grpc.server(futures.ThreadPoolExecutor(max_workers=10))
helloworld_pb2_grpc.add_GreeterServicer_to_server(Greeter(), server)
server.add_insecure_port("[::]:50051")
server.start()
server.wait_for_termination()

4.5 客户端（最简）

import grpc
import helloworld_pb2
import helloworld_pb2_grpc

with grpc.insecure_channel("localhost:50051") as channel:
stub = helloworld_pb2_grpc.GreeterStub(channel)
reply = stub.SayHello(helloworld_pb2.HelloRequest(name="World"))
print(reply.message) # Hello, World!

4.6 运行

先起服务端，再在另一终端跑客户端。生产环境请使用 TLS 与正式凭据。

5. 错误处理与超时

错误与状态码： 每次 RPC 返回一个 Status（或语言等价物）。常见码：OK、CANCELLED、DEADLINE_EXCEEDED、UNAVAILABLE、UNAUTHENTICATED、PERMISSION_DENIED、NOT_FOUND、INVALID_ARGUMENT 等。客户端应检查 status.ok() 或捕获异常后再使用响应。

超时（deadline）： 建议每次调用都设超时，避免挂死。例如 Python：response = stub.SayHello(request, timeout=10)；或在 context/metadata 里设置 deadline。

取消： 支持对进行中的 RPC 取消，客户端取消后服务端会收到取消信号，可做清理。

6. 元数据（Metadata）

元数据是键值对，随请求/响应传递，不写在 .proto 里。典型用途：认证 token、trace-id、请求来源、自定义头。

• 客户端发元数据：在调用前往 context 里塞入（如 metadata = [('key', 'value')]，再传给 stub）。
• 服务端读/写：从 context.invocation_metadata() 读请求元数据；通过 context.send_initial_metadata() 等回写响应元数据。

7. 同步 vs 异步

• 同步：调用阻塞直到拿到响应，写法简单，适合请求不多、逻辑顺序清晰的场景。
• 异步：非阻塞，通过回调或 Future/async 获取结果，适合高并发、多 RPC 并发。各语言都有异步 API（如 C++ 的 CompletionQueue/Callback、Python 的 grpc.aio）。

先掌握同步即可上手，有性能需求再上异步。

8. 安全速览

• 开发/内网：可用 insecure_channel / InsecureServerCredentials 快速跑通。
• 生产：必须用 TLS（SslCredentials / SslServerCredentials），校验证书。需要双向认证时用 mTLS（客户端也出示证书）。
• 应用层认证：在元数据里带 token，或使用 CallCredentials（如 JWT、OAuth2），与 ChannelCredentials 组合使用。

9. 特性一览（记住这些就够了）

10. 何时用 / 何时不用

适合 gRPC： 微服务间通信、强契约与代码生成、流式或实时、多语言互操作。

可考虑 REST： 面向浏览器的公开 API、简单 CRUD、强依赖 HTTP 缓存与生态。

11. 常见问题

提示： 不同语言的服务端和客户端可以互连（如 Go 服务端 + Python 客户端），只要共用同一份 .proto 定义即可。

12. 下一步

• 官方：grpc.io — 各语言教程与 API 参考。
• 示例：grpc 仓库 examples/（如 examples/python/helloworld、examples/cpp/helloworld、examples/node）。