RESTful API 是现代 Web 应用程序开发中最常用的 API 设计方式之一。资源标识符（URI）是用于标识和访问 Web 资源的主要方法。在本文中，我们将探讨一些资源标识符的最佳实践，以帮助您更好地设计您的 RESTful API。
什么是资源标识符
资源标识符（URI）是在 Web 上唯一标识一个资源的字符串，它由三个部分组成：协议、主机名和路径。
例如，下面是一个资源标识符示例：
https://example.com/api/users/1234
在这个 URI 中：
https是协议部分。example.com是主机名部分。/api/users/1234是路径部分。
路径设计
路径是资源标识符中最重要的部分之一，它应该被精心设计。以下是一些路径设计的最佳实践。
1. 使用名词而不是动词
资源标识符应该代表一个名词，而不是一个动词。例如，下面是一个错误的资源标识符示例：
https://example.com/api/get/user/1234
这个 URI 中的 get 动词应该被省略。正确的示例：
https://example.com/api/users/1234
2. 使用复数形式
通常，资源应该使用复数形式来表示。例如，下面是一个正确的资源标识符示例：
https://example.com/api/users/1234
3. 避免使用复杂的路径结构
路径结构越简单越好，尽可能避免使用嵌套路径，因为它们可能导致 API 的复杂性。
以下是一个错误的路径示例：
https://example.com/api/companies/1234/users/5678
更好的选择是使用查询参数：
https://example.com/api/users?companyId=1234&userId=5678
4. 使用连字符而不是下划线
路径中应该使用连字符而不是下划线。例如，下面是一个正确的资源标识符示例：
https://example.com/api/user-profiles/1234
查询参数
查询参数是 URI 的一部分，用于对资源进行过滤和排序。
以下是对查询参数的最佳实践：
1. 使用连字符连接单词
与路径相同，查询参数中也应该使用连字符而不是下划线。
例如，下面是一个正确的查询参数示例：
https://example.com/api/users?first-name=John&last-name=Doe
2. 为查询参数提供默认值
在某些情况下，如果用户没有提供查询参数，则可以使用默认值。
例如，下面是一个带有默认值的查询参数示例：
https://example.com/api/users?sort=name&order=asc&limit=20&offset=0
在这个示例中，如果用户未提供 sort、order、limit 或 offset 参数，则使用默认值。
示例代码
以下是一个示例的用户资源标识符及其查询参数：
https://example.com/api/users/1234?fields=name,email&sort=name
在这个示例中：
https://example.com/api/users/1234是用户资源标识符。fields=name,email是查询参数，用于返回用户姓名和电子邮件。sort=name是查询参数，用于按姓名对用户进行排序。
下面是使用 Express 框架编写的示例代码：
-- -------------------- ---- -------
----- ------- - -------------------
----- --- - ----------
------------------------- ----- ---- -- -
----- ------ - --------------
----- ------ - -----------------
----- ---- - ---------------
-- ------
----------
--- -------
----- ----- -----
------ -----------------------
-- ----
---
---
---------------- -- -- -
------------------- ------- -- ---- -------
---在这个示例中，我们使用 Express 作为 Web 框架，定义了一个名为 api/users/:id 的路由，其中 :id 是 URL 参数。我们使用 req.params 对象访问 URL 参数，使用 req.query 对象访问查询参数。
结论
在本文中，我们介绍了一些有关 RESTful API 中资源标识符的最佳实践。这些实践应该使您更好地设计您的 API，并提供更好的可读性和可维护性。使用这些最佳实践可以使您为用户提供更好的 API，从而提高您的 Web 应用程序的质量。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/670863bdd91dce0dc8709bc4