笔者近期参与了一个开源项目的建设：HiMarket。这个开源项目旨在帮助开发者，尤其是企业快速实现私有的 AI 开放平台，专注在对外提供 API 和 MCP 服务的管理上。因此，借此机会对主流 API 协议的功能和应用场景进行了梳理，以厘清容易混淆的概念。

API（Application Programming Interface，应用程序编程接口），顾名思义，是用来连接不同软件系统，以实现数据交互和服务共享的作用。构成上，它是一组规定或协议，定义了不同应用或组件之间，相互交互的方法。用三个关键词来定义 API 的核心能力，就是：定义规则、解耦系统、提升复用性。

广义上，我们也可以把 API 视为一种中间件，允许开发者访问和使用某些功能或数据，而无需了解背后的详细实现，从而降低软件系统的复杂度。例如，阿里云提供的 OpenAPI，就是提供给开发者的一系列应用程序编程接口，帮助开发者可以通过 API 的方式，来管理云上的资源、数据和服务等。

随着软件形态和应用场景的丰富，API 的种类也在不断被丰富。从最早的重量级 SOAP，到 Web 世界流行的 RESTful API，再到大模型语境下的流式 API，每一种新类型的出现都对应了新型软件形态下的不同工程解法。本文旨在对主流的 API 定位、功能、应用场景进行梳理，帮助开发者对 API 协议有一个全貌了解。

不同的视角，会有不同的分类方式。本文从应用场景，对 API 作了6种分类。

一、应用广泛的 RESTful API

REST（Representational State Transfer）是当下最广泛使用的架构风格，它基于 HTTP 协议，定义了一组设计约束和理念，他的核心思想是：一切都是资源（Resource），通过统一的接口来操作这些资源。并用 URL 来表示资源，用 HTTP 方法（GET/POST/PUT/DELETE）来定义操作。基于 REST 来构建的 API，我们称之为 RESTful API。

在 Web 世界里，资源通常对应一个 URL。例如：

• https://api.example.com/users/123 → 代表一个用户资源
  
• https://api.example.com/orders/456/items → 代表订单里的商品资源

这就像物理世界里，每一个门牌号都能唯一指向一间房子。最常见的开放平台，例如微信、支付宝、高德等开放平台，对外提供的 API 服务就是 RESTful 的。

优势

• 直观易懂：URL 就是资源，HTTP 方法就是操作，GET/POST/PUT/DELETE 的语义清晰。
  
• 无状态性：每个请求都独立携带上下文，服务端不用记住客户端的状态，这使得扩展性更好。
  
• 标准化：基于 HTTP 协议，充分复用现有的基础设施（缓存、代理、负载均衡等）。
  
• 跨语言：JSON/XML 等文本格式，使得不同语言都能轻松解析。
  

如何工作

一次典型的 REST 调用，分成客户端请求和服务端响应两个部分：

客户端请求包含什么

• URL：标识资源，例如 /users/123
  
• HTTP 方法：定义操作，例如 GET 查询、PUT 更新
  
• Headers：附加信息，比如内容格式（Content-Type: application/json）、认证令牌（Authorization: Bearer ...）
  
• 请求体（Body）：对于 POST/PUT 请求，通常包含 JSON 数据
  

请求示例：

POST /users HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer <token>

{
  "name": "望宸",
  "role": "engineer"
}

服务端响应包含什么

• 状态码：告知结果，例如 200 OK、201 Created、404 Not Found
  
• Headers：响应的元数据，例如缓存策略、返回数据格式
  
• 响应体（Body）：通常是 JSON，携带资源内容
  

响应示例：

HTTP/1.1201 Created
Content-Type: application/json

{
  "id": 123,
  "name": "望宸",
  "role": "engineer"
}

REST 的设计哲学迎合了互联网应用的爆发需求：轻量、直观、跨语言、易扩展，搭配 Swagger （现称 OpenAPI Specification, OAS）的规范，成为互联网世界应用最广泛的的 API 形态，是 Web API 协议的事实标准。

