[!info] related notes

• 父级地图: Backend Engineering MOC、Backend Architecture MOC
• 子主题地图: GraphQL MOC、gRPC MOC、前后端实时通信、Messaging & Queues MOC、MCP MOC
• 关键契约: OpenAPI 与 Swagger、GraphQL Schema

应用通信架构 MOC

知识总览

filters:
  and:
    - 'file.ext == "md"'
    - 'file.inFolder("z")'
    - 'this.file.links.contains(file)'
    - 'file.path != this.file.path'
formulas:
  knowledge: 'file.asLink(title)'
properties:
  formula.knowledge:
    displayName: 知识
  note.description:
    displayName: Description
  note.mastery:
    displayName: Mastery
views:
  - type: table
    name: 知识总览
    order:
      - formula.knowledge
      - note.description
      - note.mastery
    columnSize:
      formula.knowledge: 280
      note.description: 760
      note.mastery: 56

覆盖范围

这张地图解决的不是“哪一种协议最好”，而是：系统中的两端为什么要通信、谁主动发起、是否需要立即响应、是否需要持续推送、是否允许异步、契约怎样描述，以及失败后是否需要重试/回放。

不要把 REST、GraphQL、gRPC、WebSocket、SSE、Kafka、MCP 全部当成同一层的竞争技术。它们解决的是不同问题，可以同时出现在同一个系统中。

应用通信
│
├─ 同步 Request / Response API
│  ├─ REST
│  ├─ GraphQL
│  └─ RPC
│     ├─ gRPC
│     ├─ Connect RPC
│     ├─ JSON-RPC
│     └─ tRPC
│
├─ 实时 / Streaming
│  ├─ SSE
│  ├─ WebSocket
│  ├─ GraphQL Subscription
│  ├─ Polling / Long Polling
│  └─ WebRTC DataChannel
│
├─ 异步通知 / 事件
│  ├─ Webhook
│  └─ Message / Event Broker
│     ├─ Kafka
│     ├─ RabbitMQ / AMQP
│     └─ MQTT
│
├─ 契约描述
│  ├─ REST / HTTP → OpenAPI
│  ├─ GraphQL → GraphQL Schema
│  ├─ gRPC → Protobuf / .proto
│  └─ Event-driven API → AsyncAPI
│
└─ Agent 能力接入
   └─ MCP

第一判断：这次通信属于哪一种语义

1. 同步请求 / 响应

调用方发起请求，并希望直接得到结果：

Client → Request → Server
Client ← Response ← Server

典型方案：

• RESTful API：Resource-oriented，默认 Web/API 方案；
• GraphQL MOC：Data/Graph-oriented，客户端声明字段组合；
• gRPC：Procedure-oriented，调用远程方法，常用于服务间通信；
• tRPC：TypeScript 全栈中的端到端类型 RPC；
• Connect RPC：基于 Protobuf 的现代 RPC，兼顾浏览器与 gRPC 生态；
• JSON-RPC：轻量方法调用协议；
• SOAP：传统企业 Web Service；
• OData：标准化、可查询的 RESTful 数据 API。

最重要的三种心智模型：

REST
→ Resource-oriented
→ “操作哪个资源？”

GraphQL
→ Data-oriented
→ “这次我要数据图中的哪些字段？”

gRPC / RPC
→ Procedure-oriented
→ “我要调用哪个远程方法？”

第二判断：服务器是否需要主动持续推送

如果客户端不能只靠“请求一次、响应一次”得到完整结果，就进入实时/Streaming 分支。

详见 前后端实时通信。

SSE

Client → 建立 HTTP 连接
Server → event
       → event
       → event

适合：

• LLM token streaming；
• Agent event stream；
• 任务状态/日志；
• 单向实时通知。

详见 SSE。

WebSocket

Client ⇄ Server

适合：

• 实时协作；
• 双向聊天；
• 游戏；
• 高频交互状态。

详见 WebSocket。

GraphQL Subscription

Subscription 是 GraphQL 的实时 operation 语义，不等于 WebSocket 本身：

GraphQL Subscription
→ 描述订阅什么

WebSocket / other transport
→ 数据怎样持续传输

详见 GraphQL Subscriptions。

第三判断：调用方是否需要等待结果

如果生产者不应该等待消费者立即处理，就更适合异步消息/事件。

Webhook

System A 发生事件
→ HTTP callback
→ System B

典型：支付成功、GitHub push、第三方 SaaS 回调。

Webhook 仍然使用 HTTP，但交互语义从“调用方来查询”变为“事件发生后被调用方主动通知”。

Message Queue / Event Streaming

详见 Messaging & Queues MOC。

Producer
   ↓
Broker
   ├→ Consumer A
   ├→ Consumer B
   └→ Consumer C

常见：

• Apache Kafka：持久事件流、partition、consumer group、重放；
• RabbitMQ：队列、Exchange、路由、ACK、任务分发；
• MQTT：IoT 场景中的轻量 Pub/Sub。

对比可见 Kafka 与 RabbitMQ 的选型边界。

