干货：RESTful API 的设计理念、设计原则、请求格式。

本文链接：https://blog.youkuaiyun.com/2401_87844866/article/details/146469780

一、RESTful API 概述

RESTful API 是一种在互联网应用程序中广泛采用的 API 设计理念。它以 URL 定位资源，用 HTTP 动词描述操作，为构建可扩展和可维护的 web 应用程序提供了一种有效的方法。

在 RESTful API 中，URL 地址中只包含名词，表示资源。例如，/news 可以表示新闻资源，/users 可以表示用户资源。同时，使用 HTTP 动词表示对资源的操作。常用的 HTTP 动词有 GET、POST、PUT、PATCH 和 DELETE。GET 用于从服务器取出资源，POST 用于在服务器新建一个资源，PUT 用于在服务器更新资源，PATCH 用于在服务器部分更新资源，DELETE 用于从服务器删除资源。

这种设计理念具有很多优点。首先，它使得 API 的设计更加清晰和易于理解。通过 URL 和 HTTP 动词的组合，可以明确地表示对特定资源的操作意图。其次，RESTful API 具有良好的可扩展性。随着应用程序的发展，可以轻松地添加新的资源和操作，而不会影响现有的 API 结构。此外，RESTful API 还具有无状态性，服务器不会保存关于客户端的状态信息，每个请求都是独立的。这使得服务器可以更加容易地进行扩展和负载均衡。

总的来说，RESTful API 是一种强大的 API 设计理念，它为互联网应用程序的开发提供了一种高效、可扩展和易于维护的方法。

二、设计原则

（一）基于资源

在 RESTful API 的设计中，将网络上的每个实体或概念视为唯一资源是一个关键原则。通过 URL 来表示这些资源，使得资源的定位更加清晰和直观。例如，一个博客文章可以被表示为 /articles/123，其中 “articles” 表示文章资源的集合，“123” 是具体某一篇文章的唯一标识符。这种方式使得开发者和用户都能够轻松地理解和访问特定的资源。以电商平台为例，商品可以表示为 /products，每个具体的商品可以通过 /products/{productId} 来访问，其中 {productId} 是商品的唯一标识。这样，无论是获取商品列表还是获取单个商品的信息，都可以通过明确的 URL 来实现。

（二）统一接口

统一接口是 RESTful API 的重要设计原则之一。这意味着使用统一的方式来进行资源的访问和操作。首先，HTTP 方法被用来对资源进行操作。GET 方法用于获取资源的信息，例如发送 GET 请求到 /articles/123 可以获取编号为 123 的文章内容。POST 方法用于创建新资源，比如向 /articles 发送 POST 请求可以创建一篇新的文章。PUT 方法用于更新资源，如向 /articles/123 发送 PUT 请求可以更新编号为 123 的文章。DELETE 方法用于删除资源，向 /articles/123 发送 DELETE 请求可以删除该文章。其次，HTTP 状态码和响应消息被用来传递操作结果。例如，状态码 200 表示操作成功，404 表示资源未找到，500 表示服务器内部错误等。通过统一的接口，开发者可以更加容易地理解和使用 API，同时也提高了 API 的可维护性和可扩展性。

（三）无状态

无状态是 RESTful API 的核心原则之一。每个请求都应该包含足够的信息，使服务器能够理解和处理该请求，而不依赖于之前的请求。服务器不会在会话之间保留任何客户端的状态信息。这使得服务器可以更加容易地进行扩展和负载均衡，因为每个请求都是独立的，不需要考虑之前的请求状态。例如，当客户端发送多个请求时，服务器不需要记住之前的请求内容，只需要根据当前请求的信息进行处理。这种无状态的设计也提高了系统的可靠性和安全性，因为服务器不会因为保存状态信息而面临状态泄露或状态不一致的风险。

（四）按需响应可缓存

