研究报告 · 约 25,107 字 · 预计推送 3 部分

API 设计演进：REST、GraphQL、gRPC、WebSocket 与 SSE 的边界（综合报告） 未开始

目录

题记与说明

课题：API 设计演进：REST、GraphQL、gRPC、WebSocket 与 SSE 的边界 ｜ 完成日期：2026-10-31 ｜ 补充视角：个人 Agent 服务选型
本报告由同课题两份章节稿综合而成：纵轴稿（1991→2026 发展史）与横轴稿（2026-10-31 共时截面对比）。所有事实与链接均出自这两份章节稿，未新增未经检索的断言。
修订状态：本文件为最终稿，已按独立审读意见（2026-10-31，共 8 条）逐条修订，修订明细见文末"综合说明"；初稿见 drafts/2026-10-31-API设计演进-REST-GraphQL-gRPC-WebSocket-SSE-综合报告.md。

编者注（综合时处理的重复与出入）
1. 两稿各有一张"个人 Agent 服务选型表"且结论高度重合，已合并为本稿第 3.2 节的唯一一张决策表；
2. 两稿各有一张五技术边界速览表，已合并为本稿第 2.2 节主对比表；其中 SSE 的"缓存"一格取两稿交集口径：不可缓存（无 ETag/Cache-Control 收益），但纯 HTTP 语义、对代理/网关穿透友好；
3. 横轴稿中 Buf Connect 的链接写作 blog.bufbuild.ru，系笔误，已改回纵轴稿直读验证过的 buf.build/blog/connect-a-better-grpc；横轴稿中 Ably 对比文链接 websockets-vs-sese 系笔误，本次综合时实测 https://ably.com/blog/websockets-vs-sse 返回 200、笔误地址返回 404，已修正；
4. MCP 传输演进的表述统一为规范口径：SSE 由独立传输协议降格为 Streamable HTTP 中可按需升级的响应模式（详见 1.8 与 2.3.5）。

TL;DR

五种技术不是互相替代者，而是各守一层：REST 管资源，GraphQL 管取数，gRPC 管调用，WebSocket 管对话，SSE 管广播。纵轴二十五年是钟摆：从 SOAP 强契约摆向 REST/JSON 极简，再摆回 gRPC/GraphQL 强类型，2020 年后又经 tRPC/MCP 摆向"轻契约"——三次摆动的逐次枚举见洞察一。横轴 2026 年胜负已分：REST 以约 93% 使用率居首（Postman 数据，二手转述，见 2.3.1），LLM 时代 OpenAI 兼容 API 又让"REST+SSE"成为模型服务的默认形状（见 2.4）；GraphQL 退守企业联邦层，gRPC 靠 A2A 重返前台，WebSocket 退守语音/协作，SSE 借 LLM token 流迎来第二春并被 MCP 收编为响应模式。元趋势是语义与传输解耦、事实标准收敛。个人 Agent 服务建议：对外 OpenAI 兼容 REST+SSE，对工具 MCP（stdio/Streamable HTTP），语音 WebSocket/WebRTC，管理面 REST+OpenAPI，勿为单用户场景引入 GraphQL/gRPC。

1. 纵轴：发展脉络（1991–2026）

把五条线放在同一根时间轴上，可以看到一个清晰的钟摆运动：从"企业级复杂"（CORBA/SOAP/WS-\*）摆向"Web 原生简单"（REST/JSON），再摆回"强契约、强类型"（gRPC/protobuf、GraphQL schema）；2020 年后钟摆第三次回摆，但这次摆向的是"强类型的极简载体"（tRPC 类型推导、MCP 复用现成标准），而非退回无契约——三次摆动的逐次枚举见 3.1 洞察一。与此同时，REST 的"无状态请求-响应"教条被 WebSocket（双向）、SSE（单向推送）、HTTP/2 多路复用一层层凿开，最终在 Agent/LLM 时代，五种技术按边界各就各位、重新组合。

1.1 前史（1991–1999）：HTTP 成形与企业 RPC 两条线

两条路线在此埋下张力：企业路线（SOAP/WS-\*）越做越重，Web 路线（HTML+HTTP）保持极简。

1.2 REST 诞生与 SOAP 之战（2000–2006）

这一阶段确立了此后二十年的默认范式：资源 + URL + HTTP 动词 + JSON。

1.3 API 经济与实时化萌芽（2006–2011）

1.4 实时标准落定与单页应用兴起（2011–2014）

1.5 新一代接口"三连发"（2015–2016）：五层边界在此定型

这是本课题时间轴上最密集的两年：HTTP/2、gRPC、GraphQL 在一年内相继落地。

三者分别回答了三个不同的问题：gRPC 管"服务之间"，GraphQL 管"客户端与服务之间"，HTTP/2 管"字节如何在网络上跑"。加上 2011 年定型的 WebSocket/SSE 双子星，今天的五层边界在这两年全部落位。

1.6 治理、标准化与生态分工（2017–2019）

竞争焦点从"谁发明协议"转向"谁治理协议"；同时"对外 REST、聚合 GraphQL、内部 gRPC"的社区分工开始成形。

1.7 多极化与浏览器/类型时代（2020–2022）

1.8 Agent/LLM 时代：SSE 第二春与协议重构（2022-11 至今）

