📚 课程目录第3章 API规范与协议选择

API 规范与协议选择：RESTful API、gRPC、消息队列等对 SDK 的影响

做 SDK 这么多年，我最深的体会就是：协议选错了，后面全是坑。你想想看，SDK 本质上就是封装通信细节的工具，底层走的是 REST、gRPC 还是消息队列，直接决定了你的代码长什么样、多语言怎么对齐、性能能不能扛住。

我记得刚入行时接手一个 Java SDK，底层是 HTTP+JSON。那时觉得挺好，直到客户说「我们需要百万并发」……嗯，后来改 gRPC 改得头皮发麻。所以这一章咱们就掰扯清楚：三种主流协议对 SDK 设计到底有哪些影响。

1. RESTful API：最通用的选择，但要注意「胖 SDK」陷阱

RESTful 可以说是门槛最低的协议。HTTP 动词 + JSON 体，几乎所有语言都能用。我个人习惯在跨语言 SDK 首选 REST，因为客户端实现简单，调试也方便。

但是——REST 的 SDK 很容易变成「胖客户端」。

序列化开销：JSON 解析在大流量下是瓶颈。Java 用 Jackson，Python 用 ujson，Go 用 encoding/json，每个版本都得对齐。
错误处理：HTTP 状态码 + 自定义错误体，不同语言解析起来千奇百怪。我曾经在 Python 的 SDK 里漏判了一个 429，导致客户被限流了还不知道。
版本管理：URL 路径 /v1/、/v2/ 虽然直观，但升级时 SDK 得兼容两套逻辑。

我的建议：RESTful 适合 对外公开 API 或 语言种类多但请求量不大 的场景。如果你要包一层 SDK，记得把 HTTP 客户端做成可插拔的，方便后续换协议。

2. gRPC：高性能之王，但语言绑定有代价

gRPC 基于 HTTP/2 和 Protobuf，性能甩 REST 几条街。说白了，它就是为微服务间通信设计的。你只需要写一个 .proto 文件，然后 protoc 一跑，Java、Python、Go 的桩代码全出来了。

这里有个细节：gRPC 的 SDK 生成代码往往带有很多框架依赖。比如 Java 的 gRPC 依赖 Netty，Python 依赖 grpcio 的 C 扩展，Go 依赖 google.golang.org/grpc。如果你的 SDK 用户对依赖非常敏感（比如 Android、嵌入式环境），那就要小心了。

流式通信：gRPC 支持 server streaming、client streaming、双向流。SDK 里暴露一个 StreamObserver 或 async generator，对用户来说上手成本较高。
负载均衡：gRPC 自带负载均衡策略（round_robin、pick_first），SDK 内部要处理好连接池，否则频繁建连性能反而差。
跨语言兼容：Protobuf 的字段编号、枚举值、oneof 在不同语言中行为一致，这是 gRPC 的天然优势。

注意：我曾经踩过一个坑——gRPC 默认对消息大小有限制（4MB）。如果业务数据体量大，记得在 SDK 里放开 maxReceiveMessageSize，否则客户端会悄悄丢包。

3. 消息队列：异步解耦，但 SDK 设计思路完全不同

如果 API 不需要实时响应，或者你需要削峰填谷，消息队列是更好的选择。Kafka、RabbitMQ、Pulsar 各自有客户端 SDK，但设计模式大相径庭。

消息结构：消息队列 SDK 通常需要用户定义 topic/queue、序列化方式（Avro、Protobuf、JSON），还要处理 ACK 与重试。
连接管理：长连接 + 心跳 + 消费者组再平衡，这些逻辑写进 SDK 里远比 HTTP 复杂。我见过很多 SDK 在消费者组重平衡时丢消息，就是因为 rebalance listener 没实现好。
异步 vs 阻塞：Java 的 Kafka 客户端提供同步和异步两种接口，Python 的 confluent_kafka 是回调模式，Go 的 sarama 默认协程阻塞。SDK 设计者必须想好：是暴露底层模式，还是统一封装成 Future/Callback？

