43,486 讀數

系统设计备忘单：API 样式 - REST、GraphQL、WebSocket、Webhook、RPC/gRPC、SOAP

经过 Aleksandr Gavrilenko14m2023/10/24

太長; 讀書

API 架构是指规定软件组件如何交互的一组规则、协议和工具。 API 的架构不仅仅在于促进通信，还在于促进通信。它还涉及确保这种通信高效、安全和可扩展。设计良好的 API 架构可以显着提高系统的性能，而设计不当的 API 架构可能会导致瓶颈、安全漏洞和维护噩梦。

featured image - 系统设计备忘单：API 样式 - REST、GraphQL、WebSocket、Webhook、RPC/gRPC、SOAP

这是一系列文章的延续，我在其中简要介绍了系统架构设计中特定主题的要点。第一篇文章可以在这里阅读

API 架构是指规定软件组件如何交互的一组规则、协议和工具。 API 的架构不仅仅在于促进通信，还在于促进通信。它还涉及确保这种通信高效、安全和可扩展。

设计良好的 API 架构可以显着提高系统的性能，而设计不当的 API 架构可能会导致瓶颈、安全漏洞和维护噩梦。

不同风格的 API 架构

最常见的API设计风格：

REST （表述性状态传输）是最常用的风格，它使用标准方法和 HTTP 协议。它基于无状态、客户端-服务器架构和可缓存性等原则。它通常用于前端客户端和后端服务之间。
GraphQL是一种 API 查询语言。与 REST 不同，REST 为每个资源公开一组固定的端点，GraphQL 允许客户端准确请求他们需要的数据，从而减少过度获取。
WebSocket是一种允许通过 TCP 进行双向通信的协议。客户端使用网络套接字从后端系统获取实时更新。
Webhook是一种允许一个系统实时通知另一个系统有关特定事件的机制。它是用户定义的 HTTP 回调。
RPC (gRPC)是一种协议，一个服务可以使用该协议向网络中另一台计算机上的服务请求过程/方法。通常，它是为低延迟、高速通信而设计的。
SOAP是一种用于交换结构化信息以实现 Web 服务的协议。它依赖于 XML，并以其稳健性和安全特性而闻名，目前被认为是遗留协议。

让我们分别看看每个协议的优点、缺点和用例。

休息

REST是一种使用标准约定和协议的架构风格，使其易于理解和实现。它的无状态特性和对标准 HTTP 方法的使用使其成为构建基于 Web 的 API 的流行选择。

虽然 REST 长期以来一直是构建 API 的事实上的标准，但 GraphQL 等其他风格也已经出现，为查询和操作数据提供了不同的范例。

格式：XML、JSON、HTML、纯文本

传输协议：HTTP/HTTPS

主要概念和特征

资源：在 REST 中，一切都是资源。资源是一个对象，具有类型、关联数据、与其他资源的关系以及一组对其进行操作的方法。资源由其 URI（通常是 URL）标识。
CRUD 操作：REST 服务通常直接映射到资源上的 CRUD（创建、读取、更新、删除）操作。
HTTP 方法：REST 系统使用标准 HTTP 方法：
- GET：检索资源。
- POST：创建新资源。
- PUT/PATCH：更新现有资源。
- 删除：删除资源。
状态代码：REST API 使用标准 HTTP 状态代码来指示 API 请求的成功或失败：
- 2xx - 认可和成功
  - 200 - 好的
  - 201 - 创建
  - 202 - 已接受
- 3xx - 重定向
  - 301 - 永久移动
  - 302 - 找到
  - 303 - 查看其他
- 4xx - 客户端错误
  - 400 - 错误请求
  - 401 - 未经授权
  - 403 - 禁忌
  - 404 - 未找到
  - 405 - 方法不允许
- 5xx - 服务器错误
  - 500内部服务器错误
  - 501 - 未实施
  - 502错误的网关
  - 503服务不可用
  - 504网关超时