这是与本课题补充视角最相关的当下阶段：LLM 的流式输出把沉寂多年的 SSE 推回舞台中央，Agent 的工具调用催生了新一代协议。

Agent 的三类通道需求恰好对应三种传输——token 流（SSE）、双向实时（WebSocket/WebRTC）、结构化工具调用与上下文（JSON-RPC over stdio/HTTP）；再加上长任务、断线续传、安全授权（OAuth 2.1、RFC 8707）、多 Agent 互操作，把前六个阶段沉淀的技术边界全部"再组合"了一遍。

1.9 贯穿二十五年的驱动因素

  1. 网络条件：拨号→宽带→移动弱网→QUIC/HTTP3，决定了"多请求轮询→长连接→多路复用"的迁移（RFC 2616→7540→9114）。
  2. 客户端形态：浏览器→移动 App→SPA→Agent，分别催生了 REST（超媒体）、BFF/GraphQL（多端取数）、MCP/A2A（工具与互操作）。
  3. 部署形态：单体→微服务→边缘→个人 7×24 服务，分别对应 SOAP/RPC→gRPC→Connect/边缘 SSE。
  4. 类型与契约：XML Schema→JSON（无契约）→protobuf/GraphQL schema→TS 类型推导（tRPC）→MCP 确立 JSON Schema 2020-12 为 schema 默认方言（2025-11-25 起，SEP-1613，见 ref 42 变更日志）——"要不要强契约"的钟摆摆了三次，逐次枚举见 3.1 洞察一。
  5. 安全：从"没人管"到 OAuth 2.1、RFC 8707、MCP-Protocol-Version 头（2025-06-18 版新增，见 ref 41 变更日志）——API 演进的后半程越来越由安全需求驱动。
  6. 商业模式：API 经济（AWS/Twilio/Stripe）→模型 API→Agent 互操作，每一代商业模式都把自己需要的通道（计费查询、token 流、工具调用）固化成新协议。

2. 横轴：横向对比（2026-10-31 截面）

2.1 先分层次：五者不在同一抽象层，对比必须"按层替代"

本课题的五位"主角"并不在同一个抽象层次上，这正是横向对比的第一步：

因此"竞品/同类/替代方案"的正确取法不是五者互相替代，而是按层替代：在"暴露数据"这一层，GraphQL 竞争 REST；在"服务间通信"这一层，gRPC 竞争 REST；在"流式推送"这一层，SSE 与 WebSocket 互相竞争。同时，2023–2026 年的 LLM/Agent 浪潮催生了三个新进入者（见 2.4），它们正在重新划分五者的边界。

2.2 主对比表（两稿合并）

维度RESTGraphQLgRPCWebSocketSSE
本质层次资源风格（架构约束）查询语言 + 运行时RPC 框架（Protobuf 契约）传输协议（RFC 6455）HTTP 流式推送（text/event-stream）
通信模式请求-响应请求-响应（单端点）一元/服务端流/客户端流/双向流全双工、有状态长连接单向（服务端→客户端）
契约OpenAPI（可选，事后）SDL Schema（强类型，内置）.proto（强类型，先行）无内置契约（自定消息协议）无内置契约（事件格式自定）
流式能力无原生（可模拟，如 chunked）无原生（Subscription 需外挂 WS/SSE）四种模式原生支持原生双向原生单向流 + 自动重连
浏览器直连✅ 原生✅ 原生❌ 需 gRPC-Web/Connect + 代理✅ 原生✅ 原生
HTTP 缓存✅ 成熟（ETag/Cache-Control）❌ 基本失效（POST 单端点）❌ 无通用方案❌❌（纯 HTTP 语义，代理穿透友好；Last-Event-ID 可协商续传）
学习/运维成本低中（N+1、缓存、网关）高（proto 工具链、HTTP/2 基建）中-高（连接管理、水平扩展难）低（纯 HTTP，无握手）
生态成熟度最高高（Apollo/WunderGraph/ChilliCream）高（CNCF，服务网格原生）高（实时通信基建完备）中-高（被 LLM SDK 全面内置）
2026 年典型阵地公开 API、Web/移动后端、LLM 服务接口企业内部数据编排、BFF/超级图微服务内部、多语言高性能、A2A语音/协作/游戏等双向实时LLM token 流、事件通知、MCP 响应流

2.3 逐项判词

2.3.1 REST：不可能被替代的默认项

多份 2025–2026 年对比综述结论高度一致：REST 仍是绝大多数场景的最佳默认值。Kong 的工程建议是"REST 对多数应用是最佳默认；GraphQL 与 gRPC 适合专门场景"（Kong）。Postman《State of the API》报告的数据（经二手转述）显示 REST 以约 93% 的使用率遥遥领先，GraphQL 约 33%（转述来源：digitalapplied 🔍、refontelearning 🔍）。

REST 的护城河不在单项能力，而在组合能力：HTTP 语义即文档（动词、状态码、缓存头）、OpenAPI 生态、CDN/网关/鉴权全链路零适配、调试即 curl。它的边界也很清楚：多端异构客户端的"过度获取/不足获取"问题它无解——这正是 GraphQL 的切口。

