【技术教程】4种主流的API设计风格

介绍

API（Application Programming Interface）是现代软件的构建块之一，它允许不同的应用程序之间进行通信和协作，进而使得开发者能够创建出更为动态、灵活且具有扩展性的软件。随着互联网技术的不断发展，各种API规范也随之涌现，其中最常见的API风格包括：RESTful API、GraphQL API、RPC API和SOAP API。

RESTful API：Web 服务的 “轻骑兵”

RESTful API 是一种基于 HTTP 协议设计的 API 架构风格，遵循表述性状态转移（REST）原则。它的核心在于将一切事物都抽象为资源，每个资源都用唯一的 URL 进行标识，就像现实生活中每个地址都对应着唯一的位置一样。在操作资源时，RESTful API 使用标准的 HTTP 方法，如 GET（获取资源）、POST（创建资源）、PUT（更新资源）、DELETE（删除资源） ，这些方法就像是对资源进行的不同操作指令。​

RESTful API 严格遵循六大原则，包括客户端 – 服务器架构，将前端和后端分离，各自独立发展；无状态性，每个请求都包含完成自身所需的所有信息，服务器不保存客户端状态，这大大简化了服务器的设计，也使得系统更容易扩展；可缓存性，响应数据可被缓存，减少重复请求，提高性能，就像浏览器缓存网页一样；统一接口，所有 API 都遵循相同的规则和格式，降低了开发和维护的难度；分层系统，系统可以有多层，各层各司其职，提高了系统的可扩展性和安全性；按需代码（可选），服务器可向客户端发送可执行代码，增强客户端功能。​

RESTful API 凭借自身独特的优势，在众多 Web 应用场景中得到了广泛应用。它简单易懂，由于基于 HTTP 协议，开发人员可以轻松上手，减少了学习成本。同时，它是轻量级的，不需要额外的复杂协议，能够快速响应客户端请求。其具有良好的可扩展性，方便添加新功能，适应业务的不断变化，跨平台的特性也让它不受特定平台限制，在不同操作系统和设备上都能稳定运行。以电商平台为例，在商品管理、订单处理、用户信息获取等方面，RESTful API 发挥着重要作用，通过统一的接口和标准的 HTTP 方法，实现了前端与后端的数据交互。​

然而，RESTful API 并非十全十美。在一些复杂的数据获取场景中，它可能会出现 “过获取（Over-fetching）” 和 “欠获取（Under-fetching）” 的问题。“过获取” 指客户端收到不需要的字段，造成数据冗余和网络带宽的浪费；“欠获取” 则是单次请求无法获取关联资源，需要多次请求，增加了网络延迟和服务器负载。比如在获取用户信息时，可能附带了用户的订单信息，但客户端此时只需要用户基本资料，订单信息就属于过获取的数据；而当客户端需要获取用户及其关联的多个不同类型的资源时，可能需要多次发起不同的请求，这就是欠获取的体现。

下面是RESTful的一些关键的设计原则和约束

1. 基于资源： RESTful API 的设计应该以资源为中心。所有的服务都应该被表示成资源，例如用户、订单、商品等等。
2. 基于 HTTP 协议： RESTful API 设计依赖于 HTTP 协议，使用常见的 HTTP 动词（方法），例如 GET、POST、PUT 和 DELETE。
3. 无状态（Stateless）： RESTful API 是一种无状态的 API 设计。这意味着服务不会存储客户端的状态，而是通过客户端发送的请求来判断如何响应。
4. 缓存： RESTful API 支持缓存机制，以提高响应时间和降低网络延迟。
5. 统一接口： RESTful API 定义了一套统一的接口，使得客户端和服务端之间可以以统一的方式进行通信和交互。

GraphQL API：数据查询的 “精准射手”

GraphQL 是一种用于 API 的查询语言，同时也是一个用于执行查询的服务器端运行时。它由 Facebook 于 2012 年开发，并在 2015 年开源 ，旨在解决传统 RESTful API 在数据获取方面的一些痛点。​