无状态：从客户端到服务器的每个请求都必须包含理解和处理该请求所需的所有信息。服务器不应在请求之间存储有关客户端状态的任何信息。
客户端-服务器：REST 基于客户端-服务器模型。客户端负责用户界面和体验，而服务器负责处理请求、处理业务逻辑和存储数据。
可缓存：来自服务器的响应可以由客户端缓存。服务器必须指示响应是否可缓存。
分层系统：客户端通常无法区分它是直接连接到终端服务器还是中介。中间服务器可以通过启用负载平衡和提供共享缓存来提高系统的可扩展性。
HATEOAS：超媒体作为应用程序的引擎 Stat 是一种 REST Web 服务原则，使客户端能够完全基于服务器在其响应中动态提供的超媒体与 Web 应用程序进行交互和导航，从而促进松散耦合和可发现性。

用例

Web 服务：许多 Web 服务通过 REST API 公开其功能，允许第三方开发人员集成和扩展其服务。

移动应用程序：移动应用程序通常使用 REST API 与后端服务器通信以获取和发送数据。

单页应用程序 (SPA) ：SPA 使用 REST API 动态加载内容，无需刷新整个页面。

系统之间的集成：组织内的系统可以使用 REST API 进行通信和共享数据。

例子

要求

获取“/用户/42”

{ "id": 42, "name": "Alex", "links": { "role": "/user/42/role" } }

GraphQL

GraphQL提供了一种更灵活、更强大、更高效的 API 构建方法，特别是在复杂的系统中或当前端需要高度灵活性时。它将部分责任从服务器转移到客户端，允许客户端指定其数据要求。

虽然它不能在所有场景中替代 REST，但它在许多情况下提供了令人信服的替代方案，特别是当应用程序变得更加网络化和分布式时。

格式：JSON

传输协议：HTTP/HTTPS

主要概念和特征

API 的查询语言：它允许客户端请求他们需要的数据，从而可以在单个请求中获取所有所需的信息。

类型系统：GraphQL API 是根据类型和字段而不是端点来组织的。它使用强类型系统来定义 API 的功能。 API 中公开的所有类型均使用 GraphQL 架构定义语言 (SDL) 写在架构中。

单一端点：与 REST 不同，在 REST 中，不同的资源可能有多个端点，而在 GraphQL 中，您通常会公开一个表示服务完整功能集的端点。

解析器：在服务器端，解析器收集查询中描述的数据。

通过订阅进行实时更新：除了查询数据之外，GraphQL 还内置对使用订阅进行实时更新的支持。

Introspective ：可以查询 GraphQL 服务器支持的类型。这在客户端和服务器之间创建了强有力的契约，允许使用工具和更好的验证。

用例

灵活的前端：对于带宽至关重要的应用程序（尤其是移动应用程序），您希望最大限度地减少从服务器获取的数据。

聚合微服务：如果您有多个微服务，可以引入 GraphQL 层将这些服务的数据聚合到统一的 API 中。

实时应用程序：凭借其订阅系统，GraphQL 非常适合需要实时数据的应用程序，例如聊天应用程序、实时体育更新等。

版本无关的 API ：使用 REST，一旦引入更改，您通常需要对 API 进行版本控制。使用 GraphQL，客户端仅请求所需的数据，因此添加新字段或类型不会造成重大更改。

例子

要求

GET “/graphql?query=user(id:42){ 名称角色 { id 名称 } }”

{ "data": { "user": { "id": 42, "name": "Alex", "role": { "id": 1, "name": "admin" } } } }

WebSocket

WebSockets通过单个长期连接提供全双工通信通道，允许客户端和服务器之间进行实时数据交换。这使其成为交互式和高性能 Web 应用程序的理想选择。

格式：二进制

传输协议：TCP

主要概念和特征

持久连接：与传统的请求响应模型不同，WebSocket 提供保持开放的全双工通信通道，允许实时数据交换。

升级握手：WebSockets 作为 HTTP 请求启动，如果服务器支持，则将其升级为 WebSocket 连接。这是通过“Upgrade”标头完成的。

帧：一旦建立连接，数据就会以帧的形式传输。文本和二进制数据都可以通过这些帧发送。

低延迟：WebSocket 允许客户端和服务器之间直接通信，而无需为每次交换打开新连接的开销。这导致更快的数据交换。