2.3.2 GraphQL：从"REST 杀手"退守"企业编排层"

这是横轴上变化最明显的一项。2026 年的诚实结论（包括 GraphQL 阵营自己承认的）是：GraphQL 没有死，但已经停止扮演"REST 替代者"。

小结：能力上 GraphQL 独有"客户端定义数据形状"；成本上要付 N+1、缓存失效、网关复杂度三笔税；生态上 Apollo supergraph、ChilliCream 的厂商中立联邦规范、WunderGraph 的"把 REST/SOAP/gRPC 自动并入联邦图"的 AI 工具构成三足；成熟度上已进入"无聊但可靠的企业中间层"阶段。

2.3.3 gRPC：内部赛道的王者，浏览器侧的天生残缺

2026 年综述的点题结论："REST 与 GraphQL 主要面向把数据暴露给客户端，而 gRPC 是为服务间通信设计的"（Medium/@davide.mib）。gRPC 的四向流（一元/服务端流/客户端流/双向流）是五者中流式能力最完整的，Protobuf 契约先行 + 多语言代码生成让它在多团队、多语言微服务中不可替代。

它的边界在浏览器：浏览器拿不到 HTTP/2 trailers、不能自定义部分请求头，因此原生 gRPC 无法从浏览器直接调用，必须经 gRPC-Web 代理（典型为 Envoy）（salrashid: Using gRPC-Web on GKE Ingress 🔍、Medium/@senthilrajarathnam）。Buf 的 Connect 协议正是为绕开这一摩擦而生：浏览器友好、同时兼容 gRPC/gRPC-Web（Buf Blog ✅）。

2025 年后的新变量：gRPC 被 Agent 世界"回收再利用"——A2A 规范以 spec/a2a.proto 为全部协议对象的唯一权威规范定义（原文："the file spec/a2a.proto is the single authoritative normative definition of all protocol data objects and request/response messages"），并规定所有派生形式必须从该 proto 再生成；在此之上定义了三种标准协议绑定：JSON-RPC（over HTTPS）、gRPC、HTTP+JSON/REST，三者须提供功能等价的表示（A2A 规范 ✅、agent2agent.info 🔍、github.com/a2aproject/a2a 🔍）。gRPC 因此在"服务间通信"的老本行之外，新开了"Agent 间通信"的阵地。

2.3.4 WebSocket：双向实时的高墙内之王

WebSocket 的能力上限五者最高（全双工、低延迟、二进制、任意消息协议），但能力上限不等于选型得分：它要求有状态的连接管理、粘性会话或专门的连接层，水平扩展与负载均衡成本显著高于无状态 HTTP。Ably 的选型指南指出：只有双方都在持续说话的场景（协作编辑、多人游戏、交易通道）才值得付这笔税（Ably）。

2025 年 LLM 时代它守住了两个高价值阵地：语音 Agent（OpenAI Realtime API 同时提供 WebSocket（服务端/电话链路）与 WebRTC（浏览器端、临时令牌 + 最低延迟）两条接入路径，OpenAI 社区 🔍、callsphere.ai 对比 🔍）与 MCP 早期传输。但它输掉了最大的那一仗——LLM 文本流式输出，见下节。

2.3.5 SSE：LLM 时代的最大赢家

这是横轴上最重要的权力转移事实：主流 LLM 提供商的流式补全都选择了 SSE 而非 WebSocket——其中 OpenAI 与 Anthropic 有官方文档直证：OpenAI 流式指南写明 "Learn how to stream model responses from the OpenAI API using server-sent events"（stream=True）（OpenAI: Streaming API responses ✅），Anthropic 流式文档写明 stream: true 时 "incrementally stream the response using server-sent events (SSE)"（Anthropic: Streaming messages ✅）；"全行业选 SSE"的概括出自第三方对比分析（IBM Community，2025-10 🔍、buildmvpfast，2026-03 🔍）。理由链条完整：

  1. 对话补全是一问一答的单向流，双向能力是冗余成本；
  2. SSE 就是普通 HTTP——代理、负载均衡、CDN、Header 鉴权、HTTP/2 多路复用全部免适配；
  3. 内建 Last-Event-ID 自动重连语义，WebSocket 需要自己造；
  4. 服务端无需维护长连接状态，可无状态水平扩展。

MCP 的演进给这个结论加了一层官方背书：MCP 早期"HTTP + SSE"传输已被废弃，新规范改为 Streamable HTTP——单个 MCP 端点接收 HTTP POST（JSON-RPC 消息），回复按需升级为"请求级 SSE 流"（废弃原因：SSE 的持久连接与 serverless 自动扩缩容天然冲突，见迁移实录与迁移指南；规范直读见 MCP 传输页）。也就是说：SSE 从"独立传输协议"降格为"Streamable HTTP 里可按需升级的响应模式"——不是被抛弃，而是被收编。

2.4 新进入者：正在重划边界的三个协议

协议编码传输解决的问题对五巨头的边界影响
OpenAI 兼容 APIJSONREST + SSE统一 LLM 服务接口让"REST+SSE"成为 LLM 时代的默认形状；本地推理服务全部跟进
MCPJSON-RPC 2.0stdio / Streamable HTTPAgent↔工具/数据源复活了 JSON-RPC；把 SSE 收编为响应模式
A2AJSON-RPC over HTTPS / protobuf / HTTP+JSON（三种绑定均以同一份 a2a.proto 为权威定义）HTTPS / gRPCAgent↔Agent 互操作让 gRPC 重新进入前台；Agent 间不共享内部状态