GraphQL 的核心概念围绕着模式（Schema）、查询（Query）、变更（Mutation）和解析器（Resolver）展开。模式就像是一份详细的数据字典，它使用强类型系统，以 GraphQL 模式定义语言（SDL）记录了所有可以在 API 中查询的数据类型，以及这些类型与用户可用操作之间的关系，明确了 API 能够提供哪些数据和操作。查询是客户端向 GraphQL 服务器发出的请求，客户端可以在查询中精确指定自己想要获取的数据字段，其结构通常与期望的响应数据结构一致，这让数据获取的需求变得清晰明了。变更则用于在服务器上执行创建、更新或删除数据的操作，和查询类似，变更操作也会根据模式及其定义进行验证后再执行。解析器负责为模式中的每个字段提供数据，它可以从数据库、云服务等各种数据源中检索数据，将 GraphQL 操作转化为实际的数据响应。​

与 RESTful API 相比，GraphQL 在数据获取方面具有显著优势。它允许客户端精确地请求所需的数据，避免了 “过获取” 和 “欠获取” 的问题，大大减少了不必要的数据传输，提高了数据传输效率和应用程序的性能。例如，在一个社交媒体应用中，客户端如果只需要获取用户的姓名和头像，使用 RESTful API 可能会返回用户的所有信息，包括详细的个人资料、动态等，造成数据冗余；而 GraphQL 则可以让客户端只获取指定的姓名和头像字段。GraphQL 使用单一端点提供服务，客户端通过这一个统一的 API 接口就能获取所需的所有数据，不像 RESTful API 每个资源都有不同的端点，这极大地简化了 API 的管理和维护。​

GraphQL 还具备强大的灵活性和可扩展性。开发人员可以轻松定义和修改数据模型，无需担心影响现有的客户端代码。当业务需求发生变化，需要添加新的数据字段或修改数据结构时，GraphQL 的这种特性使得 API 能够轻松演进。而且，通过 GraphQL 的订阅功能，前端可以实时获取后端数据的更新，这为需要实时数据的应用场景，如实时聊天、股票行情显示等，提供了良好的支持。​

不过，GraphQL 也存在一些劣势。对于熟悉 RESTful 请求的开发者来说，学习 GraphQL 需要花费一定的时间和精力，掌握其查询语言和 Schema 设计等知识。在服务端，开发者可能需要投入更多时间来开发和维护数据模型，特别是处理复杂业务逻辑时，难度会更大。由于 GraphQL 查询的动态特性，它难以直接应用传统的 HTTP 缓存机制，设计有效的缓存策略以优化性能成为一项具有挑战性的任务。

GraphQL API遵循以下设计原则：

1. 强类型：GraphQL是一种强类型的查询语言，它的类型系统有严格的约束、具备清晰的层次关系。
2. 单一端点：所有的GraphQL API都从同一个端点获取相应的数据。
3. 可组合性：客户端可以通过组合不同的查询来获取所需的数据。
4. 可预测性：GraphQL查询语句在语法上是非常明确的，因此对于客户端来说是可以预测的。
5. 客户端驱动：GraphQL API由客户端发起，客户端控制数据传输和终端的兼容性。
6. 自我描述的API：GraphQL API使用类型系统来描述其功能和数据类型，因而具有自我描述特性。

RPC API：远程调用的 “快捷通道”

RPC（Remote Procedure Call）即远程过程调用，是一种计算机通信协议，它允许程序像调用本地函数一样调用远程服务器上的函数，而无需开发者显式地编写网络通信细节，极大地简化了分布式系统的开发。​

这是最常见的方式，RPC说的是本地调用远程的方法，面向的是过程。

• RPC形式的API组织形态是类和方法，或者说领域和行为。
• 因此API的命名往往是一个动词，比如GetUserInfo和CreateUser。
• 因为URI会非常多而且往往没有一些约定规范，所以需要有详细的文档。
• 也是因为无拘无束，HTTP方法基本只用GET和POST，设计起来比较简单。

