引言
RESTful API 是设计 Web 服务的一种架构风格。它遵循 HTTP 协议的规范，用 HTTP 请求来实现对资源的访问，是现代 Web 开发中最常用的 API 设计模式之一。RESTful API 有许多优秀的设计理念，例如基于资源和行为的 URL，状态码和消息语义，以及无状态性和可缓存性等。然而，实际开发过程中的 RESTful API 往往存在许多问题，不够规范、不够灵活、不够健壮。本文将介绍一些常见的 RESTful API 设计问题，分析其原因，并提供一些指导意义和示例代码帮助你的 RESTful API 更加符合设计理念。
问题一：URI 设计不够语义化
RESTful API 的核心是资源的 URL，它应该具有自描述性，包含有关资源的语义。
以下是一些常见的 URI 设计错误：
--- -----------------
--- -----------------
--- -----------------
上面的示例中，create、update、delete 并不是资源的名词，而是 HTTP 动词。正确的 URI 设计应该是：
---- ----------
--- ---------------
------ ---------------
这些 URI 具有更好的语义，也更容易理解和使用。
问题二：错误的 HTTP 方法
使用正确的 HTTP 方法是 RESTful API 的关键之一。但是，许多开发者只是将所有 API 请求都映射到 HTTP 的 GET 方法中。例如：
--- -----------------
--- -----------------
--- -----------------
这种设计不仅不符合 RESTful API 的规范，还会导致安全和数据完整性等问题。正确的 HTTP 方法应该是：
---- ----------
--- ---------------
------ ---------------
这些 HTTP 方法更加符合语义，也更有效、更安全。
问题三：缺乏版本控制
RESTful API 在演化和不断更新的过程中，需要考虑版本管理。一旦 API 发布后，如果需要增加、删除或更改 API 中的某些资源或者属性，会给使用 API 的客户端带来很大的不便。
--- ---------------
假设我们需要增加一个新的属性（如 phone）到用户对象中，返回类型如下：
- ----- ---- ------- ------ -------- ------------------ -------- ----------- -
如果没有版本控制，那么客户端将不能适应这个变化，而且会导致错误。正确的方式是使用版本控制，例如：
--- ------------------
--- ------------------
在每个版本中，我们可以轻松添加或删除属性，而不必担心老客户端无法使用 API。
问题四：缺少 HATEOAS
HATEOAS（Hypermedia as the Engine of Application State）是 RESTful API 的一个重要概念，它推崇通过链接的方式，让客户端发现和使用 API，而不是通过 API 的文档说明。
考虑下面的 API 请求：
--- ---------------
如果需要编辑该用户，我们通常需要在文档中查找一个资源链接，类似于：
-
-------- -
-
------ -------
------- ----------------------
-
-
-客户端通过执行链接来调用编辑操作。缺少 HATEOAS 将会导致 API 使用和维护的不便。
问题五：状态码不足以表达消息语义
HTTP 状态码是 RESTful API 的一个重要组成部分。它们包含了有关请求状态和响应的状态的消息语义。
以下是一些常见的状态码问题：
--- ------------
如果该用户不存在，我们通常使用 404 状态码，但是 404 状态码不足以表达用户不存在这个信息，我们可以使用 422 状态码，如下所示：
--- --------------
-------- --- ------------- ------
-
--------- -
- ------- ----------------- ---------- ----- ---- --- ------ -
-
-这样，客户端就可以针对 code 属性处理错误。
结论
每个 RESTful API 的实际生产环境都有不同的约束和限制。然而，一个好的 RESTful API 应该遵循约定的设计规则，并以可预见和自我描述的方式来表达资源和操作，这有助于 API 的普及和推广，并使 API 更加易于理解和使用。
参考资料
- RESTful API Designing Guidelines by David Zaffiro
- RESTful API Design – Step By Step Guide by Krunal Lathiya
- The RESTful cookbook by Benjamin Fite-Wassilak
来源：JavaScript中文网 ，转载请联系管理员！ 本文地址：https://www.javascriptcn.com/post/66efb5716fbf960197309131