OpenAI 兼容 API 是 2026 年最成功的"隐性标准"。本地推理三件套 Ollama、llama.cpp、vLLM（以及 LM Studio）全部暴露 OpenAI 兼容端点，使客户端代码可以在它们之间无改动互换（matterai 对比、cohorte 🔍、Red Hat Developer 🔍）。网关层 LiteLLM 把这一个形状扩到 100+ 家提供商、约 1900 个模型（官方文档自述 "one OpenAI-compatible endpoint for 100+ LLM providers"，LiteLLM 文档 ✅、litellm.ai 🔍）。

MCP 证明了 JSON-RPC 的复兴：它没有发明新编码，而是直接复用既有 JSON-RPC 2.0 编码（该规范 2009–2010 年定稿，规范页标明 "Origin Date: 2010-03-26 (based on the 2009-05-24 version)"，jsonrpc.org ✅；安全分析确认其传输无关性，senthorus 🔍）。选型含义是：Agent 工具调用不需要 REST 的资源建模，也不需要 GraphQL 的查询能力，需要的是"方法名 + 参数 + 通知"的最小 RPC 语义。

A2A 证明了多传输绑定是可行架构：spec/a2a.proto 是唯一权威规范定义，JSON-RPC over HTTPS、gRPC、HTTP+JSON/REST 三种绑定均须提供其功能等价的表示（A2A 规范 ✅、agent2agent.info 🔍）。这与 MCP"一套语义、多种 binding"的官方表述形成呼应——2026 年的主流共识是"语义与传输解耦"，而不是"一种协议统治所有层"。

3. 交叉洞察：两轴结合说明了什么

3.1 五条元洞察

洞察一：钟摆不是整体摇摆，而是逐层发生；五层边界在 2015–2016 已固化。
纵轴看到"强契约↔极简"的钟摆摆了三次，逐次枚举如下：第一次（2000 年代，向极简）——CORBA/SOAP/WS-\* 的 XML Schema 强契约 → REST/JSON 的"无契约"（靠约定与 OpenAPI 事后补救）；第二次（2015–2016，向强契约）——REST/JSON → gRPC proto 与 GraphQL SDL，先行 IDL 与代码生成回归；第三次（2020–2025，向"轻契约"）——gRPC/GraphQL 式"新造 IDL" → tRPC 把契约移进 TS 类型系统（无 schema、无代码生成）、MCP 直接复用现成的 JSON-RPC 2.0 与 JSON Schema——强类型保留，契约的仪式与重量做减法。横轴看到五个协议各守一层。两轴叠加的真相是：钟摆只发生在"契约风格"这一层，传输层（HTTP/1.1→2→3）始终单向进化，而 2011 年的 RFC 6455/SSE 与 2015–2016 年的 HTTP/2/gRPC/GraphQL"三连发"之后，再没有新范式取代过这五者——此后十年只有新协议（OpenAI 兼容 API、MCP、A2A）在层与层的缝隙里重新组合它们。今天要做的不是发明第六种范式，而是把五层拼对。

洞察二：胜负由"最小通道匹配"决定，不由能力上限决定。
SSE 能力最弱（单向、纯文本、无契约）却赢下了 LLM 流式——因为逐 token 生成在物理上就是单向文本流，双向能力是冗余成本；WebSocket 能力最强（全双工、二进制、任意协议）却只守住语音/协作——因为它为用不到的能力收取有状态连接的税；GraphQL 表达力最强却退守联邦层——因为单客户端场景付不起 N+1 与缓存失效。纵轴上每个协议都诞生于对"当时那个最小通道"的匹配（SSE 匹配服务器推送、gRPC 匹配内部微服务、GraphQL 匹配移动端裁剪），横轴上每个协议的胜负也由"当下场景的最小通道"重新裁决。能力过剩 = 成本，选型的第一问永远是"这个场景的最小通道是什么"。

洞察三：语义与传输持续解耦，是两轴共同指向的元趋势。
横轴稿在 2026 年截面上观察到：MCP 明言"transport is a binding"（一套 JSON-RPC 语义绑 stdio/Streamable HTTP 两种传输），A2A 用一份 a2a.proto 派生出功能等价的三种绑定（JSON-RPC over HTTPS、gRPC、HTTP+JSON/REST）；SSE 被收编为 Streamable HTTP 的响应模式，JSON-RPC（2009–2010 年定稿的编码，见 jsonrpc.org ✅）在 MCP 中复活，Protobuf 在 A2A 中复用。回到纵轴，这其实是二十五年来一直在发生的事：REST 把"资源语义"与"HTTP 传输"绑定得更松（Fielding 的超媒体理想从未被主流实现），HTTP/2 把"API 风格"与"字节怎么跑"彻底分开，Connect 把"gRPC 语义"搬上 HTTP/1.1。API 设计的问题已经从"该用哪种协议"变成"这一层的语义用什么编码表达、传输用什么形状承载"。

