API 设计风格对比:REST、GraphQL、gRPC、SSE、WebSocket —— 结合 Agent 工具服务给出选型表(精读笔记) 未开始

题记与说明

精读日期:2026-10-31
唯一前缀:knowledge-fexxiou8-1
精读方式:网络可用,共精读 5 个来源(WebFetch 全文抓取并提取原文引述),另有 3 组搜索级结果作为旁证(已标注精读级别)。
注:本次精读对象多为"对比指南/规范/工程博客"而非学术论文,因此"数据与证据"维度多为定性论证与规范原文,定量基准数据普遍缺失(已在局限中标注)。

0. 来源清单与精读级别

1. 一句话画像:五种风格到底在比什么

关键提醒(S1):REST/GraphQL/gRPC 与 SSE/WebSocket 不是同一层的比较——前者是API 组织风格(怎么建模交互),后者是传输/推送通道(数据怎么流动)。一个 LLM 聊天服务完全可以"REST 风格的 POST + SSE 响应流"组合。MCP(S2)恰好示范了这一点:消息层用 JSON-RPC(类 gRPC 的 RPC 风格),传输层用 stdio 或"HTTP POST + 可选 SSE"。

2. 逐来源精读

S1. REST vs GraphQL vs gRPC(Level Up Coding)

核心论点:三者解决的是不同的通信问题,错误的不是选错,而是选了一个到处用。

三种风格各自"组织通信"的方式(S1 原文,经 WebFetch 提取):

• REST — "Organizes communication around resources"(围绕资源组织通信)
• GraphQL — "Organizes communication around queries",客户端指定精确的数据形状,"the server resolves only those fields"(服务端只解析被请求的字段),并对着一份类型化 schema 校验,schema 是共享契约
• gRPC — "Organizes communication around methods",服务暴露 "strongly typed procedures that other services call directly over HTTP/2 using compact binary messages"(强类型过程,经 HTTP/2 以紧凑二进制消息直接调用),网络调用感觉像本地函数调用

优劣清单(S1):

S1 的选型建议(原文):

• REST:"when stability, simplicity, and web infrastructure matter more than fine-grained data control"(当稳定性、简单性和 Web 基础设施比细粒度数据控制更重要时)
• GraphQL:"when client data needs vary frequently"(当客户端数据需求频繁变化时)
• gRPC:"for internal service communication"(用于内部服务间通信)

S1 的点睛引述(逐字):

"An API style is really a tradeoff between flexibility, simplicity, efficiency, and control."
(API 风格本质上是灵活性、简单性、效率与控制力之间的权衡。)

"The trap isn't choosing the wrong one. It's choosing one and using it everywhere."
(陷阱不在于选错了哪个,而在于选了一个然后到处都用它。)

"Most production systems do not choose a single API style. They choose boundaries."
(大多数生产系统并不选择单一 API 风格,而是选择边界。)

S1 的结论架构:混合分层。 边缘(浏览器/移动端/第三方)用 REST 或 GraphQL;内部用 gRPC(protobuf + deadline-aware calls)。示例:目录服务走 REST 过 CDN 缓存,移动端走 GraphQL 聚合层,内部服务走 gRPC。三者是互补的层次,不是竞争的哲学。

注意(S1 局限): 该文完全定性,无任何基准数字;宣称二进制载荷"比 JSON 更小更快"但未给测量。

S5. gRPC 官方文档(Introduction + Core concepts)

定义(逐字):

"In gRPC, a client application can directly call a method on a server application on a different machine as if it were a local object"
(客户端可以直接调用另一台机器上服务端应用的方法,就像调用本地对象一样。)

• 默认用 Protocol Buffers 同时作为 IDL 与消息交换格式;"gRPC can use protocol buffers as both its Interface Definition Language (IDL) and as its underlying message interchange format"
• 客户端持有一个 stub("a local object known as stub"),实现与服务端相同的方法;protoc + gRPC 插件生成客户端/服务端桩代码与序列化代码
• 跨语言互操作:"you can easily create a gRPC server in Java with clients in Go, Python, or Ruby"

四种 RPC 方法类型(逐字,来自 Core concepts 页):

内建能力(逐字要点):

