原系统架构分析：理解现有系统接口的组成与调用方式

做系统迁移，第一件事不是写代码，而是先把老系统的接口"扒干净"。我个人习惯先画一张接口全景图，把所有对外暴露的入口标出来。你想想看，如果连自己家里有几扇门都不清楚，怎么敢动墙？

咱们这一章的目标很直接：搞清原系统接口到底长什么样。包括它用了什么协议、数据怎么包装、调用方怎么连上来、有没有认证鉴权。把这些要素拆开看，迁移时才能做到"换内芯不换接口"。

接口的四个基本组成要素

我经手过的遗留系统，接口设计五花八门。但不管多乱，底层都离不开这四个东西：

1. 传输协议 - HTTP/HTTPS、gRPC、Dubbo、AMQP 等等。决定了数据怎么"跑"到对方手里。
2. 接口端点（Endpoint） - 也就是 URI 或队列名。比如 /api/v1/order/create ，或者 queue://trade.settle 。
3. 数据格式与契约 - JSON、XML、Protobuf，以及对应的 Schema 或 IDL。迁移时最头疼的就是这个。
4. 认证与鉴权 - 、JWT、OAuth2、或者是简单的 IP 白名单。我碰上过完全没有认证的系统，迁移时反而要补安全层。

调用方式：同步？异步？混着来？

先别说迁移，你连调用模式都搞混，后面必然出事。我见过最典型的坑：开发说"我们全是同步调用"，结果线上有个 MQ 消费者在后台悄悄跑。那迁移时就漏了。

常见调用方式有三大类：

说白了，调用方式决定了你 SDK 的线程模型和阻塞策略。迁移时不光要模拟接口，还要模拟它的"行为特征"。

接口文档与契约：你的救命稻草

老系统有文档吗？有，但多半是过时的。我习惯先跑一次全链路抓包，然后用工具自动生成 OpenAPI 规范。举个例子，假设原系统有个创建订单的接口：

POST /api/order
Content-Type: application/json
Authorization: Bearer <>

{
  "userId": 12345,
  "items": [
    {"sku": "A001", "quantity": 2}
  ],
  "couponCode": "SAVE10"
}

返回：

HTTP/1.1 201 Created
{
  "orderId": "ORD20250321001",
  "totalAmount": 199.80,
  "status": "pending"
}

注意这里的 status 字段值 pending，不是 PENDING 也不是 0。这种细节很容易被忽略，但在迁移里一个字母大小写差异就能造成线上事故。

画出你的接口架构图

好了，上面分析了一堆要素。现在把它们放到一张图里，你就能看清全貌。下面这个 SVG 图展示了原系统接口的典型组成与调用关系。

归纳总结：一张接口清单就够了

分析到最后，你应该输出一张表格。我把自己的检查清单分享给你：