洞察四：事实标准定形状，正式治理保生存，两条轨道缺一不可。
纵轴显示 2017 年后协议存活的门槛是治理：gRPC 入 CNCF（2017）、GraphQL 基金会（2018）、MCP 治理结构（2025-11-25）、A2A 入 Linux 基金会（2025-06-23）；横轴则显示 2026 年最强的接口形状不是任何组织发布的标准——OpenAI 兼容 API 由一个厂商的 REST+SSE 形状出发，靠本地推理三件套（Ollama/llama.cpp/vLLM）与 LiteLLM（100+ 提供商）自发跟进成为事实标准。GraphQL 有完整的正式治理，却停止了作为"REST 替代者"的扩张——其采用数据仍在涨（约 70%、50%+，见 2.3.2），但增长集中于联邦编排场景而非对 REST 的替代；OpenAI 兼容 API 没有治理机构却统一了行业。结论：押注协议时看治理（有中立治理才不会被单一厂商绑架），设计接口时看事实形状（跟行业收敛的形状走， interoperability 成本最低）。

洞察五：后半程的驱动力从"功能"转向"安全与治理"。
纵轴的六个阶段里，前半程的演化由网络条件与客户端形态驱动，后半程（MCP 2025-03-26 引入 OAuth 2.1、2025-06-18 要求 RFC 8707 Resource Indicators 并新增 MCP-Protocol-Version 头、2025-11-25 确立治理结构、2026-07-28 Tasks 转正并加 Skills/Apps 扩展）越来越由授权、审计与长任务治理驱动。横轴上 MCP 对 SSE 传输的废弃理由也不是技术落后，而是"持久连接与 serverless 自动扩缩容天然冲突"——运维与安全形态反过来改造协议。API 设计的重心正在从"怎么传"移向"怎么授权、怎么扩缩、怎么治理"。

3.2 对个人 Agent 服务的判断与建议

把两轴结论折算到"个人自建 Agent 服务"（单用户/小团队、一台 24 小时机器、成本敏感、要求可替换性）的场景。两份章节稿的选型表结论一致，合并为唯一一张决策表：

层场景首选理由（对应两轴事实）
模型推理层本地跑模型（Ollama/vLLM/llama.cpp）OpenAI 兼容 REST + SSE三件套全部原生暴露该形状，换后端零改码（横轴 2.4）
模型网关层同时用云端 API + 本地模型LiteLLM 类 OpenAI 兼容网关一个形状覆盖 100+ 提供商，密钥/配额/重试统一管理
流式面LLM token 流、任务进度、通知SSE（text/event-stream）LLM 行业已用脚投票；EventSource 自动重连、纯 HTTP、无状态可扩展
工具面（本地）脚本、文件系统等本地工具MCP stdio（JSON-RPC 换行分帧）进程子方式启动、无网络栈，官方两大标准传输之一
工具面（远程/跨机）远程/跨机工具MCP Streamable HTTP单端点 POST + 请求级 SSE，适配无状态部署；勿再用已废弃的 HTTP+SSE 双端点传输
长任务爬取、批处理、多步任务MCP Tasks 或自建队列 + SSE 进度推送协议已给出"持久请求 + 轮询 + 延迟取结果"的官方答案（2025-11-25 实验→2026-07-28 转正）
实时面语音/实时对话WebSocket（服务端间）/ WebRTC（浏览器端）双向连续音频流是 WebSocket 不可退让的主场；参照 Realtime API"先 WS 后补 WebRTC"的拓扑
控制面任务 CRUD、配置、鉴权、管理面板REST + OpenAPI 3.1二十年验证的默认项：缓存、调试、网关、文档生成全部现成
多 Agent 协作与他人/其他框架的 Agent 互操作A2A（HTTP+JSON 绑定优先）开放协议、绑定语义同构；个人场景不必启用 gRPC 绑定
跨机高频内部调用多台机器、多语言模块gRPC 或 ConnectgRPC 管"服务之间"的边界结论至今成立；要喂浏览器就用 Connect（HTTP/1.1 兼容）
只读异构数据聚合聚合 GitHub 等第三方数据优先用对方现成 API（如 GitHub GraphQL）自建 GraphQL 在单用户场景几乎总是过度设计
本机内部多模块单机模块间通信进程内直调/队列即可gRPC 的强契约收益 < 维护 proto/代码生成的成本

一句话原则：个人 Agent 服务应把自己的 API 表面收敛为两种形状——对外一律"OpenAI 兼容 REST+SSE"，对工具一律"MCP（stdio 本地 / Streamable HTTP 远程）"，语音是唯一的 WebSocket 例外。这与 2026 年行业事实标准的收敛方向完全一致：观察到的普遍模式不是"选一种协议"，而是"每种协议各守一层，层与层之间靠事实标准形状拼接"。

推荐骨架（五个面）

  1. 控制面：REST（FastAPI/Hono）暴露任务 CRUD、配置、鉴权，OpenAPI 文档自动生成；
  2. 流式面：所有模型输出走 SSE，进度/通知事件复用 SSE 的 event: 类型字段；
  3. 工具面：本地工具挂 stdio MCP server，远程/跨机工具挂 Streamable HTTP MCP server，用 OAuth 2.1 + RFC 8707 保护远程端点；
  4. 实时面：若做语音，客户端 WebRTC、服务器间 WebSocket，参照 Realtime API 拓扑；
  5. 治理面：学 MCP 的"日期版本"惯例（2024-11-05 → 2025-03-26 → 2025-06-18 → 2025-11-25 → 2026-07-28），给自家 API 定日期版本与变更日志。