• Deadline:客户端可指定 "how long they are willing to wait for an RPC to complete",超时得 DEADLINE_EXCEEDED;服务端可查询剩余时间
• Cancellation:"Either the client or the server can cancel an RPC at any time",且 "Changes made before a cancellation are not rolled back"(取消不回滚——写工具逻辑时要自己保证幂等/补偿)
• Metadata:"information about a particular RPC call (such as authentication details)" 的键值对;键不得以 grpc- 开头(保留);二进制值键以 -bin 结尾
• 终止语义:"both the client and server make independent and local determinations of the success of the call, and their conclusions may not match"(双方各自判定成功与否,结论可能不一致——分布式调用必须幂等)

S2. MCP 规范 Transports(Agent 工具服务的事实标准)

消息层:JSON-RPC。 规范第一句:"MCP uses JSON-RPC to encode messages. JSON-RPC messages MUST be UTF-8 encoded."

传输层:两种标准传输 + 自定义。

1. stdio:"The client launches the MCP server as a subprocess",客户端写 stdin、服务端写 stdout;消息按行分隔、不得含内嵌换行;stdout 只许写合法 MCP 消息;"Clients SHOULD support stdio whenever possible."
2. Streamable HTTP(2025-03-26 起取代旧的 HTTP+SSE 传输):服务端"operates as an independent process that can handle multiple client connections"。规范原文要点:

"Server can optionally make use of Server-Sent Events (SSE) to stream multiple server messages. This permits basic MCP servers, as well as more feature-rich servers supporting streaming and server-to-client notifications and requests."