在 RESTful API 中，服务器可以标记某些响应为可缓存的，以便客户端可以在后续请求中重复使用相同的响应结果，从而提高性能和减少网络负载。例如，对于一些不经常变化的资源，如静态图片、文档等，服务器可以设置响应头中的缓存控制信息，告诉客户端可以将这些资源缓存一段时间。当客户端再次请求相同的资源时，如果资源没有过期，客户端可以直接使用缓存中的结果，而不需要再次向服务器发送请求。这样可以大大减少网络流量和服务器的负载，提高系统的性能。同时，服务器也可以根据需要随时更新资源，当资源发生变化时，服务器可以通过设置响应头中的缓存控制信息，告诉客户端缓存已经过期，需要重新获取资源。

三、请求格式

（一）URL 设计

在 RESTful API 的请求格式中，URL 的设计至关重要。URL 地址中应只包含名词来表示资源，这样可以使资源的定位更加清晰和直观。例如，/products 表示产品资源集合，/customers 表示客户资源集合。避免设计层级过深的 URL，因为这会使 URL 变得复杂且难以理解。如果需要对资源进行更具体的筛选或查询，可以使用查询参数的形式。比如，要获取特定状态的订单，可以设计 URL 为 /orders?status=pending。这样的设计方式更加灵活，也便于客户端根据不同的需求进行资源的获取。

（二）HTTP 动词

在 RESTful API 中，常用的 HTTP 动词有 GET、POST、PUT、PATCH 和 DELETE。

GET：用于从服务器取出资源。例如，发送 GET 请求到 /articles 可以获取文章列表，发送 GET 请求到 /articles/123 可以获取编号为 123 的文章内容。
POST：用于在服务器新建一个资源。比如向 /articles 发送 POST 请求可以创建一篇新的文章，请求体中包含新文章的信息。
PUT：用于在服务器更新资源。向 /articles/123 发送 PUT 请求可以更新编号为 123 的文章，请求体中包含更新后的完整文章信息。
PATCH：用于在服务器部分更新资源。与 PUT 不同，PATCH 只更新资源的部分属性。例如，只更新文章的标题，可以使用 PATCH 请求到 /articles/123，请求体中只包含标题的更新信息。
DELETE：用于从服务器删除资源。向 /articles/123 发送 DELETE 请求可以删除编号为 123 的文章。

（三）幂等性

在 RESTful API 中，不同的 HTTP 方法具有不同的幂等性。幂等性是指无论调用多少次都不会有不同结果的特性。

POST 方法是非幂等的。因为每次调用 POST 请求都会在服务器上创建一个新的资源。例如，多次向 /articles 发送 POST 请求会创建多篇不同的文章。
GET 方法是幂等的。无论发送多少次 GET 请求到同一个 URL，结果都不会改变资源本身。比如，多次发送 GET 请求到 /articles/123，只是查询文章内容，不会对文章资源产生影响。
DELETE 方法是幂等的。调用一次和多次对资源产生的影响是相同的，即删除资源。例如，多次发送 DELETE 请求到 /articles/123，最终结果都是文章被删除。
PUT 方法是幂等的。它直接把实体部分的数据替换到服务器的资源，多次调用只会产生一次影响。例如，多次发送 PUT 请求到 /articles/123，用相同的文章内容进行更新，结果都是一样的。
PATCH 方法一般是非幂等的。因为 PATCH 请求是会执行某个程序的，如果重复提交，程序可能执行多次，对服务器上的资源就可能造成额外的影响。例如，服务端对 PATCH 请求的处理是每次更新部分字段并将记录的操作记录加一，那么每次调用的资源就会发生变化。

四、状态码与错误处理

（一）常用状态码含义

在 RESTful API 中，状态码用于表示服务器对客户端请求的响应状态。以下是一些常见的状态码及其含义：

2XX：请求成功：

- 200：“成功”，服务器已成功处理了请求，通常表示服务器提供了请求的网页。例如，发送 GET 请求到 /articles/123，服务器成功返回编号为 123 的文章内容，状态码为 200。
- 201：“已创建”，请求成功并且服务器创建了新的资源。比如向 /articles 发送 POST 请求创建一篇新文章成功后，状态码为 201。
- 202：“已接受”，服务器已接受请求，但尚未处理。可以用于异步操作的场景，服务器告知客户端请求已被接受，但处理可能需要一段时间。
- 204：“无内容”，服务器成功处理了请求，但没有返回任何内容。例如，DELETE 请求成功删除资源后，可能返回状态码 204。
- 206：“部分内容”，服务器成功处理了部分 GET 请求，通常用于处理范围请求。