其实消息队列的 SDK 最难的不是写逻辑，而是想清楚「谁来保证最终一致性」。是让用户自己处理重试和幂等，还是 SDK 内部做？我倾向于让 SDK 提供可配置的重试策略，但不做自动幂等——避免黑盒行为。

一句话总结：REST 省心，gRPC 高效，消息队列解耦。但没有银弹。

4. 核心对比：一句话看懂差异

维度	RESTful API	gRPC	消息队列
通信模型	请求-响应（同步）	请求-响应 / 流式	发布-订阅 / 点对点
序列化	JSON/XML（文本，自描述）	Protobuf（二进制，紧凑）	可配置（Avro/Proto/JSON）
性能	一般（解析开销大）	高（二进制+HTTP/2）	高（异步批处理）
SDK 代码量	小（手动封装）	中（protoc 生成后仍需封装业务逻辑）	大（需管理连接、重试、ACK）
多语言对齐难度	易（JSON 通用）	易（proto 文件是单源）	中（不同语言客户端行为差异大）
适用场景	公开 API、轻量集成	微服务间通信、高并发	异步任务、事件驱动

5. 协议如何影响 SDK 的分层设计

不管选哪种协议，SDK 内部都可以抽象出几层，但每层的重心不同。

传输层：REST 用 HTTP Client（OkHttp、requests、net/http），gRPC 用 Channel/Connection，消息队列用 Producer/Consumer 客户端。这一层要支持重试、超时、连接池。
序列化层：REST 的 JSON 序列化可配置（jackson/gson/orjson），gRPC 固定 Protobuf，消息队列通常自带序列化（Kafka 的 Serializer/Deserializer）。
业务层：这是 SDK 的价值所在。不管底层是什么协议，对外暴露的接口应该尽量一致，比如 sendMessage()、getUser()。业务层与协议耦合越低，以后换协议的成本就越低。

实战经验：我曾在同一个 SDK 内同时支持 REST 和 gRPC 两种传输模式。做法很简单：定义一个抽象的 Transport 接口（Java 里用 interface，Go 里用 interface，Python 里用 ABC），然后把序列化器和业务逻辑都依赖这个接口。这样用户传一个 TransportType.REST 或 TransportType.GRPC 就能切换。

核心原则：协议影响的是传输和序列化，不应该污染业务接口。保持 SDK 的「协议无关」设计，你后续维护会轻松很多。

6. 避坑指南：协议切换时的常见问题

我在项目中遇到过三次「协议迁移」的决策，每次都有人反对。这里把共性的坑列出来：

不要一刀切：同一个 SDK 可以同时支持 REST 和 gRPC，但要给用户明确的选择。我曾经见过一个团队把 REST 接口全删了，结果上游客户还在用 curl 测试，直接报 404。
注意连接生命周期：gRPC 和消息队列的客户端通常是长连接，用完后必须关闭。我在 Python 的 SDK 里忘了 channel.close()，导致进程退出时僵尸线程卡了 30 秒。
序列化版本兼容：Protobuf 的 field 编号一旦发布就不能改！如果你要废弃一个字段，记得用 reserved 关键字。Avro 和 JSON Schema 同理。
流式处理的背压：gRPC 的流如果消费端处理慢，服务端会堆积或超时。SDK 里最好提供流控选项，比如 FlowControl 或 maxOutstandingMessages。

曾经有个项目：客户要求支持 Kafka 和 Pulsar 两种消息队列，我们觉得抽象一层就能搞定。结果 Pulsar 的 consumer 没有同步 offset 的概念，导致我们的重试逻辑在 Kafka 上正常、在 Pulsar 上疯狂重复消费。最后不得不把「offset 管理」抽离成插件——协议差异永远比你想的多。

总结一下：协议选择考验的是你对场景的理解和对 SDK 抽象能力的把握。别怕选错，怕的是写死了换不动。只要你把传输层和序列化层藏好，业务层就能稳稳地活到下一个协议流行的那天。