【API架构】REST API 设计的原则和最佳实践

这篇最佳实践文章面向对创建 RESTful Web 服务感兴趣的开发人员，这些服务提供跨多个服务套件的高可靠性和一致性；遵循这些准则；服务定位于内部和外部客户快速、广泛、公开采用。
这是一个完整的图表，可以轻松理解 REST API 的原理、方法和最佳实践。

现在，让我们从每个盒子的原理开始详细说明它。

六项原则/约束

1. 客户端-服务器：关注点分离是客户端-服务器约束背后的原则。通过将用户界面问题与数据存储问题分开，我们提高了用户界面跨多个平台的可移植性，并通过简化服务器组件提高了可扩展性。

2. 无状态：通信必须是无状态的，如客户端-无状态-服务器 (CSS) 风格。从客户端到服务器的每个请求都必须包含理解请求所需的所有信息。因此，会话状态完全保留在客户端上。

3. 可缓存：为了提高网络效率，我们添加了缓存约束以形成客户端-缓存-无状态-服务器风格。缓存约束要求数据响应带有隐式或显式标签为可缓存或不可缓存的请求。如果响应是可缓存的，则客户端缓存有权为以后的等效请求重用该响应数据。

4. 分层系统：客户端通常无法判断它是直接连接到终端服务器还是沿途的中介。中间服务器可以通过启用负载平衡和提供共享缓存来提高系统可扩展性。层也可以强制执行安全策略。

5. 按需代码：REST 允许通过下载和执行小程序或脚本形式的代码来扩展客户端功能。通过减少需要预先实现的功能数量来简化客户端。它允许在部署后下载功能，提高了系统的可扩展性。

6. 统一接口：通过将通用性的软件工程原理应用于组件接口，简化了整个系统架构，提高了交互的可见性。实现与它们提供的服务分离，这鼓励了独立的可进化性。REST 定义了四个接口约束：资源的识别、通过表示的资源操作、自描述消息和作为应用程序状态引擎的超媒体。

   1. 自描述消息：每条消息都包含足够的信息来描述如何处理消息。

   2. 基于资源：在请求中使用 URI 作为资源标识符来标识单个资源。资源本身在概念上与返回给客户端的表示分开。

   3. 通过表示操作资源：当客户端表示资源（包括附加的任何元数据）时，它有足够的信息来修改或删除服务器上的资源，前提是它有这样做的权限。

   4. 超媒体作为应用程序状态引擎 (HATEOAS)：客户端通过正文内容、查询字符串参数、请求标头和请求的 URI（资源名称）传递状态。服务通过正文内容、响应代码和响应头向客户端提供状态。

最佳实践

现在，让我们换个角度来了解 REST 的基本最佳实践，这是每个工程师都应该知道的。

• 保持简单和细粒度：创建模拟系统底层应用程序域或系统数据库架构的 API。最终，您将需要聚合服务——利用多种底层资源来减少闲聊的服务。

• 过滤和排序：对于大型数据集，从带宽的角度来看，限制返回的数据量至关重要。此外，我们可能希望指定要包含在响应中的资源的字段或属性，从而限制返回的数据量。我们最终想要查询特定值并对返回的数据进行排序。

• 版本控制：有很多方法可以破坏合同并对 API 开发中的客户产生负面影响。如果您不确定更改的后果，最好谨慎行事并考虑版本控制。在决定新版本是否合适或对现有表示的修改是否充分和可接受时，需要考虑几个因素。由于维护多个版本变得繁琐、复杂、容易出错且成本高昂，因此对于任何给定资源，您应该支持不超过两个版本。

• 缓存：缓存通过启用系统中的层来消除检索请求数据的远程调用来增强可扩展性。服务通过在响应（如 Cache-Control、Expires、Pragma、Last-Modified 等）上设置标头来提高缓存能力