RPC 的调用流程有着清晰的步骤。首先，客户端发起一个本地调用，该调用看似是对本地函数的调用，但实际上是通过客户端存根（Stub）进行的 。客户端存根负责将调用的方法名、参数等信息进行序列化，把这些数据转化为可以在网络上传输的格式，然后通过网络将请求发送到服务端。服务端接收到请求后，服务器存根对请求数据进行反序列化，还原出调用的方法名和参数，接着调用实际的服务方法进行处理。处理完成后，服务端将结果返回给服务器存根，服务器存根再将结果序列化，并通过网络发送回客户端。客户端存根接收到返回的数据后，进行反序列化操作，将结果以合适的形式返回给客户端调用方，至此，整个 RPC 调用过程完成。​

以一个简单的电商订单处理系统为例，假设订单服务和库存服务分别部署在不同的服务器上。当用户下单时，订单服务需要调用库存服务来检查库存并扣减相应数量。使用 RPC，订单服务就可以像调用本地函数一样调用库存服务的检查库存和扣减库存方法，而不用关心网络传输、数据序列化与反序列化等复杂细节。​

SOAP API：企业级应用的 “安全卫士”

SOAP 是简单对象访问协议（Simple Object Access Protocol）的缩写 ，是一种应用程序之间进行通信的协议，主要用于通过 HTTP/HTTPS 传输数据。它只与 XML 一起工作，并有着自己的编码规则和约定，这使得无论应用程序建立在何种不同的平台上，使用何种不同的语言，都能借助 SOAP 实现通信。自 1998 年诞生以来，SOAP 凭借自身特性在企业级应用领域一直保持着重要地位。​

SOAP 消息有着独特且严谨的结构，包含四个关键元素。信封（Envelope）是最基本的元素，它就像是一个 “包裹”，将整个文档标识为 SOAP 消息，而非其他类型的 XML 文档，消息以信封的标签开始和结束 。标头（Header）是一个可选元素，借助 SOAP 模块，开发者可以为其添加新特性和功能，一个信封中可以存在多个标题，比如在进行跨境电商交易时，标头中可能会包含交易的安全凭证、事务 ID 等重要信息，用于保障交易的安全性和可追溯性。正文（body）是消息的核心部分，包含着实际的消息内容，无论是请求信息还是响应数据都在其中，是必不可少的元素，如订单创建请求中的商品信息、数量、价格等都在正文中体现。Fault 是用于错误消息和状态信息的元素，如果在处理过程中出现问题，比如 SOAP 格式错误、数据类型不匹配等，就会通过 Fault 元素进行反馈，尽管它在技术上是可选的，但为了能及时发现和处理问题，通常建议包含。​

SOAP 的强类型系统通过 WSDL（Web Services Description Language）文件定义，WSDL 充当着机器可读的接口契约，它详细地描述了服务端点、操作类型、消息格式和数据类型。以银行系统的转账操作为例，WSDL 会明确规定转账服务的端点地址，操作类型是转账，消息格式中会规定请求和响应的具体 XML 结构，数据类型则会说明金额、账号等数据的类型要求。这种严格的契约优先设计，使得 SOAP 在对安全性和事务完整性要求极高的场景中得到广泛应用。在金融支付领域，每一笔交易都关乎着巨大的资金流动和用户的财产安全，SOAP 内置的 WS-Security 标准支持端到端消息加密和数字签名，能够满足 PCI DSS（Payment Card Industry Data Security Standard，支付卡行业数据安全标准）等合规要求，确保交易的安全性和可靠性，防止数据泄露和篡改。在企业应用集成中，不同的系统可能来自不同的供应商，有着不同的技术架构和数据格式，SOAP 的严格标准和强大的兼容性，使其能够有效地整合这些系统，实现数据的顺畅交换和业务流程的协同。​

XML 格式虽然具有良好的可读性和自我描述性，但它的文本量较多，占用大量带宽，导致 SOAP 消息通常比较冗长，在数据传输过程中会消耗更多的网络资源，影响传输效率，尤其在网络带宽有限的情况下，这种劣势更加明显。WSDL 文件的学习曲线较为陡峭，开发者需要花费大量时间和精力去理解和掌握其复杂的规范和语法，这增加了开发和维护的难度。而且，由于 SOAP 协议的严格性和复杂性，它在面对一些快速迭代、需求灵活多变的互联网应用场景时，显得不够灵活，难以快速响应业务的变化。

抉择