双向：客户端和服务器都可以独立地向对方发送消息。

更少的开销：在初始连接之后，数据帧需要发送更少的字节，从而比重复建立 HTTP 连接更少的开销和更好的性能。

协议和扩展：WebSocket 支持子协议和扩展，允许在基本 WebSocket 协议之上使用标准化和自定义协议。

用例

在线游戏：实时多人游戏，玩家的行为必须立即反映给其他玩家。

协作工具：像 Google Docs 这样的应用程序，多个用户可以同时编辑文档并实时查看彼此的更改。

金融应用：股票价格需要实时更新的股票交易平台。

通知：用户需要接收实时通知的任何应用程序，例如社交媒体平台或消息应用程序。

实时推送：新闻网站或社交媒体平台，将新帖子或更新实时传输给用户。

例子

要求

获取“ws://site:8181”

HTTP/1.1 101 切换协议

网络钩子

Webhook是由特定Web应用程序事件触发的用户定义的HTTP回调，允许实时数据更新和不同系统之间的集成。

格式：XML、JSON、纯文本

传输协议：HTTP/HTTPS

主要概念和特征

事件驱动：Webhooks 通常用于表示事件已发生。 Webhook 不是定期请求数据，而是实时提供数据，彻底颠覆了传统的请求-响应模型。

回调机制：Webhook本质上是一种用户定义的回调机制。当特定事件发生时，源站点会对目标站点提供的 URI 进行 HTTP 回调，然后目标站点将采取特定操作。

Payload ：当 webhook 被触发时，源站点将向目标站点发送数据（payload）。该数据通常采用 JSON 或 XML 的形式。

实时：Webhooks 允许应用程序获取实时数据，使其具有高度响应能力。

可定制：用户或开发人员通常可以定义他们想要通知的特定事件。

安全性：由于 Webhooks 涉及对用户定义的 HTTP 端点进行回调，因此它们可能会带来安全挑战。确保端点安全、数据经过验证并且可能经过加密至关重要。

用例

持续集成和部署（CI/CD） ：推送代码或合并拉取请求时触发构建和部署。

内容管理系统 (CMS) ：内容更新、发布或删除时通知下游系统。

支付网关：向电子商务平台通知交易结果，例如支付成功、交易失败或退款。

社交媒体集成：接收有关社交媒体平台上的新帖子、提及或其他相关事件的通知。

IoT（物联网） ：设备或传感器可以触发 Webhook 来通知其他系统或服务有关特定事件或数据读取的信息。

例子

要求

获取“ https://external-site/webhooks?url=http://site/service-h/api&name=name ”

{ "webhook_id": 12 }

RPC 和 gRPC

RPC （远程过程调用）是一种协议，允许程序在另一个地址空间执行过程或子例程，从而实现分布式系统之间的无缝通信和数据交换。

gRPC (Google RPC) 是一个建立在 RPC 之上的现代开源框架，使用 HTTP/2 进行传输，使用 Protocol Buffers 作为接口描述语言，提供身份验证、负载平衡等功能，以促进高效、稳健的通信微服务之间。

远程过程调用

格式：JSON、XML、Protobuf、Thrift、FlatBuffers

传输协议：各种

主要概念和特征

定义：RPC 允许程序使过程（子例程）在另一个地址空间（通常在共享网络上的另一台计算机上）执行。这就像调用在与调用者不同的机器上执行的函数。

存根：在 RPC 上下文中，存根是由工具生成的代码片段，允许本地和远程过程调用看起来相同。客户端有一个类似于远程过程的存根，服务器有一个存根，用于解压参数、调用实际过程，然后打包结果并发回。

默认同步：传统的 RPC 调用是阻塞的，这意味着客户端向服务器发送请求并在等待服务器响应时被阻塞。

语言中立：许多 RPC 系统允许不同的客户端和服务器实现进行通信，无论它们是用什么语言编写的。

紧耦合：RPC 通常要求客户端和服务器知道被调用的过程、其参数及其返回类型。

用例

分布式系统：RPC 通常用于分布式系统，其中系统的各个部分分布在不同的计算机或网络上，但需要像本地一样进行通信。

