gRPC开发者快速入门

gRPC 开发者快速入门

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

目录

  1. [一句话了解 gRPC](#一句话了解 gRPC)
  2. [核心概念(4 步)](#核心概念(4 步))
  3. [四种 RPC 类型](#四种 RPC 类型)
  4. [5 分钟上手(以 Python 为例)](#5 分钟上手(以 Python 为例))
  5. 错误处理与超时
  6. 元数据(Metadata)
  7. [同步 vs 异步](#同步 vs 异步)
  8. 安全速览
  9. 特性一览
  10. [何时用 / 何时不用](#何时用 / 何时不用)
  11. 常见问题
  12. 下一步

1. 一句话了解 gRPC

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

为什么用 gRPC?

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

2. 核心概念(4 步)

步骤 做什么
1. 定义服务 在 .proto 里写 service、rpc、message
2. 生成代码 用 protoc + gRPC 插件生成目标语言代码
3. 实现服务端 实现生成的 Service 接口,监听端口
4. 写客户端 建 Channel → 拿 Stub → 调用 RPC

三个关键抽象:

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

3. 四种 RPC 类型

类型 请求 响应 典型场景
一元 1 个 1 个 普通 API 调用
服务端流式 1 个 流 推送、大结果集
客户端流式 流 1 个 上传、批处理
双向流式 流 流 聊天、实时双向

4. 5 分钟上手(以 Python 为例)

4.1 安装

bash 复制代码
pip install grpcio grpcio-tools

其他语言安装:

语言 命令
Go go get google.golang.org/grpc
Node.js npm install @grpc/grpc-js
Java Maven: io.grpc:grpc-netty-shaded 等
C# dotnet add package Grpc.Net.Client
Ruby gem install grpc

4.2 定义服务 helloworld.proto

protobuf 复制代码
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 生成代码

bash 复制代码
python -m grpc_tools.protoc -I. --python_out=. --grpc_python_out=. helloworld.proto

得到 helloworld_pb2.py(消息)和 helloworld_pb2_grpc.py(服务/存根)。

4.4 服务端(最简)

python 复制代码
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 客户端(最简)

python 复制代码
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. 特性一览(记住这些就够了)

能力 说明
协议 HTTP/2 + Protocol Buffers
负载均衡 调用级,内置 round_robin、pick_first 等
安全 TLS/mTLS、CallCredentials(如 JWT)
超时与取消 每次调用可设 deadline,支持取消
元数据 键值对,随请求/响应传递
通道状态 IDLE → CONNECTING → READY → TRANSIENT_FAILURE → SHUTDOWN

10. 何时用 / 何时不用

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

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


11. 常见问题

现象 可能原因 处理
端口已被占用 本机已有进程占用该端口 换端口或结束占用进程
连接被拒绝 / Connection refused 服务端未起或地址/端口错误 先启动服务端,检查 host:port
超时 / DEADLINE_EXCEEDED 网络慢或服务端未响应 加大 timeout,检查服务端逻辑与网络
跨语言调用失败 协议版本或 .proto 不一致 保证两端用同一 .proto 定义并重新生成代码

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


12. 下一步

  • 官方 :grpc.io --- 各语言教程与 API 参考。
  • 示例 :grpc 仓库 examples/(如 examples/python/helloworld、examples/cpp/helloworld、examples/node)。
相关推荐
码事漫谈8 小时前
以后人人都可以成为导演
后端
Resean02238 小时前
Spring 源码分析(二)配置类的解析与扫描
java·后端·spring
一只爱撸猫的程序猿8 小时前
五周、两个开源仓库、九次拦截之后:AI 时代程序员缺的到底是什么
人工智能·后端·开源
ShineWinsu9 小时前
对于Qt:QFormLayout常见属性以及方法的解析
开发语言·c++·qt·面试·客户端·表单·qformlayout
kyle~9 小时前
嵌入式 SoC 系统
linux·c++·嵌入式·计算系统
北城笑笑9 小时前
Vue 110 ,若依SSE流式接口限次空500排查与解决
前端·javascript·vue.js·后端·vue
ServBay10 小时前
Local harness 将退役,VS Code 本地开发要不要搬到云端?
后端·ai编程·visual studio code
ashiho10 小时前
【LeetCode hot 100】3. 无重复字符的最长子串 (三种解法)
java·数据结构·后端·算法·leetcode·滑动窗口
张一凡9311 小时前
你的 AGENTS.md,真的管到模型写代码了吗?
前端·后端·agent
00后程序员11 小时前
iOS 实时活动怎么开发,Windows 上用 KXBuild 和 ActivityKit 写灵动岛
后端·ios