但随着应用场景的多样化，它也逐渐暴露出一些局限，因此出现了其他的 API 形态。

二、前端查询友好的 GraphQL

在移动互联网和前端复杂化的背景下，客户端需要的数据结构和后端返回的 RESTful 响应会出现对不上号的情况。

• 数据获取过多：例如客户端只需要用户的头像和昵称，但 RESTful API /users/123 返回了整个用户对象（包含地址、订单、权限等一大堆信息）。这不仅浪费带宽，还增加了解析开销。
  
• 数据获取不足：例如移动端要展示用户信息 + 最近三条订单，但 RESTful 只能先调 /users/123，再调 /users/123/orders，最后还得筛选。一个页面可能要发出三四次请求，性能和延迟都受到影响。

这种不足在移动端、复杂单页应用、跨端应用尤为严重，因为客户端和网络环境资源有限。GraphQL 正是为了解决这个问题而出现的。它允许客户端“按需取数”，一次请求返回所需字段。

GraphQL 是 Facebook 在 2015 年开源的一种 API 查询语言与执行引擎。它的核心理念是：客户端自己决定要什么数据，服务端只返回所需字段。

和 RESTful 按资源划分不同，GraphQL 只有一个统一的入口（通常是 /graphql），客户端通过查询语句（Query）来精确指定数据结构。打个比方来解释 GraphQL 和 RESTful 的不同：

• RESTful 是优惠套餐，点了“用户信息”，结果上了一桌子菜，包含了你不需要的；
  
• GraphQL 是自助区，用户拿个盘子，自己挑头像、昵称、最近三单，拿多少算多少。
  

优势

• 按需取数：避免 RESTful 的过度获取和获取不足。
  
• 单一入口：所有请求都通过 /graphql，简化路由和维护。
  
• 强类型 Schema：客户端和服务端共享同一份类型系统，减少数据格式不一致的问题。
  
• 自文档化：Schema 定义就是文档，开发者可以通过 introspection 自动获取接口描述。
  
• 前端友好：前端团队可以独立定义所需数据，减少和后端的沟通成本。
  

工作机制

GraphQL 的运作分三步：

• 客户端构造查询：用类 JSON 的语法描述需要的数据字段；
  
• 服务端解析查询：根据 Schema 验证语法和字段合法性；
  
• 服务端执行解析器：从数据库或服务获取数据，并组装成响应。
  

客户端请求示例

POST /graphql HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "query": "{
    user(id: 123) {
      name
      max
      orders(limit: 3) {
        id
        total
      }
    }
  }"
}

服务端响应示例

{
  "data": {
    "user": {
      "name": "望宸",
      "max": "https://cdn.example.com/max/123.png",
      "orders": [
        { "id": "A001", "total": 99.9 },
        { "id": "A002", "total": 58.0 },
        { "id": "A003", "total": 199.5 }
      ]
    }
  }
}

可以看到：客户端只要“头像、昵称、三条订单”，服务端就不会多给一个字节。

三、面向微服务体系的 API

在性能要求不高的情况下，RESTful 足够好用。但进入微服务架构之后，问题变得复杂：

• 一个前端请求可能要串联 5~10 个微服务，RESTful 的 JSON 编码 + HTTP/1.1 协议在序列化和传输上效率并不高。
  
• 服务之间往往是高频调用，这时候带宽和 CPU 序列化开销就成了大问题，需求高性能的调用框架。
  

这里我们介绍3种大家熟悉的，用于微服务架构的高性能远程调用框架或实现范式。

Apache Dubbo

Apache Dubbo，由阿里开源，是一种 RPC（Remote Procedure Call）框架。核心特性包括：

• 多协议支持：默认用 Dubbo 协议（基于 TCP/长连接），后来也支持 gRPC、REST 等。
  
