【系统设计】API 设计：从基础知识到最佳实践
@TOC
推荐超级课程：
在本次我们将介绍 API 设计，从基础知识开始，逐步实现定义特殊 API 的最佳实践。
作为开发人员，您可能熟悉其中许多概念，但我将提供详细的解释以加深您的理解。
API 设计：电子商务示例
让我们考虑一下Shopify 等电子商务平台的 API ，如果您不熟悉的话，它是一个著名的电子商务平台，允许企业建立在线商店。
在 API 设计中，我们关注的是定义API 的输入（例如新产品的产品详细信息）和输出（例如某人查询产品时返回的信息）。
这意味着我们关注接口而不是底层实现
API设计和CRUD：
因此，重点主要在于定义如何向与电子商务 API 交互的用户或系统公开 CRUD 操作。
CRUD代表创建、读取、更新、删除。这些是任何数据驱动应用程序的基本操作。
例如，要添加新产品（创建），您可以向/api/products请求正文中发送产品详细信息的位置发出 POST 请求。
要检索产品（读取），您需要使用 GET 请求从 获取数据/products。
为了更新产品信息（Update），我们使用 PUT 或 PATCH 请求/products/:id，其中 id 是我们需要更新的产品的 id。
删除与更新类似；/products/:id我们向 id 是我们需要删除（删除）的产品发出 DELETE 请求。
通信协议和数据传输机制
另一部分是决定将使用的通信协议，如 HTTP、WebSocket 等，以及数据传输机制：JSON、XML 或协议缓冲区。
RESTful API 就是这种情况，但我们也有 GraphQL 或 gRPC 范例
API范式
API 有不同的范式，每个范式都有自己的一套协议和标准。
REST
**优点：**无状态：从客户端到服务器的每个请求都必须包含理解和完成请求所需的所有信息。使用标准 HTTP 方法（GET、POST、PUT、DELETE）。不同客户端（浏览器、移动应用程序）可以轻松使用。
**缺点：**这可能会导致数据过度获取或获取不足，因为可能需要更多端点来访问特定数据。
**特点：**支持分页、过滤（**limit**、**offset**）和排序。使用 JSON 进行数据交换。
GraphQL
**优点：**允许客户准确请求他们需要的内容，避免过度获取和获取不足。基于强类型模式的查询。
**缺点：**复杂的查询会影响服务器性能。所有请求都作为 POST 请求发送。
**特点：**通常以 HTTP 200 状态代码进行响应，即使出现错误，也会在响应正文中提供错误详细信息。
gRPC（谷歌远程过程调用）
**优点：**它基于 HTTP/2 构建，提供了多路复用和服务器推送等高级功能。使用 Protocol Buffers，这是一种语言中立、平台中立、可扩展的序列化结构化数据的方式。在带宽和资源方面高效，特别适合微服务。
**缺点：**与 JSON 相比，人类可读性较差。需要 HTTP/2 支持。
**特点：**支持数据流和双向通信。非常适合服务器到服务器通信。
API设计中的关系
在电子商务环境中，您可能存在用户与订单、订单与产品等关系。
设计端点来反映这些关系非常重要。例如，在这种情况下**GET /users/{userId}/orders**应该获取特定用户的订单。
GET 请求的查询、限制和幂等性
常见查询还包括用于分页的 和或用于过滤特定日期范围内的产品的**limit**和。这允许用户检索特定的数据集，而不会一次过多的信息使系统或用户不堪重负。**offset**``**startDate**``**endDate**
一个精心设计的 GET 请求是幂等的，这意味着多次调用它不会改变结果。
GET 请求永远不应该改变数据。它们仅用于检索。
向后兼容性和版本控制：
修改端点时，保持向后兼容性很重要。这意味着确保更改不会破坏现有客户。
版本控制：引入版本（如**/v2/products**）是处理重大更改的常见做法。
就 GraphQL 而言，添加新字段（v2 字段）而不删除旧字段有助于在不破坏现有客户端的情况下改进 API。
速率限制和 CORS
另一个最佳实践是设置速率限制。这用于控制用户在特定时间范围内可以发出的请求数量。这对于维护 API 的可靠性和可用性至关重要。它还可以防止 API 遭受 DDoS 攻击。
常见的做法是同时设置 CORS 设置 跨源资源共享 (CORS) 设置对于 Web 安全非常重要。它们控制哪些域可以访问您的 API，从而防止不必要的跨站点交互。