反模式（两轴上反复出现的坑）

4. 参考来源

标注说明：✅ = 章节稿会话或本修订会话（2026-10-31）中直接抓取验证过原文；🔍 = 搜索结果确认（未直接打开原文全文）；〔转述〕= 二手转述数据，未核对原始报告全文。2026 截面组（25–37）以 🔍 搜索确认为主，本次修订未逐一打开原文复核；其中 25–31 沿用章节稿检索结果、维持未逐一验证声明。本次修订已把裸域名来源补到具体文章路径（32、33、36、37、44、49），无法定位具体文章的 getstream.io 条目已删除（见 36 说明），官方文档直证补入 48。

规范与一手来源

  1. Fielding 博士论文第 5 章（REST），UCI，2000：https://ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm ✅
  2. SOAP 1.1 W3C Note，2000-05-08：https://www.w3.org/TR/2000/NOTE-SOAP-20000508/ ✅
  3. Fielding《REST APIs must be hypertext-driven》，2008-10-20：https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven ✅
  4. RFC 2616 HTTP/1.1（1999-06）：https://datatracker.ietf.org/doc/html/rfc2616 🔍
  5. RFC 6455 The WebSocket Protocol，2011-12：https://datatracker.ietf.org/doc/html/rfc6455 ✅
  6. RFC 7540 HTTP/2，2015-05：https://datatracker.ietf.org/doc/html/rfc7540 ✅
  7. RFC 9114 HTTP/3，2022-06：https://datatracker.ietf.org/doc/html/rfc9114 ✅
  8. WHATWG HTML §9.2 Server-sent events：https://html.spec.whatwg.org/multipage/server-sent-events.html ✅
  9. caniuse：EventSource 浏览器支持：https://caniuse.com/eventsource ✅
  10. spec.graphql.org（最新版 2025-09）：https://spec.graphql.org ✅

历史沿革与官方公告

  1. XML-RPC 历史（1998）：https://en.wikipedia.org/wiki/XML-RPC 🔍
  2. Amazon S3 发布（2006-03-14）：https://press.aboutamazon.com/2006/3/amazon-web-services-launches 、https://en.wikipedia.org/wiki/Amazon_S3 🔍
  3. Alex Russell《Comet》，2006-03-03：https://infrequently.org/2006/03/comet-low-latency-data-for-the-browser 🔍
  4. WebSocket 起源（2008）：https://lists.w3.org/Archives/Public/public-whatwg-archive/2008Jun/0186.html 、https://en.wikipedia.org/wiki/WebSocket 、https://www.taskade.com/blog/websockets-history 🔍
  5. Socket.IO（2010；1.0 于 2014-05-28）：https://socket.io 、https://www.infoq.com/news/2014/05/socket-io-1.0/ 🔍
  6. grpc.io/about（Stubby 沿革）：https://grpc.io/about/ ✅
  7. gRPC 1.0（2016-08-23）：https://cloud.google.com/blog/products/gcp/grpc-a-true-internet-scale-rpc-framework-is-now-1-and-ready-for-production-deployments 🔍
  8. Meta Engineering《GraphQL: A data query language》，2015-09-14：https://engineering.fb.com/2015/09/14/core-infra/graphql-a-data-query-language/ ✅
  9. Phil Calçado《Pattern: Backends For Frontends》，2015-09-18：https://philcalcado.com/2015/09/18/the_back_end_for_front_end_pattern_bff.html ✅
  10. GitHub GraphQL API v4（2016-09 预览）：https://docs.github.com/en/graphql 、https://medium.com/apollo-stack/the-new-github-graphql-api-811b005d1b6e 🔍
  11. GraphQL Foundation（2018-11-06）：https://www.linuxfoundation.org/press/press-release/intent_to_form_graphql 、https://techcrunch.com/2018/11/06/facebooks-graphql-gets-its-own-open-source-foundation/ 🔍
  12. gRPC 在 CNCF（2017-02 孵化，未毕业）：https://www.cncf.io/projects/grpc/ 、https://github.com/cncf/toc/pull/2101 🔍
  13. tRPC（约 2020 年中）：https://trpc.io 、https://ajcwebdev.com/first-look-trpc 🔍
  14. Buf《Connect: A better gRPC》，2022-06-01：https://buf.build/blog/connect-a-better-grpc ✅；Connect 官网：https://connectrpc.com 🔍