• 注册中心：典型搭配 Zookeeper、Nacos 来做服务发现。
  
• 负载均衡 & 容错：内建多种负载策略、调用重试、限流降级。
  
• 面向 Java 生态：和 Spring/Spring Boot 结合紧密。
  

gRPC

gRPC 作为 RPC 架构的一种变体， 由 Google 于 2015 年创建，相比 RESTful API，具备更高性能、更低延迟的特点。

• 协议：gRPC 依赖于 HTTP/2，提供更好的性能和更低的延迟，而 REST 使用 HTTP/1.1。
  
• 数据格式：gRPC 采用协议缓冲区 Protobuf（一种二进制序列化格式），从而实现更小的有效负载和更快的通信；REST 通常利用 JSON 或 XML（基于文本的格式）。
  
• API 设计：gRPC 遵循 RPC 范式，使其感觉像是调用本地函数；REST 遵守表述性状态转移模型的架构约束，专注于资源和状态转换。
  
• 流式传输：gRPC 支持双向流式传输，从而实现客户端和服务器之间的持续数据交换；REST 仅限于请求-响应通信模式。
  

Spring Cloud

在 Spring Cloud 体系里，最初的远程调用主要依赖 REST（基于 HTTP），通过 RestTemplate 或后来推荐的 WebClient，后来出现了 Feign（声明式 HTTP 客户端），开发者用接口 + 注解就能调用远程服务，更贴近 RPC 的开发体验。

打个比喻，RESTful 是公路运输（HTTP + JSON），虽然灵活，但车流量大了容易堵车；RPC 是修好的高铁轨道，列车运行高效、可预测，适合点对点的大规模通信。

四、面向实时通信的 API：WebSocket

实时性是互联网应用中诸多场景的刚需。比如：

• 即时通讯应用的消息同步
  
• 协同办公软件里的文档编辑
  
• 游戏场景下的状态更新
  
• 交易平台的行情推送
  

如果仅靠 RESTful API 的请求-响应模型，客户端要么需要不断轮询服务器，要么只能被动等待。前者带来资源浪费，后者无法满足实时性。因此，WebSocket 就应运而生，它们提供了从服务端主动推送消息到客户端的能力，但方式和适用场景有所不同。

WebSocket 是 HTML5 标准中的全双工通信协议，它允许客户端与服务端在单个 TCP 连接上进行双向、实时数据交换。与 REST 不同，WebSocket 不是一次请求&一次响应的短时通信，而是一旦建立连接，就能随时互发消息。

优势

• 双向通信：客户端和服务端都能主动发消息，打破了 HTTP 单向模式。
  
• 低延迟：复用连接，避免了频繁 HTTP 握手的开销。
  
• 实时性高：适合消息交互频繁的场景。
  

工作机制

• 客户端通过 HTTP 请求发起握手（Upgrade: websocket）；
  
• 服务端同意升级，建立 WebSocket 连接；
  
• 后续通信基于帧协议在 TCP 长连接上传输，支持二进制和文本。
  

示例

const socket = new WebSocket("ws://example.com/chat");
socket.onopen = () => socket.send("Hello!");
socket.onmessage = (event) => console.log(event.data);

五、面向大模型场景的流式 API：SSE

大模型场景下流量具备如下特点：

• 生成结果是渐进式的：大模型在推理时，不是一次性生成完整答案，而是逐 token 输出。
  
• 响应延迟更长：推理耗时可能是秒级甚至分钟级。
  
• 数据量大且不可预估：大模型的输出结果往往难以事先预估字数，一次性传输容易导致内存压力、带宽突增，甚至连接超时。
  
• 交互模式以单向为主：大多数大模型应用场景是先用户提问，再模型回答，很少需要实时的双向消息交互。
  
• 连接数量庞大，运维要求高：一个大模型应用可能同时服务数百万用户，需求更轻量、更易于代理和负载均衡的方案。