在实际的软件开发项目中，选择合适的 API 风格是一项至关重要的决策，它直接影响到系统的性能、可维护性、开发效率以及与其他系统的集成能力。以下是在不同场景下选择四大 API 风格的一些建议：​

RESTful API​

• 简单 Web 应用场景：如果开发一个功能相对简单、数据结构不太复杂的 Web 应用，如小型博客网站、简单的企业展示网站等，RESTful API 是理想之选。它基于 HTTP 协议，简单易懂，开发难度低，能够快速搭建起前后端的数据交互桥梁，方便前端获取和展示数据。​

• 数据缓存需求高的场景：由于 RESTful API 具有良好的可缓存性，对于那些对数据缓存有较高要求的应用，如新闻资讯类应用，大量的数据可以通过缓存减少重复请求，提高用户体验和应用性能。​

• 跨平台、跨语言交互场景：其跨平台的特性使得它在不同操作系统和设备上都能稳定运行，并且支持多种数据格式（如 JSON 和 XML） ，这使得它在需要与多种不同技术栈的系统进行交互时表现出色，例如一个电商平台需要与不同的支付系统、物流系统进行对接时，RESTful API 能够轻松实现。​

GraphQL API​

• 复杂数据需求场景：当应用需要处理复杂的数据关系和多样化的数据请求时，GraphQL API 能够大显身手。例如在大型社交网络应用中，用户可能需要获取自己的好友列表、好友动态、点赞评论等多种关联数据，并且根据不同的展示需求，对数据字段有精确的要求，GraphQL 允许客户端精确指定所需的数据，避免了数据的过度获取或不足获取，能够高效地满足这些复杂需求。​

• 频繁迭代的项目：对于业务需求变化频繁、需要快速迭代的项目，GraphQL 的灵活性和可扩展性使其成为优势选择。开发人员可以轻松定义和修改数据模型，无需担心影响现有的客户端代码，能够快速响应业务的变化，节省开发时间和成本。​

• 对实时数据有要求的场景：借助 GraphQL 的订阅功能，前端可以实时获取后端数据的更新，对于实时聊天、在线游戏、股票行情显示等需要实时数据的应用场景，GraphQL 能够提供良好的支持，确保用户能够及时获取最新信息。​

RPC API​

• 高性能需求场景：如果项目对性能要求极高，追求低延迟和高吞吐量，如金融交易系统、大规模分布式计算系统等，RPC API 是不错的选择。它通过隐藏底层网络通信细节，以类似本地函数调用的方式进行远程调用，减少了网络开销，能够快速地处理大量请求，满足系统对响应时间的苛刻要求。​

• 跨语言调用场景：当需要在不同语言开发的系统之间进行通信和协作时，像 gRPC 这样支持多语言开发的 RPC 框架就发挥了重要作用。不同技术栈的团队可以方便地使用 RPC 进行分布式系统的构建，实现跨语言的服务通信，例如一个由 Java 后端和 Python 数据分析模块组成的大数据处理系统，可以通过 RPC 实现高效的交互。​

• 微服务架构场景：在微服务架构中，各个微服务之间需要频繁地进行通信和数据交互，RPC 能够提供高效的通信方式，使得微服务之间的协作更加紧密，提高系统整体性能，促进系统的高效运行。例如在一个电商微服务架构中，订单服务、库存服务、支付服务等之间可以通过 RPC 实现快速的数据交互和业务流程的协同。​

SOAP API​

• 对安全和事务要求高的场景：在金融支付、电子政务等领域，数据的安全性和事务的完整性至关重要，SOAP API 凭借其内置的 WS-Security 标准支持端到端消息加密和数字签名，以及严格的契约优先设计，能够满足 PCI DSS 等合规要求，确保数据传输的安全性和可靠性，防止数据泄露和篡改，保障业务的稳定运行。​

• 企业应用集成场景：企业内部通常存在多个不同的系统，这些系统可能来自不同的供应商，有着不同的技术架构和数据格式。SOAP 的严格标准和强大的兼容性，使其能够有效地整合这些系统，实现数据的顺畅交换和业务流程的协同，例如在企业的 ERP（企业资源计划）系统与 CRM（客户关系管理）系统集成时，SOAP API 可以确保两个系统之间的数据交互准确无误。