software

实现 gRPC

发布: (2026年2月6日 GMT+8 06:06)
6 min read
原文: Dev.to

I’m ready to translate the content, but I don’t see the text you’d like me to translate—only the source link. Could you please provide the article or the specific passage you want translated? Once I have the text, I’ll keep the source line unchanged and translate the rest into Simplified Chinese for you.

Core Principles

  • Protocol Buffers – gRPC 使用 Protocol Buffers 进行序列化，能够实现高效的二进制编码。这会减小消息体积并降低解析开销，从而加快通信速度。
  • Strong‑typed contracts – API 使用 .proto 文件定义，指定服务、方法和数据类型。这在客户端和服务器之间创建一致的接口，降低错误风险。
  • Bi‑directional streaming – 客户端和服务器可以同时交换消息，这在大规模或实时数据传输时尤为有用。
  • Language‑agnostic – 官方支持 C++、Java、Python、Go 等多种语言，使团队能够在不担心兼容性的情况下选择最合适的语言。

典型使用场景

  • 高性能应用
  • 微服务架构
  • 实时或流式工作负载
  • 带宽受限的移动/物联网通信

gRPC 是面向性能、可扩展 API 的分布式系统的极佳选择。它非常适合具备底层编程和网络通信经验的团队，能够实现快速、可靠的 API。

gRPC vs. REST 比较

方面gRPCREST
协议HTTP/2HTTP/1.1（或 HTTP/2）
消息格式Protocol Buffers（二进制）JSON、XML（文本）
性能⚡ 更快（二进制序列化）较慢（文本解析）
负载大小更小（约 3–10 倍）较大
延迟更低更高
带宽使用更低更高
代码生成自动（基于 .proto 文件）手动或基于模板
浏览器支持有限（需 gRPC‑Web）原生支持
API 风格RPC（函数调用）面向资源（URI）
URL 路由Service.MethodRESTful 路径（/resource/id）
HTTP 方法所有请求均使用 POSTGET、POST、PUT、DELETE、PATCH
缓存较难（需自定义逻辑）内置（HTTP 缓存）
流式传输双向流式传输仅请求‑响应
连接方式持久（多路复用）每次请求
学习曲线较陡较平缓
生态系统正在成长成熟且已建立
文档代码生成（proto）手动编写
调试较难（二进制格式）较易（JSON 可读）
移动友好性良好非常好
IoT/边缘计算出色良好
实时特性出色（流式）有限
拦截器/中间件内置手动实现
错误处理标准化（gRPC 状态码）HTTP 状态码
认证JWT、OAuth、证书OAuth、API Key、JWT
使用场景微服务、实时、移动公共 API、Web 服务

快速入门示例

# Clone the repository
git clone https://github.com/your-org/aquaworld-grpc.git
cd aquaworld-grpc

# Build and run the server
mvn clean install
mvn spring-boot:run

预期服务器输出

🐠 ==========================================
🐠 AquaWorld 宠物店 gRPC API
🐠 ==========================================
🐠 gRPC 服务器已在端口 9090 启动
🐠 使用 grpcurl 测试：grpcurl -plaintext localhost:9090 list
🐠 ==========================================

使用 grpcurl 进行测试

# macOS
brew install grpcurl

# Linux (requires Go)
go install github.com/fullstorydev/grpcurl/cmd/grpcurl@latest
# 列出可用服务
grpcurl -plaintext localhost:9090 list

预期结果

com.aquaworld.grpc.auth.AuthService
com.aquaworld.grpc.order.OrderService
com.aquaworld.grpc.payment.PaymentService
com.aquaworld.grpc.product.ProductService
grpc.reflection.v1.ServerReflection
grpc.reflection.v1alpha.ServerReflection

请参阅仓库的 README 以测试其余功能。

通过 Proto 包进行版本控制

  • 推荐方法：使用 .proto 文件中的 package 名称对 API 进行版本化（例如，package aquaworld.v1;）。

最佳实践

字段编号

  • 绝不重复使用 已分配的字段编号。
  • 不要删除 字段；请改为将其标记为 deprecated。

状态码

CodeMeaning
OK成功
INVALID_ARGUMENT客户端发送了无效数据
NOT_FOUND资源不存在
ALREADY_EXISTS资源重复
PERMISSION_DENIED授权失败
UNAVAILABLE服务暂时不可用

避免为客户端错误返回 UNKNOWN 或 INTERNAL。

丰富错误详情

  • 使用 gRPC trailers 发送结构化错误元数据，以便在客户端实现程序化处理。

截止时间与超时

  • 始终设置截止时间（context.WithDeadline），以定义客户端等待响应的最长时间。

重试

  • 有意识地实现重试；只有在配合幂等操作和适当的退避策略时，重试才会提升系统弹性。

负载均衡

  • HTTP/2 的长连接会改变负载均衡的动态。使用支持 gRPC 的负载均衡器（例如 Envoy、gRPC‑LB）来有效分发流量。

Summary of Advantages

  • 高性能和低延迟
  • 高效的移动/物联网通信
  • 实时双向流式传输
  • 适用于微服务和内部 API
  • 最小化带宽使用

这些特性使 gRPC 成为现代性能关键的分布式系统的有力候选者。

Back to Blog

相关文章

阅读更多 »