2026 截面：采用数据与选型对比

  1. Kong：REST vs gRPC vs GraphQL 选型：https://konghq.com/blog/engineering/rest-vs-grpc-vs-graphql
  2. Medium（2026）：REST vs GraphQL vs gRPC 定位差异：https://medium.com/@davide.mib/rest-vs-graphql-vs-grpc-when-to-use-what-in-2026-ea3392d41476
  3. dev.to（2026-07）：三者选型综述：https://dev.to/addwebsolutionpvtltd/rest-vs-graphql-vs-grpc-choosing-the-right-api-architecture-fa4
  4. Apollo：API 编排研究（约 70% 组织使用）：https://www.apollographql.com/newsroom/press-releases/apollo-graphql-unveils-first-comprehensive-api-orchestration-research-study
  5. Apollo：对 2026 Gartner 曲线的自评（Agent 场景渗透有限）：https://www.apollographql.com/blog/what-we-think-the-2026-gartner-hype-cycle-gets-right-about-graphql
  6. WunderGraph：六年 GraphQL 复盘：https://wundergraph.com/blog/six-year-graphql-recap
  7. Gartner 预测转述（2025 年 50% 企业生产使用）：https://zylos.ai/research/2026-02-04-graphql-modern-api-development 〔转述〕
  8. Postman 数据转述（REST 93% / GraphQL 33%）：https://www.digitalapplied.com/blog/api-versioning-strategies-2026-engineering-decision-matrix 🔍 、https://www.refontelearning.com/blog/what-tools-do-professional-api-developers-use 🔍 〔转述〕
  9. gRPC 浏览器限制（HTTP/2 trailers）：https://blog.salrashid.dev/articles/2018/grpc_web_with_gke 🔍 、https://medium.com/@senthilrajarathnam/grpc-web-connect-web-b25d667462bc
  10. Ably：WebSocket vs SSE 选型：https://ably.com/blog/websockets-vs-sse （横轴稿原链接含笔误，本次综合实测 200 修正）
  11. IBM Community（2025-10）：SSE 与实时聊天：https://community.ibm.com/community/user/blogs/anjana-m-r/2025/10/03/server-sent-events-the-perfect-match-for-real-time 🔍
  12. LLM 流式选 SSE 的行业分析：https://www.buildmvpfast.com/blog/streaming-llm-responses-sse-vs-websockets-2026 🔍 （原 getstream.io 为裸域名条目，本次检索未能定位到具体文章、猜测路径实测 404，已删除该条；厂商侧直证改以官方文档为准，见 48）
  13. OpenAI Realtime API 双路径（WebSocket/WebRTC）：https://openai.com/index/introducing-the-realtime-api 、https://community.openai.com/t/realtime-api-updates-webrtc-cheaper-prices-4o-mini-and-more/1059962 🔍 、https://callsphere.ai/blog/vw1c-openai-realtime-websocket-vs-webrtc-tradeoffs-2026 🔍

Agent 协议生态（MCP / A2A / OpenAI 兼容）

  1. Anthropic《Model Context Protocol》，2024-11-25：https://www.anthropic.com/news/model-context-protocol ✅
  2. MCP 规范最新版（2026-07-28）：https://modelcontextprotocol.io/specification/latest ✅；传输页：https://modelcontextprotocol.io/docs/concepts/transports
  3. MCP 规范 2025-03-26 变更（Streamable HTTP / OAuth 2.1）：https://modelcontextprotocol.io/specification/2025-03-26/changelog ✅
  4. MCP 规范 2025-06-18 变更（RFC 8707、MCP-Protocol-Version 头等）：https://modelcontextprotocol.io/specification/2025-06-18/changelog ✅
  5. MCP 规范 2025-11-25 变更（Tasks / 治理结构 / JSON Schema 2020-12 默认方言，SEP-1613）：https://modelcontextprotocol.io/specification/2025-11-25/changelog ✅
  6. MCP SSE 传输废弃与迁移：https://protobox.ai/blog/mcp-sse-to-streamable-http-migration 、https://www.reddit.com/r/ClaudeAI/comments/1qu43qt/
  7. MCP JSON-RPC 安全分析（Senthorus《Clashing Security Challenges in the Model Context Protocol》）：https://blog.senthorus.ch/posts/model_context_protocol 🔍
  8. A2A 协议（Google 2025-04 发布、Linux 基金会 2025-06-23、三种绑定以 a2a.proto 为权威定义）：https://a2a-protocol.org/latest/specification/ ✅（规范原文，本次修订直读）、https://agent2agent.info 🔍 、https://github.com/a2aproject/a2a 🔍 、https://www.linuxfoundation.org/press/linux-foundation-launches-the-agent2agent-protocol-project-to-enable-secure-intelligent-communication-between-ai-agents ✅
  9. OpenAI function calling（2023-06-13）：https://openai.com/index/function-calling-and-other-api-updates 🔍
  10. OpenAI Responses API / Agents SDK（2025-03-11）：https://openai.com/index/new-tools-for-building-agents 🔍
  11. LLM API 流式输出为 SSE（官方文档直证，替代原第三方镜像 poixe.com）：OpenAI《Streaming API responses》：https://platform.openai.com/docs/guides/streaming-responses ✅ ；Anthropic《Streaming messages》：https://platform.claude.com/docs/en/build-with-claude/streaming ✅
  12. 本地推理 OpenAI 兼容 API 对比：https://www.matterai.so/guides/ollama-vs-vllm-vs-llamacpp-runtime-comparison 、https://cohorte.co/blog/local-llm-openai-compatible-server 🔍 、https://developers.redhat.com/articles/2025/10/30/why-vllm-best-choice-ai-inference-today 🔍
  13. LiteLLM 网关（100+ 提供商统一 OpenAI 形状，官方自述 "one OpenAI-compatible endpoint for 100+ LLM providers"）：https://docs.litellm.ai/docs/simple_proxy ✅ 、https://www.litellm.ai 🔍
  14. JSON-RPC 2.0 规范（Origin Date: 2010-03-26，基于 2009-05-24 版）：https://www.jsonrpc.org/specification ✅（本次修订直读，用于更正"1999 年代际"误记）
  15. MCP 规范首版（2024-11-05）：https://modelcontextprotocol.io/specification/2024-11-05 ✅（本次修订直读）