3XX：请求被重定向：

- 300：“多种选择”，针对请求，服务器可执行多种操作，服务器可根据请求者选择一项操作，或提供操作列表供请求者选择。
- 301：“永久移动”，请求的网页已永久移动到新位置，服务器返回此响应时，会自动将请求者转到新位置。
- 302：“临时移动”，服务器目前从不同位置的网页响应请求，但请求者应继续使用原有位置来进行以后的请求。
- 303：“查看其他位置”，请求者应当对不同的位置使用单独的 GET 请求来检索响应时，服务器返回此代码。
- 304：“未修改”，自从上次请求后，请求的网页未修改过，服务器返回此响应时，不会返回网页内容。
- 307：“临时重定向”，服务器目前从不同位置的网页响应请求，但请求者应继续使用原有位置来进行以后的请求。

4XX：请求错误：

- 400：“错误请求”，服务器不理解请求的语法。例如，请求体中的数据格式错误或缺少必要的参数。
- 401：“未授权”，请求要求身份验证。对于需要登录的网页，服务器可能返回此响应。
- 403：“禁止”，服务器拒绝请求。可能是因为用户没有足够的权限访问资源。
- 404：“未找到”，服务器找不到请求的网页。当请求的资源不存在时，返回此状态码。
- 405：“方法禁用”，禁用请求中指定的方法。例如，使用不被允许的 HTTP 方法访问资源。
- 406：“不接受”，无法使用请求的内容特性响应请求的网页。
- 407：“需要代理授权”，此状态代码与 401 “未授权” 类似，但指定请求者应当授权使用代理。
- 408：“请求超时”，服务器等候请求时发生超时。
- 409：“冲突”，服务器在完成请求时发生冲突。服务器必须在响应中包含有关冲突的信息。
- 410：“已删除”，如果请求的资源已永久删除，服务器就会返回此响应。
- 411：“需要有效长度”，服务器不接受不含有效内容长度标头字段的请求。
- 412：“未满足前提条件”，服务器未满足请求者在请求中设置的其中一个前提条件。
- 413：“请求实体过大”，服务器无法处理请求，因为请求实体过大，超出服务器的处理能力。
- 414：“请求的 URI 过长”，请求的 URI（通常为网址）过长，服务器无法处理。
- 415：“不支持的媒体类型”，请求的格式不受请求页面的支持。
- 416：“请求范围不符合要求”，如果页面无法提供请求的范围，则服务器会返回此状态代码。
- 417：“未满足期望值”，服务器未满足 “期望” 请求标头字段的要求。

5XX：服务器错误：

- 500：“服务器内部错误”，服务器遇到错误，无法完成请求。
- 501：“尚未实施”，服务器不具备完成请求的功能。例如，服务器无法识别请求方法时可能会返回此代码。
- 502：“错误网关”，服务器作为网关或代理，从上游服务器收到无效响应。
- 503：“服务不可用”，服务器目前无法使用（由于超载或停机维护）。通常，这只是暂时状态。
- 504：“网关超时”，服务器作为网关或代理，但是没有及时从上游服务器收到请求。
- 505：“HTTP 版本不受支持”，服务器不支持请求中所用的 HTTP 协议版本。

（二）错误处理方式

在 RESTful API 中，错误处理是非常重要的一部分。当出现错误时，服务器应该向用户返回明确的错误信息，以便用户和开发者能够快速定位问题并采取相应的措施。

利用 Http 状态码表明错误类型：Http 状态码定义了很多抽象的错误类型，在 RESTful API 中利用 Http 状态码来表明错误类型再合适不过了。例如，当请求参数不合法或格式错误时，可以返回 400 Bad Request 状态码；当用户没有权限操作资源时，可以返回 403 Forbidden 状态码。
返回业务错误码：很多时候，我们根据业务类型来自定义错误码。这些业务错误码与 Http 状态码并不重叠，可以用来提示用户 / 开发者错误类型。例如，可以设计一个业务错误码为 “FORMAT_INVALID”，当请求格式无效时返回这个错误码，同时可以在错误信息中详细说明格式错误的具体原因。
提供给用户看的错误信息：当出现错误时，需要提示用户如何处理这种情况，通常这种错误信息都是必须的。例如，可以在错误信息中告诉用户 “请求格式错误，请检查您的输入并重新提交”。
提供给开发者看的错误信息：如果 API 需要开放给第三方开发者，那么就需要考虑返回一些给开发者看的错误信息。例如，可以在错误信息中提供错误发生的具体位置、错误类型、错误代码等信息，以便开发者快速定位问题并进行修复。