网络文件系统：NFS（网络文件系统）是远程执行文件操作的 RPC 的一个示例。

例子

要求

{ "method": "addUser", "params": [ "Alex" ] }

{ "id": 42, "name": "Alex", "error": null }

远程过程调用

格式：协议缓冲区

传输协议：HTTP/2

主要概念和特征

定义：gRPC是Google开发的开源RPC框架。它使用 HTTP/2 进行传输，使用协议缓冲区 (Protobuf) 作为接口描述语言，并提供身份验证、负载平衡功能等。

Protocol Buffers ：这是一种语言中立、平台中立、可扩展的机制，用于序列化结构化数据。通过 gRPC，您可以使用 Protobuf 定义服务方法和消息类型。

性能：gRPC 专为低延迟和高吞吐量通信而设计。 HTTP/2 允许通过单个连接复用多个调用并减少开销。

流式传输：gRPC 支持流式请求和响应，允许更复杂的用例，例如长期连接、实时更新等。

截止日期/超时：gRPC 允许客户端指定等待 RPC 完成的时间。服务器可以检查这一点并决定是否完成操作或中止（如果可能需要太长时间）。

可插拔：gRPC 旨在支持可插拔的身份验证、负载平衡、重试等。

语言中立：与 RPC 一样，gRPC 与语言无关。然而，使用 Protobuf 和 gRPC 工具，生成多种语言的客户端和服务器代码很容易。

用例

微服务：gRPC 由于其性能特征和轻松定义服务契约的能力而常用于微服务架构。

实时应用程序：由于 gRPC 支持流式传输，因此适用于服务器将数据实时推送到客户端的实时应用程序。

移动客户端：gRPC 的性能优势和流处理功能使其非常适合移动客户端与后端服务的通信。

例子

message User { int id = 1 string name = 2 } service UserService { rpc AddUser(User) returns (User); }

肥皂

SOAP （简单对象访问协议）是一种用于交换结构化信息以在计算机网络中实现 Web 服务的协议。它是一种基于 XML 的协议，允许运行在不同操作系统上的程序相互通信。

格式：XML

传输协议：HTTP/HTTPS、JMS、SMTP 等

主要概念和特征

基于 XML ：SOAP 消息采用 XML 格式并包含以下元素：
- Envelope ： SOAP 消息的根元素，它将 XML 文档定义为 SOAP 消息。
- 标头：包含在中间点或最终端点处理消息时使用的消息的任何可选属性。
- Body ：包含包含正在发送的消息的 XML 数据。
- 故障：可选的故障元素，提供有关处理消息时发生的错误的信息。
中立性：SOAP 可以与任何编程模型一起使用，并且不依赖于特定的模型。

独立性：可以在任何操作系统、任何语言上运行。

无状态：从客户端到服务器的每个请求都必须包含理解和处理该请求所需的所有信息。

内置错误处理：SOAP 消息中的Fault 元素用于错误报告。

标准化：基于明确定义的标准进行操作，包括 SOAP 规范本身以及相关标准，例如用于确保消息传递的 WS-ReliableMessaging、用于确保消息安全的 WS-Security 等。

用例

企业应用程序：由于 SOAP 的稳健性、可扩展性以及穿越防火墙和代理的能力，因此经常在企业环境中使用。

Web 服务：许多 Web 服务，尤其是较旧的 Web 服务，都使用 SOAP。这包括 Microsoft 和 IBM 等大公司提供的服务。

金融交易：SOAP 的内置安全性和可扩展性使其成为数据完整性和安全性至关重要的金融交易的良好选择。

电信：电信公司可能会使用 SOAP 进行计费等流程，其中不同的系统必须可靠地通信。

例子

要求

<?xml version="1.0"?> <soap:Envelope> <soap:Body> <m:AddUserRequest> <m:Name>Alex</m:Name> </m:AddUserRequest> </soap:Body> </soap:Envelope>

<?xml version="1.0"?> <soap:Envelope> <soap:Body> <m:AddUserResponse> <m:Id>42</m:Id> <m:Name>Alex</m:Name> </m:AddUserResponse> </soap:Body> </soap:Envelope>