1. 原系统接口协议概述
咱们做迁移适配，第一件事是搞清楚「原系统到底在用啥协议」。
说白了，接口协议就是两套系统商量好的「沟通暗号」。你按我这个格式发请求，我就能懂；我按那个格式回响应，你就能用。格式不对，鸡同鸭讲。
我记得刚入行那会儿，对接一个老系统，对方丢过来一句「我们走SOAP」。我当时一脸懵，心想这不就是个XML发数据嘛，有啥好说的？结果一上手，命名空间、WSDL、信封结构……折腾了两天才调通。嗯，从那以后我就明白了——协议不只是数据格式，它决定了你怎么建客户端、怎么处理错误、怎么升级。
为什么先要懂协议？
迁移SDK的时候，你不可能把所有代码重写一遍。你得像做翻译一样——理解原系统用REST还是gRPC，然后把请求、响应、错误码、认证方式统统映射到新SDK的接口上。
我建议不要一开始就扎进代码。先画张图：
- 原系统有哪些外部接口？
- 每个接口用的是什么协议？
- 协议版本是多少？
- 有没有自定义的扩展？
这一步做扎实，后面踩坑就会少很多。
常见协议一览
我在项目中见过的协议，主流就这四种：
| 协议 | 传输格式 | 典型场景 | 我个人的第一印象 |
|---|---|---|---|
| REST | JSON / XML | Web API、移动端后端 | 最简单，入门快，但规范容易被滥用 |
| gRPC | Protobuf (二进制) | 微服务内部、高吞吐场景 | 性能好，但上手有门槛 |
| Thrift | Thrift Binary / Compact | 跨语言、多语言异构系统 | Facebook出品，灵活但生态散 |
| SOAP | XML (带WSDL) | 金融、银行、企业服务总线 | 老派但严谨，兼容性噩梦 |
REST：最常见，也最容易被误解
REST不是协议，是一种架构风格。但大家都把它当协议用了。
特点：
- 基于HTTP，用GET/POST/PUT/DELETE映射CRUD
- 资源用URI表示，状态码告诉你结果
- 无状态——这一点很重要
我曾在一个项目里见过「REST API」用GET请求去删除用户，参数塞在URL里……嗯，那其实已经不是REST了，顶多算「HTTP隧道」。做迁移适配时，要特别注意原系统是不是真的遵循REST语义。如果不是，你的SDK就不能假设它有标准的资源模型。
gRPC：高性能，但理解成本高
gRPC用Protobuf做IDL，数据序列化后是二进制，比JSON小很多。特别适合内部服务间调用——延迟敏感、吞吐量大的场景。
特点：
- 强类型：接口定义即契约
- 支持双向流、客户端流、服务端流
- 默认基于HTTP/2
但是—— 你想想看，如果原系统用了gRPC streaming，你的新SDK必须支持同样的流式语义，而不是简单发一个请求等一个响应。我亲手踩过这个坑：以为gRPC都是「一问一答」，结果对接流式接口时，客户端直接挂死。后来老老实实读了.proto文件里的stream关键字。
Thrift：多语言的「缝合怪」
Thrift是跨语言RPC框架。你写一个.thrift文件，它能生成Java、Python、C++等各种语言的客户端和服务端代码。
适用场景：
- 团队用多种语言开发
- 需要同一套接口描述跑在不同语言上
我个人觉得Thrift的优点是灵活——你可以选Binary、Compact、JSON等多种传输协议。但缺点也在这：每个公司的Thrift用法可能都不一样。有的用TBinaryProtocol，有的用TCompactProtocol。迁移SDK时，必须搞清楚原系统用的是什么子协议。
SOAP：老当益壮，别随便动它
SOAP用XML做消息格式，WSDL做接口描述。它很重，但也很严谨。安全性、事务、可靠性……SOAP都给你考虑好了。
适用场景：
- 金融机构、政府部门
- 需要严格契约和复杂安全机制的场景
我曾经要迁移一个SOAP接口到RESTful SDk。原系统有十几个命名空间，XML结构嵌套了四层。最麻烦的是——SOAP消息里带数字签名，改了XML结构，签名就失效了。所以迁移SOAP系统，不能简单做报文转换，得先理解它的安全模型。
怎么选？看场景
没有最好的协议，只有最合适的。我做迁移适配时，一般先问三个问题：
- 原系统是内部系统还是外部开放接口？ 内部多用gRPC或Thrift，外部多用REST或SOAP。
- 性能要求有多高？ 如果是实时交易，gRPC的二进制优势明显；如果是CRUD后台，REST完全够用。
- 团队熟悉什么？ 这一点容易被忽略。我建议优先考虑团队能驾驭的协议，而不是性能最好的。
一张图看懂协议关系
下面这张SVG图总结了四种协议的核心链路。你可以看出它们对应不同的传输层和数据格式，但最终都是为了实现「客户端 → 服务端」的远程调用。
总结本章重点
- 接口协议是系统间沟通的契约，决定了数据格式、调用方式、错误处理。
- REST最普遍，但要注意它是不是真的「RESTful」，还是只是「HTTP + JSON」。
- gRPC优势在高性能，但流式语义是难点。
- Thrift跨语言方便，但子协议多，容易混淆。
- SOAP虽老，但在金融领域仍是主力，迁移时必须尊重它的安全模型。
- 开始适配前，一定要彻底摸清原系统的协议栈——这一步省不得。