• 分页：REST 的原则之一是连通性——通过超媒体链接。同时，没有它们，服务仍然有用。当链接在响应中返回时，API 变得更具自我描述性。对于支持分页的响应中返回的集合，“first”、“last”、“next”和“prev”链接至少是有益的。

• 资源命名：当资源命名正确时，API 是直观且易于使用的。做得不好，同样的 API 会让人感觉很笨拙，并且难以使用和理解。RESTful API 适用于消费者。URI 的名称和结构应该向这些消费者传达含义。通常很难知道数据边界应该是什么，但是通过了解您的数据，您很可能有能力进行尝试，并将什么作为代表返回给您的客户是有意义的。为您的客户设计，而不是为您的数据设计。

• - 复数：普遍接受的做法是始终在节点名称中使用复数形式，以保持您的 API URI 在所有 HTTP 方法中保持一致。原因是“客户”是服务套件中的一个集合，而 ID（例如 33245）指的是集合中的这些客户之一。

• 监控：确保添加各种监控以提高 API 的质量或性能。数据点可以是响应时间（P50、p90、P99）、状态代码（5XX、4XX 等）、网络带宽等等。

• 安全：

  • - 授权/认证：对服务的授权与对任何应用程序的授权没有什么不同。问这个问题，“这个主体对给定资源是否有请求的权限？”

  • - CORS：在服务器上实现 CORS 就像在响应中发送额外的 HTTP 标头一样简单，例如 Access-Control-Allow-Origin、Access-Control-Allow-Credentials 等

  • - TLS：所有身份验证都应使用 SSL。OAuth2 需要授权服务器和访问令牌凭据才能使用 TLS。

  • - 幂等性：如果执行一次或多次，将产生相同结果的操作。根据其适用的上下文，它可能具有不同的含义。例如，在具有副作用的方法或子程序调用的情况下，这意味着修改后的状态在第一次调用后保持不变。

  • - 输入验证：验证服务器上的所有输入。接受“已知”好的输入并拒绝错误的输入，防止 SQL 和 NoSQL 注入，将消息大小限制为字段的确切长度，服务应仅显示一般错误消息等等。

  • - 限速：是一种限制网络流量的策略。它限制了某人在特定时间范围内重复操作的频率 - 例如，尝试登录帐户。

  • - 记录：确保您不会意外记录任何个人身份信息 (PII)。

至此，我结束了这次学习，我希望你今天学到了一些新东西。请分享给更多的同事或朋友。

本文	https://jiagoushi.pro/principles-best-practices-rest-api-design
讨论：知识星球【首席架构师圈】或者加微信小号【cea_csa_cto】或者加QQ群【792862318】
公众号	【jiagoushipro】 【超级架构师】 精彩图文详解架构方法论，架构实践，技术原理，技术趋势。 我们在等你，赶快扫描关注吧。
微信小号	【cea_csa_cto】 50000人社区，讨论：企业架构，云计算，大数据，数据科学，物联网，人工智能，安全，全栈开发，DevOps，数字化.
QQ群	【792862318】深度交流企业架构，业务架构，应用架构，数据架构，技术架构，集成架构，安全架构。以及大数据，云计算，物联网，人工智能等各种新兴技术。 加QQ群，有珍贵的报告和干货资料分享。
视频号	【超级架构师】 1分钟快速了解架构相关的基本概念，模型，方法，经验。 每天1分钟，架构心中熟。
知识星球	向大咖提问，近距离接触，或者获得私密资料分享。
喜马拉雅	路上或者车上了解最新黑科技资讯，架构心得。	【智能时刻，架构君和你聊黑科技】
知识星球	认识更多朋友，职场和技术闲聊。	知识星球【职场和技术】
微博	【智能时刻】	智能时刻
哔哩哔哩	【超级架构师】
抖音	【cea_cio】超级架构师
快手	【cea_cio_cto】超级架构师
小红书	【cea_csa_cto】超级架构师

谢谢大家关注，转发，点赞和点在看。