第四判断：契约放在哪里

通信方式不仅要回答“怎么传”，还要回答“双方如何知道消息长什么样”。

通信模型	常见契约
REST / HTTP API	[[openapi-swagger
GraphQL	[[graphql-schema
gRPC	Protobuf / .proto
Event-driven / Message API	AsyncAPI
tRPC	TypeScript 类型推导

契约与 transport 不是同一个概念：

OpenAPI
≠ REST transport

GraphQL Schema
≠ HTTP

Protobuf
≠ gRPC transport 本身

第五判断：是否是在给 AI / Agent 暴露能力

MCP 不应该被理解成 REST、GraphQL 或 gRPC 的直接替代品。

它解决的是：

AI Host / Agent
   ↓ discover
Tools / Resources / Prompts
   ↓ invoke
MCP Server

MCP Server 背后的真实业务系统仍可能通过：

REST
GraphQL
gRPC
Database
CLI
local filesystem

工作。

因此 MCP 属于 Agent 能力接入层，而 REST/GraphQL/gRPC 更多属于应用 API / 服务通信层。

详见 MCP MOC。

不要混淆的五个层次

1. API 语义
   REST / GraphQL / RPC

2. Transport / 实时连接
   HTTP / SSE / WebSocket

3. 异步消息与事件传播
   Webhook / Kafka / RabbitMQ / MQTT

4. Contract / IDL
   OpenAPI / GraphQL Schema / Protobuf / AsyncAPI

5. Agent 能力协议
   MCP

同一个产品可以同时使用所有层次。

一个现代系统可能怎样组合

Browser / Mobile
      │
      ├─ REST / GraphQL
      │
      ├─ SSE / WebSocket
      │
      ▼
API / BFF / Gateway
      │
      ├─ gRPC → internal service
      ├─ REST → external service
      └─ publish event
             ↓
       Kafka / RabbitMQ
             ↓
        Worker / Analytics

External SaaS
      ↓ Webhook
Backend

AI Agent
      ↓ MCP
Tool Gateway
      ↓
REST / gRPC / DB / CLI

关键是：这些不是互相排斥的选项，而是不同边界上的组合。

快速选型规则

需求	优先考虑
普通 Web CRUD / Public API	REST + OpenAPI
页面关系数据复杂、客户端字段组合差异大	GraphQL
内部微服务、强契约、跨语言、高性能	gRPC / Protobuf
TypeScript 前后端一体、内部产品	tRPC
Server → Browser 单向流	SSE
Browser ↔ Server 高频双向实时通信	WebSocket
GraphQL 应用中的实时实体变化	GraphQL Subscription
第三方系统事件回调	Webhook
服务解耦、任务异步处理	RabbitMQ / Message Queue
持久事件流、重放、多个消费者	Kafka
IoT / 低带宽 Pub/Sub	MQTT
AI Agent 发现并调用工具	MCP

选型时真正应该问的问题

不要先问：

“REST、GraphQL 和 gRPC 哪个最好？”

应该依次问：

1. 谁主动发起？Client、Server 还是 Event Producer？
2. 调用方需要立即拿结果吗？
3. 是一次结果，还是持续 Streaming？
4. 单向还是双向？
5. 是否需要跨语言强契约和 codegen？
6. 是否需要跨服务解耦？
7. 事件是否必须持久化、重试、重放？
8. Browser 是否必须直接支持？
9. 这是普通应用 API，还是 Agent 工具能力边界？

答案会自然缩小方案空间。

当前工程定位速记

REST
→ Web/API 默认基线，最普遍

GraphQL
→ 主流但更专项，复杂客户端数据图强

gRPC
→ 服务间 RPC 主力之一，浏览器不是最自然入口

SSE
→ 单向 Streaming，AI/Agent 应用非常重要

WebSocket
→ 双向实时通信

Webhook
→ 跨系统事件回调

Kafka / RabbitMQ
→ 后端异步与事件系统

SOAP
→ 传统企业/遗留系统仍存在

MCP
→ Agent 工具接入层，不取代应用 API

推荐学习路径

HTTP 基础
  ↓
REST + OpenAPI
  ↓
GraphQL
  ↓
SSE + WebSocket
  ↓
gRPC + Protobuf
  ↓
Webhook
  ↓
Message Queue / Kafka / RabbitMQ
  ↓
Event-driven Architecture
  ↓
MCP / Agent Tool Protocol

对于 AI 全栈 / Agent 工程，重点优先级：

REST / HTTP            ★★★★★
SSE                    ★★★★★
GraphQL                ★★★★☆
gRPC / Protobuf        ★★★★☆
WebSocket              ★★★★☆
Webhook                ★★★★☆
Kafka / RabbitMQ       ★★★★☆
MCP                    ★★★★★
SOAP / OData           ★★☆☆☆

相邻知识地图

• Backend Engineering MOC
• Backend Architecture MOC
• GraphQL MOC
• gRPC MOC
• 前后端实时通信
• Messaging & Queues MOC
• MCP MOC