RESTful API 是近年来比较流行的一种 API 设计风格，它能够帮助开发者更有效地管理和组织 API 接口，提高开发效率。但是，即使是熟练的开发者在设计和实现 RESTful API 时，也会经常遇到一些问题。这篇文章将介绍 RESTful API 的一些常见错误，以及可以尝试的解决方案。
错误 1：过分地使用 HTTP 动词
HTTP 协议定义了多种请求方法，比如 GET、POST、PUT、DELETE 等。其中，GET 和 POST 方法是最常用的请求方法，而 PUT 和 DELETE 方法常常被遗漏，甚至被误用。在 RESTful API 中，这些请求方法有着明确的含义和使用场景。GET 方法用来获取资源，POST 方法用来创建资源，PUT 方法用来更新资源，DELETE 方法用来删除资源。如果在使用 RESTful API 时，过分地使用 GET 或 POST 方法，未能正确使用 PUT 或 DELETE 方法，那么就会出现一些问题，比如：
- 不符合 RESTful API 的规范：RESTful API 的核心思想是使用 HTTP 动词来操作资源，如果过分地使用 GET 或 POST 方法，就会违背 RESTful API 的设计原则。
- 可读性差：如果在代码中使用了不正确的 HTTP 动词，就会让其他开发者难以理解代码的含义，增加维护成本。
- 安全风险：如果使用 GET 或 POST 方法来执行和更新资源，可能会导致跨站点脚本攻击和其他安全问题。
解决方案
在开发 RESTful API 时，应该遵循设计的原则，正确地使用 HTTP 动词。下面是一些建议：
- 使用 GET 方法来获取资源，对于读取、搜索等操作。例如：
GET /users - 使用 POST 方法来创建资源，对于新增、传输数据的操作。例如：
POST /users - 使用 PUT 方法来更新资源的完整内容，对于更新整个资源内容的操作。例如：
PUT /users/{id} - 使用 PATCH 方法来更新资源的部分内容，对于更新资源的某一部分内容的操作。例如：
PATCH /users/{id} - 使用 DELETE 方法来删除资源，对于删除资源的操作。例如：
DELETE /users/{id}
错误 2：不合理地处理 HTTP 状态码
RESTful API 返回 HTTP 状态码，用来告诉客户端请求是否成功，以及出错时的原因和类型。常见的状态码包括 200、201、204、400、401、403、404、500 等等。RESTful API 的设计应该准确合理地处理 HTTP 状态码，否则会导致客户端无法正确地处理响应，或者无法理解服务器返回的错误信息。
解决方案
在开发 RESTful API 时，应该使用正确的 HTTP 状态码来表示响应结果，包括：
- 成功响应：成功的响应需要返回 2xx 系列状态码，比如 200、201、204 等等。
- 客户端错误响应：当客户端请求不正确时，需要返回客户端错误的响应，便于客户端根据错误码来处理或显示错误消息。客户端错误响应返回 4xx 系列状态码，比如 400、401、403、404 等等。
- 服务器错误响应：服务器出现错误，需要返回 5xx 系列的状态码，比如 500、502、503 等等。
同时，在返回 HTTP 状态码时，也应该合理地返回错误消息和响应体，让客户端能够快速准确地处理错误信息。
错误 3：不恰当地使用 URL
RESTful API 的 URL 非常重要，正确的 URL 设计可以使 API 更加易用、安全、易维护性。但是，有些开发者在设计 URL 时，未能考虑这些因素，导致一些问题。
解决方案
在开发 RESTful API 时，应该遵循以下 URL 设计原则：
- 使用名词表示资源：URL 应该使用名词，表示 API 中的资源。例如，应该使用
/users表示用户资源，而不是/getusers。 - 使用复数形式：将资源名转为复数形式，例如：
/users。但是，也有人主张使用单数形式，因为这样更符合英文的语法规则。 - 避免动词表示操作：不应该在 URL 中使用动词来表示操作，而应该使用 HTTP 动词。例如，应该使用 HTTP PUT 方法来更新用户，而不是使用
PUT /users/update。 - 使用参数过滤资源：对于某个资源的筛选操作，应该使用参数来过滤资源。例如，
/users?age=20表示筛选年龄为 20 的用户资源。 - 不要使用层级 URL：URL 中不应该过分使用层级来表示资源之间的关系（如
/parent/child/grandchild）。因为这样会使 URL 过长，不容易维护。
下面是一些使用正确 URL 设计的示例：
- GET /users：获取所有用户。
- GET /users/{id}：获取指定 ID 的用户。
- POST /users：创建用户。
- PUT /users/{id}：更新指定 ID 的用户。
- DELETE /users/{id}：删除指定 ID 的用户。
错误 4：缺少版本控制
RESTful API 的设计变化可能会影响 API 的用户，为了在设计的变化中保护客户端，应该进行版本控制。否则，当你进行 API 更新时，可能会产生以下问题：
- 客户端的 API 调用可能会突然停止工作，这会给用户带来破坏性的影响。
- 没有版本控制很难管理你的 API。如果你要针对特定版本解决一个错误，你可能需要查找所有受影响的组，并手动更新所有版本的 API。
- 没有版本控制的 API 很难升级，这会使它们更容易受到攻击。
解决方案
在开发 RESTful API 时，应该使用版本控制。当你进行 API 升级时，你可以向你的用户发布新版本，而不是让客户端强制更新。
这里介绍两种版本控制方式：
- 包含版本号
在 URL 中包含版本号是一种可行的版本控制方式，例如：/v1/users、/v2/users。这样做有一些好处，比如：
- 方便识别和管理版本。
- 版本间不会互相干扰。
- 允许客户端逐渐迁移到新版本。
- 使用 Accept 标头
使用 Accept 标头请求版本是 RESTful API 的另一种版本控制方式。这种方法使你可以在客户端发出请求时指定所需的版本，例如：Accept: application/vnd.example.v1+json。这样做的好处是：
- 对于没有变化的资源可以共享。
- 可以使用缓存机制，提高性能。
- 更易于使用 API 数据格式。
结论
RESTful API 是一种流行的 API 设计风格，能够更有效地管理和组织 API 接口，提高开发效率。本文介绍了一些常见的 RESTful API 错误和可以尝试的解决方案，包括使用正确的 HTTP 动词、合理处理 HTTP 状态码、恰当地使用 URL 和版本控制。在开发 RESTful API 时，开发者应该遵循这些设计原则，避免产生错误，提高代码质量。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/677496a56d66e0f9aaee6b7d