• 单端点:"The server MUST provide a single HTTP endpoint path … that supports both POST and GET methods"(如 https://example.com/mcp)
• 上行:每条 JSON-RPC 消息各发一个 HTTP POST;Accept 头必须同时列 application/json 与 text/event-stream
• 下行两种形态:服务端对 POST 可回 application/json(单对象)或 text/event-stream(SSE 流),客户端必须都支持
• 服务器主动消息:客户端可对端点发 GET 开 SSE 流,接收与当前请求无关的服务器发起请求/通知;无则回 405
• 多连接约束:"it MUST NOT broadcast the same message across multiple streams"(同一消息只发一条流)
• 断线与重投:SSE 事件可带 id;断线不算取消("Disconnection SHOULD NOT be interpreted as the client cancelling its request"),取消要显式发 CancelledNotification;重连用 Last-Event-ID 头从游标续传,且服务端"MUST NOT replay messages … on a different stream"
• 会话:Mcp-Session-Id 头(初始化时下发);"SHOULD be globally unique and cryptographically secure";终止发 DELETE;收到 404 则重新初始化
• 版本头:HTTP 上所有后续请求必须带 MCP-Protocol-Version: 2025-06-18
• 安全警告(逐字):"Servers MUST validate the Origin header on all incoming connections to prevent DNS rebinding attacks";本地应只绑 127.0.0.1;"Without these protections, attackers could use DNS rebinding to interact with local MCP servers from remote websites."
• 自定义传输:"The protocol is transport-agnostic and can be implemented over any communication channel that supports bidirectional message exchange"——但必须保持 JSON-RPC 消息格式与生命周期要求

对我们的含义: MCP 的消息层是 RPC 风格(不是资源风格),传输层是"HTTP POST + 可选 SSE 推送"——它把 gRPC 的"方法调用"心智模型、SSE 的"服务器推送"能力、HTTP 的基础设施兼容性缝合在一起,且刻意不用 WebSocket。

S3. SSE vs WebSocket(dev.to 精读,含评论区勘误)

两者技术分野(逐字):

• WebSocket:"Both the client and the server can shout at each other simultaneously."(全双工:客户端与服务端可同时互喊)
• SSE:"The server keeps a standard HTTP connection open and pushes text-based events down to the client."(服务端保持一条标准 HTTP 连接,向下推送文本事件)

WebSocket 的四类基础设施成本(S3):

SSE 的扩展心智:"is just a long-lived HTTP request, it scales like any other HTTP endpoint"——它就是一条长 HTTP 请求,按普通 HTTP 端点的方式扩展。

S3 的判断阈值: 只有当客户端需要在流进行中高频回推(文中阈值:"10+ times per second")时才需要 WebSocket——典型是聊天室、多人游戏、协作文档(如 Google Docs)。

S3 点睛引述(逐字):

"for about 90% of modern web applications—including AI chat streaming, live dashboards, and notification feeds—WebSockets are massive overkill."
(对约 90% 的现代 Web 应用——包括 AI 聊天流、实时面板、通知流——WebSocket 都是大材小用。)

"WebSockets and SSE aren't competitors; they solve different shapes of problems."
(WebSocket 与 SSE 不是竞品,它们解决不同形状的问题。)

"don't immediately reach for the heaviest tool in the box"
(别一上来就伸手拿工具箱里最重的那个。)

评论区勘误(重要工程细节,S3 独有): 该文示例代码没发 id: 行,浏览器就不会带 Last-Event-ID——自动重连仍会触发,但续传不会。更深一层:即使补了 id:,服务端还必须真读这个头并从缓冲区重放;用 Date.now() 当事件 id 会让续传难以实现(应使用单调序列号);没有重放逻辑却宣称可续传,"the header became honest and the stream became duplicating"(头变诚实了,流却开始重复)——比不宣称续传更糟。

S4. Anthropic《Writing effective tools for agents》(工具服务的设计学)

定位(逐字):

"Tools are a new kind of software which reflects a contract between deterministic systems and non-deterministic agents."
(工具是一种新型软件:它体现的是确定性系统与非确定性 Agent 之间的契约。)

其核心主张:不该"按写给人类开发者的函数和 API 的方式"写工具与 MCP server,而要为 Agent 设计(原文:"instead of writing tools and MCP servers the way we'd write functions and APIs for other developers… we need to design them for agents",该引述经提取工具轻微压缩,语义完整)。

五条原则(S4):

1. 选对要实现的工具(和不要实现的):"More tools don't always lead to better outcomes."(工具多≠效果好);把 1:1 包装原始 API 端点是常见错误
2. 命名空间划边界:相关工具用公共前缀,如 asana_search、asana_projects_search;但前缀 vs 后缀命名对评测有 "non-trivial effects" 且因模型而异——用自家评测定方案
3. 返回有意义的上下文:避免 uuid、256px_image_url、mime_type 这类低层技术标识;改用 name、image_url、file_type;把任意 UUID 解析成自然语言标识符,"significantly improves Claude's precision in retrieval tasks by reducing hallucinations"(显著提升检索精度、减少幻觉)
4. token 效率:实现分页、范围选择、过滤、截断并给合理默认值;"Claude Code caps tool responses at 25,000 tokens by default";错误信息要可执行,而非裸错误码/堆栈
5. 描述当文档写:像给新同事做 onboarding 一样写工具描述;参数名要无歧义——"instead of a parameter named user, try a parameter named user_id";"Even small refinements to tool descriptions can yield dramatic improvements."

响应格式:没有万能答案(逐字): "there is no one-size-fits-all solution"——XML/JSON/Markdown 都可能影响评测表现,LLM 对接近训练数据分布的格式表现更好,应基于自己的评测选;推荐暴露 response_format 枚举(concise/detailed)让 Agent 自选详细度,Slack 示例中简洁模式约省 2/3 token。

工具整合(与 Agent 工具服务选型直接相关,逐字):

"Instead of implementing a list_users, list_events, and create_event tools, consider implementing a schedule_event tool"
(与其实现 list_users、list_events、create_event 三个工具,不如实现一个 schedule_event 工具。)

以及:"Too many tools or overlapping tools can also distract agents from pursuing efficient strategies."(工具太多或互相重叠会让 Agent 分心,不去走高效路径。)

3. 五风格横向对比表(综合 S1–S6)

表中 SSE 与 WebSocket 两列的知识基础来自 S3 全文精读;REST/GraphQL/gRPC 列来自 S1、S5;标注 S6 的条目仅有搜索摘要级证据。

4. Agent 工具服务选型表(本次精读的核心交付)

先明确两层决策:(a) 工具服务用什么协议风格暴露;(b) Agent 会话本身的流式通道用什么。 两层可以混搭,而且通常应该混搭。

4.1 工具服务层( Agent 调工具 )

4.2 Agent 会话层(用户 ↔ Agent 的交互通道)

4.3 选型速判(三条心法,均有原文支撑)

1. 先问方向,再问风格。 交互是"客户端拉"还是"服务器推"?单向用 REST/RPC + SSE,双向高频才用 WebSocket/gRPC bidi。——S3:"WebSockets and SSE aren't competitors; they solve different shapes of problems."
2. 按边界组合,不要全线统一。 ——S1:"Most production systems do not choose a single API style. They choose boundaries." 典型生产组合:边缘 REST/GraphQL + 内部 gRPC + 面向 Agent 的 MCP(JSON-RPC)+ 会话层 SSE。
3. Agent 工具不等于人类 API 的缩水版。 ——S4:"Tools are a new kind of software which reflects a contract between deterministic systems and non-deterministic agents." 工具数量、命名、响应形状都按 Agent 的评测来定,而不是照搬 REST 资源建模。

4.4 一个值得注意的信号:为什么 MCP 不用 WebSocket

MCP 旧版(2024-11-05)传输是 HTTP+SSE,新版(2025-03-26 起)改为 Streamable HTTP,仍以"HTTP POST + 可选 SSE"为核心(S2)。结合 S3/S6 可还原其设计逻辑:Agent 与工具服务的消息模式是客户端发起请求 + 服务端偶尔主动推送,这恰好落在 SSE 的能力甜区;WebSocket 的全双工、有状态连接在此是纯负担(粘性会话、代理不友好、无原生重连)。而双向性需求由"多个短 POST + 独立 GET-SSE 流"的组合满足,还顺带获得了 HTTP 基础设施(鉴权、负载均衡、续传头)的全部兼容性。

5. 七维提取(主题整体)

5.1 核心问题

为一个系统(尤其是带 Agent 的系统)选择 API 风格时,如何在灵活性、简单性、效率、控制力之间做权衡(S1),并把"交互建模风格(REST/GraphQL/gRPC)"与"推送通道(SSE/WebSocket)"两个正交决策分开,再落到 Agent 工具服务的具体工程选择上。

5.2 主要主张

1. 五种风格解决不同形状的问题,错误用法是"选一个用到底"(S1:"The trap isn't choosing the wrong one. It's choosing one and using it everywhere.")。
2. 生产系统的答案是按边界混合:边缘 REST/GraphQL、内部 gRPC、会话推送 SSE(S1 + S3 + S6)。
3. 对 LLM 应用,SSE 是默认选项,WebSocket 只在生成过程中需要客户端高频回推时使用(S3:"…WebSockets are massive overkill";S6:各主流 LLM API 皆用 SSE)。
4. Agent 工具服务的通用底座是 MCP:JSON-RPC 2.0 消息 + stdio/Streamable HTTP 传输(S2),它验证了"RPC 心智 + SSE 推送 + HTTP 兼容"的混搭在 Agent 语境下是主流路线。
5. 工具接口的设计原则独立于传输协议:少而整合、命名空间、自然语言标识符、token 效率、可执行错误(S4)。

5.3 方法

对比分析(S1 五风格逐维度表)、规范文本精读(S2、S5 官方规范级证据)、工程实战复盘(S3 含评论区勘误)、厂商一手工程经验(S4,Anthropic 自家评测结论)。本次笔记采用五来源交叉验证:同一结论(如"SSE 适合 LLM 流")至少有两处独立来源(S3 全文精读 + S6 搜索级多文)。

5.4 数据与证据

• 规范级(最强):S2 MCP 规范原文对 Streamable HTTP 的 MUST/SHOULD 级要求(单端点、Accept 双类型、Origin 校验、Last-Event-ID 续传、Mcp-Session-Id);S5 gRPC 四种流式与 deadline/cancellation 语义的官方定义。
• 定性论证(中):S1 三风格优劣清单与边界论;S3 的 WS 四类基础设施成本与"90% 应用过度"论断;S4 的 token 效率数据点(Claude Code 工具响应默认上限 25,000 token;Slack 简洁模式约省 2/3 token)。
• 搜索级(弱,未精读):S6 中"主流 LLM 提供商均采用 SSE"、AWS"REST 通常 HTTP/1.1 / gRPC 需 HTTP/2"、Nginx SSE 缓冲与无界缓冲区内存泄漏等生产坑。
• 缺口:全部来源均无跨风格端到端延迟/吞吐基准;gRPC "二进制比 JSON 更快更小"仅是常识级宣称(S1 自认无数字);GraphQL resolver N+1 问题只有定性描述无量化。

5.5 结论

选型不是单选题而是分层组合题:① 工具服务层——本地用 MCP stdio,远程/多客户端用 MCP Streamable HTTP,内部高频走裸 gRPC,对第三方开放走 REST;② 会话层——token 流/进度推送用 SSE(行业事实标准,基础设施全兼容),仅语音级双向或高频回推才上 WebSocket/gRPC 双向流;③ 工具的"内容设计"(数量、命名、响应形状)按 S4 原则做,与协议选择正交且同样影响 Agent 表现。

5.6 局限

• 证据局限:无定量基准(S1 明示定性;S2/S5 是规范不涉及性能);S6/S7 仅有搜索摘要级证据,其中 S7(Medium SSE vs WebSocket in Go)抓取超时未能精读,其结论只经搜索摘要转述。
• 来源局限:S3 是个人博客(dev.to),其"90%""10+ 次/秒"为经验值而非测量;评论区勘误说明此类文章的代码示例可能有坑,不能照抄。
• 时效局限:MCP 传输规范以 2025-06-18 版为准,旧 HTTP+SSE 传输已弃用但仍在兼容期;S4 的评测结论(前缀命名、response_format)明确说"因模型而异",换了模型需重测。
• 范围局限:未覆盖 GraphQL Subscription 的工程细节、gRPC-Web 的具体代理配置、SSE 在 HTTP/1.1 下每域 6 连接限制(S3 精读提取明确说"未讨论");未对比 HTTP/3/QUIC 对 WS/SSE 的影响(超出全部来源范围)。
• 推断声明:4.4 节"MCP 为何不用 WebSocket"是从 S2 + S3/S6 还原的设计逻辑推断,规范原文未给动机说明——这是我的推断,不是规范声明。

5.7 对我的启发

1. 给 Agent 项目选型时,默认组合直接抄 MCP 的答案:JSON-RPC 风格消息 + stdio(本地)/ Streamable HTTP + SSE(远程),不要为"新技术冲动"上 WebSocket——S2 与 S3/S6 形成闭环证据。
2. 工具设计比传输协议更影响 Agent 效果(S4):把 1:1 包装 REST 端点改成聚合工具(如 schedule_event 代替 list_users+list_events+create_event)、给响应加 response_format 开关、UUID 换自然语言名——这些是零协议成本的收益,值得在任何现有工具上先做。
3. 写 SSE 续传要一次做对(S3 勘误):id: 行 + 单调序列号 + 服务端缓冲重放,三者缺一不可;宣称可续传却不重放比不宣称更糟。
4. "选择边界"可以直接落成架构图(S1):以后评审 API 设计文档时,先问三件事——这个接口的消费者是谁(浏览器/第三方/内部服务/Agent)?数据形状会不会频繁变?有没有服务器→客户端的推送需求?三问答完,风格基本自选。
5. 取消语义要在工具层显式设计(S5):gRPC "取消不回滚"、"双方各自判定成败"提醒我:Agent 工具调用必须是幂等的,长任务要有取消通知(MCP 的 CancelledNotification)与补偿路径。

6. 重要原文引述汇总(速查)

7. 本次学到什么

1. 把"风格"与"通道"两个正交决策拆开,选型题就从五选一变成两次二选一,错误率骤降;MCP 规范本身就是这个拆法的活标本(JSON-RPC 消息层 × stdio/HTTP+SSE 传输层)。
2. 推送通道的默认答案是 SSE,不是 WebSocket——判断标准只有一条:生成/推送进行中,客户端要不要高频回推。
3. Agent 工具是"确定性系统与非确定性 Agent 的契约":协议选型只解决"怎么传",工具的数量、命名、响应形状决定 Agent"用得好不好",后者往往收益更大且成本更低。
4. 规范文档(MUST/SHOULD/MAY)是最便宜的一手证据:比博客对比文可靠一个量级,精读优先级应最高。