因此，RESTful 不适合，因为其是客户端发出请求，等待服务端计算完毕，再一次性返回结果WebSocket 是双向通信，需要独立的协议升级、长连接管理、心跳检测，复杂网络（防火墙、代理、负载均衡）下，WebSocket 更容易被中断，WebSocket 的双向能力略显冗余，不是最优选择。

SSE（Server-Sent Events）是一种基于 HTTP 的单向流式传输机制，服务端可以不断通过同一连接向客户端推送事件流，天然适合在对话 Agent 的场景。

优势

• 天然流式：支持服务端边生成边推送，用户能立即看到部分输出。
  
• 基于 HTTP：复用已有 HTTP 基础设施，兼容性好，代理/负载均衡/防火墙都友好。
  
• 轻量级：只需要服务端不断写入 data: 数据块，客户端就能实时接收。
  
• 专注单向流：正好匹配大模型“只需要输出”的场景，不必浪费资源维护双向通道。
  
• 断线重连：支持 Last-Event-ID，能从中断点恢复。
  

工作机制

1. 客户端通过 EventSource 向服务端发起 HTTP GET 请求；

2. 服务端返回 Content-Type: text/event-stream 并保持连接；

3. 服务端以流的形式持续推送事件：

data: hello
data:  world

4. 客户端逐条处理，形成实时效果。

示例

const source = new EventSource("/events");
source.onmessage = (event) => console.log("New data:", event.data);

打个比喻理解三者的不同，WebSocket 是打电话，双方可以随时打断对方说话。SSE 是电台广播

六、面向 MCP 场景的 API

MCP 本质上也是一种 API，作为 MCP Server 向大模型客户端提供应用程序编程接口。早期，MCP 官方采用了 SSE 协议，但是之后变更成 Streamable HTTP 协议。

HTTP + SSE 存在的问题

HTTP+SSE 的传输过程实现中，客户端和服务器通过两个主要渠道进行通信。

• HTTP 请求/响应：客户端通过标准的 HTTP 请求向服务器发送消息。
  
• 服务器发送事件（SSE）：服务器通过专门的 /sse 端点向客户端推送消息。

这就导致存在下面三个问题：

• 服务器必须维护长连接，在高并发情况下会导致显著的资源消耗。
  
• 服务器消息只能通过 SSE 传递，造成了不必要的复杂性和开销。
  
• 基础架构兼容性，许多现有的网络基础架构可能无法正确处理长期的 SSE 连接。企业防火墙可能会强制终止超时连接，导致服务不可靠。
  

Streamable HTTP 的改进

Streamable HTTP 是 MCP 协议的一次重要升级，通过下面的改进解决了原有 HTTP + SSE 传输方式的多个关键问题：

• 统一端点：移除了专门建立连接的 /sse 端点，将所有通信整合到统一的端点。
  
• 按需流式传输：服务器可以灵活选择返回标准 HTTP 响应或通过 SSE 流式返回。
  
• 状态管理：引入 session 机制以支持状态管理和恢复。
  

因此，相比 SSE，Streamable HTTP 在稳定性、性能和客户端复杂度上都有了大幅提升。

七、总结和展望

API 的演进史就是软件工程不断应对新问题的过程。从 SOAP 的繁琐，到 RESTful 的简洁，再到 GraphQL 的灵活，从单向的 HTTP 请求，到实时双向通信的 WebSocket，再到大模型语境下的流式 API，每一次形态的出现，都是在性能、灵活性、实时性之间找到新的平衡点。

未来，随着 AI 原生应用的丰富，API 还会继续演进，并会衍生出 API 管理方面更多的诉求。近期，Higress 开源了开箱即用的 AI 开放平台 Himarket，旨在高效、统一管理 RESTful API、MCP 这些对外提供服务、数据、应用的接口，欢迎试用。

HiMarket AI 开放平台：https://github.com/higress-group/himarket

来源  |  阿里云开发者公众号

作者  |  望宸