五、与其他架构区别

RESTful API 与 SOAP WebService 的区别

效率方面：RESTful API 通常基于 HTTP 协议，使用 JSON 等轻量级数据格式，报文传输量相对较小，具有较高的传输效率。相比之下，SOAP WebService 基于 XML 协议，本身使用 XML 传输会传输一些无关的东西从而效率不高，随着 SOAP 协议的完善，增加了许多内容，导致使用 SOAP 协议去完成简单的数据传输的效率不高。
易用性方面：RESTful API 简单易用，基于 HTTP 协议，可以使用常见的 HTTP 方法（如 GET、POST、PUT、DELETE 等）进行操作，使得开发人员可以快速上手和使用。同时，RESTful API 的 URL 设计直观，易于理解和记忆。而 SOAP WebService 需要使用特定的 SOAP 协议，开发相对复杂，对开发人员的技术要求较高。
安全性方面：RESTful API 默认基于 HTTP 协议进行通信，可以使用 SSL/TLS 等安全协议进行加密传输，提高了安全性。而 SOAP WebService 也有一系列的标准，如 WSRM（WS-Reliable Messaging）形式化契约确保可靠性与安全性，确保异步处理与调用；WS-Security、WS-Transactions 和 WS-Coordination 等标准提供了上下文信息与对话状态管理。总的来说，两者在安全性方面都有一定的保障，但具体的安全性取决于实际的应用场景和配置。

RESTful API 与 RPC 的区别

效率方面：RPC 使用自定义的通信协议，可以减少报文传输量，提高传输效率。而 RESTful API 的报文传输量较大，因为需要携带更多的 HTTP 头部信息。此外，RPC 在性能方面相对较高，由于其直接调用远程方法，不需要经过 HTTP 协议的三次握手等过程。
易用性方面：RESTful API 简单易用，基于 HTTP 协议，开发人员可以快速上手和使用。而 RPC 需要实现编码、序列化、网络传输等功能，相比之下实现更复杂。同时，RESTful API 可以在不同的平台和设备上使用，因为它是基于标准的 HTTP 协议进行通信，具有较强的跨平台能力。而 RPC 则需要根据不同的语言和平台进行定制化开发，跨平台能力有限。
安全性方面：RESTful API 默认基于 HTTP 协议进行通信，可以使用 SSL/TLS 等安全协议进行加密传输，提高了安全性。而 RPC 则需要自定义通信协议，在安全性方面可能存在一定的风险。

RESTful API 与 WebSocket 的区别

效率方面：WebSocket 是一种持久化的、全双工通信协议，允许在客户端和服务器之间进行实时的双向通信，无需每次请求都创建新的连接，在实时通信场景下效率较高。而 RESTful API 是基于请求 / 响应模型的，每次请求都是无状态的，服务器不会主动向客户端推送数据，在实时通信方面效率相对较低。
易用性方面：RESTful API 简单易用，基于 HTTP 协议，开发人员可以快速上手和使用。而 WebSocket 的使用相对复杂，需要在客户端和服务器端进行特定的配置和处理，以建立和维护 WebSocket 连接。
安全性方面：RESTful API 默认基于 HTTP 协议进行通信，可以使用 SSL/TLS 等安全协议进行加密传输，提高了安全性。WebSocket 也可以使用 SSL/TLS 进行加密，但在一些情况下，可能需要额外的安全措施来确保通信的安全性。

综上所述，RESTful API 与 SOAP WebService、RPC、WebSocket 等架构在效率、易用性、安全性等方面各有优劣，在实际应用中，应根据具体的需求和场景选择合适的架构。