*综合说明：本稿为最终稿，已按独立审读意见（2026-10-31，共 8 条）逐条修订。修订明细：① A2A 绑定口径统一为三种（JSON-RPC over HTTPS / gRPC / HTTP+JSON，均以 spec/a2a.proto 为唯一权威规范定义），修订处 2.3.3、2.4 表、洞察三，依据 A2A 规范原文（ref 45）直读；② "JSON-RPC 2.0（1999 年代际）"经核实为误记，改为"2009–2010 年定稿"并补官方规范来源（ref 51），修订处 2.4 与洞察三；③ TL;DR 中"93% 使用率"（Postman 二手转述）与"借 OpenAI 兼容 API 二次登基"已拆分为两个独立陈述，不再拼接因果；④ 钟摆口径全文统一为"三次摆动"，并在洞察一逐次枚举（SOAP→REST→gRPC/GraphQL→tRPC/MCP），TL;DR、1 章导语、1.7、1.9、2.3.5 关联处同步；⑤ "所有主流 LLM 提供商流式补全都选 SSE"补入 OpenAI/Anthropic 官方流式文档为主证（ref 48，本次直读），全称判断降格为"OpenAI 与 Anthropic 有官方文档直证 + 第三方分析概括行业面"；⑥ 裸域名来源补到具体文章路径（32、33、36、37、44、49），2026 截面组补齐标注并在标注说明中声明未逐一验证项，无法定位的 getstream.io 条目删除；⑦ 章节时间错位调整：Fielding 2008 博文自 1.2 移入 1.3，1.3 区间放宽为 2006–2011（Comet、Stripe 随之入界），1.6 的 OpenAPI 表述改以 2017 年发布为锚点；⑧ 散点口径：洞察四改为"停止作为 REST 替代者扩张"并与 2.3.2 采用数据调和；1.8 补 MCP 首版规范日期 2024-11-05（ref 52）；1.9/1.8 补 JSON Schema 2020-12（2025-11-25，SEP-1613）与 MCP-Protocol-Version 头（2025-06-18）出处；LiteLLM 统一为"100+ 家提供商"（官方自述，ref 50）。两份章节稿的完整细节（尤其纵轴各阶段的"主要参与者/驱动因素"分析与横轴逐项数据的转述来源）以上文链接为准。*

思考题（读完后想一想，参考答案可展开）

  1. 报告的核心论点是什么？为什么说 REST、GraphQL、gRPC、WebSocket、SSE 五种技术是“各守一层”而非互相替代？
    参考答案

    五种技术不在同一抽象层、各守一层：REST 管资源、GraphQL 管取数、gRPC 管服务间调用、WebSocket 管双向实时、SSE 管单向推送。纵轴呈钟摆：SOAP 强契约→REST/JSON 极简→gRPC/GraphQL 强类型→tRPC/MCP 轻契约。五层边界 2015–2016 已固化，此后无新范式取代，只有 OpenAI 兼容 API、MCP、A2A 在层间缝隙重组它们。

  2. 在 LLM 流式输出场景中，能力最弱的 SSE 为何击败能力最强的 WebSocket？这体现了什么选型原则？
    参考答案

    对话补全是一问一答的单向流，双向能力是冗余成本；SSE 是普通 HTTP，代理、CDN、鉴权免适配，内建 Last-Event-ID 自动重连，服务端可无状态扩展。这体现“最小通道匹配”原则：胜负由最小通道决定，不由能力上限决定，能力过剩即成本。WebSocket 能力最强却只守住语音/协作等双方持续说话的场景。

  3. 报告中哪些关键数据和结论存在证据等级限制？引用时应注意什么？
    参考答案

    REST 约 93%、GraphQL 约 33% 的使用率是 Postman 报告的二手转述；“全行业 LLM 提供商选 SSE”仅 OpenAI 与 Anthropic 官方文档直证，行业概括出自第三方分析；GraphQL 停止扩张的判断部分依赖 Apollo 对 2026 Gartner 曲线的自评。报告修订已把这些降格处理，引用数字时应注意证据等级。

  4. 个人自建 Agent 服务应把 API 表面收敛为什么形状？报告警告了哪些反模式？
    参考答案

    收敛为两种形状：对外一律 OpenAI 兼容 REST+SSE（Ollama、llama.cpp、vLLM 均原生暴露，换后端零改码）；对工具一律 MCP（本地 stdio、远程 Streamable HTTP）；语音是唯一 WebSocket 例外。反模式：单用户上 GraphQL、WebSocket 承载一切、自造工具调用协议、原生 gRPC 直暴露给浏览器、预付复杂度税。

← 资料库今日播报 →