在设计 RESTful API 时，URI 的设计非常重要。URI 是唯一可以被远程客户端执行的 API 标识符。正确的 URI 设计使得 API 的使用更加易于理解，并且可以大大提高 API 的可读性和可维护性。在本文中，我们将深入探讨 RESTful API 中 URI 的最佳实践和设计规范。
URI 的组成
URI 由多个部分组成：协议、主机、端口、路径和查询参数。在 RESTful API 的设计中，URI 的主要作用是标识资源，因此我们需要遵循一些最佳实践和设计规范来确保 URI 的清晰和简洁。
1. 协议
协议是 URI 的第一部分，通常是 HTTP 或 HTTPS。在 RESTful API 中，协议通常是 HTTP 或 HTTPS。如果您的 API 需要保证数据传输的安全性和完整性，HTTPS 是强烈建议的。
2. 主机
主机表示 API 所在的服务器地址。在 RESTful API 中，主机通常是您部署 API 的服务器地址或域名。例如：api.example.com 或 192.168.0.1。
3. 端口
端口可选，可以将不同的 API 服务放在不同的端口上。默认端口号为 80（HTTP）或 443（HTTPS）。端口号通常可以省略，只需要在 URI 中包含主机即可。
4. 路径
URI 的主要部分是路径，它表示资源的层次结构。路径的设计应该尽可能简单和自描述。下面的示例代码演示了路径的最佳实践：
-- -------------------- ---- ------- - ------------- ---------- - --------------- ------------------- - ------------ ---------- - ------------- ------------------- - -------------- -------------------
- URI 的路径使用名词表示，最好不要使用动词。
- 使用斜杠
/分隔多个层次的资源。 - 使用大括号
{}表示动态参数，可以通过 URI 参数的方式传递。例如：/api/users/{userID}。
5. 查询参数
查询参数可选，用于过滤资源或指定其他属性。在 RESTful API 中，我们应该尽量避免使用查询参数，而是使用路径参数来表示资源的属性和过滤条件。如果必须使用查询参数，应该采用下面的最佳实践：
# 获取用户列表，支持分页、排序和过滤 /api/users?page=1&limit=10&sort=name&gender=male
- 查询参数使用
?表示，多个参数使用&分隔。 - 查询参数应该尽可能简短，使用下划线
_分隔单词。 - 尽量不要使用数字参数，而是尽可能使用可读性更高的字符参数。
URI 的最佳实践
在设计 RESTful API 的 URI 时，我们应遵循一些最佳实践和设计规范，以提高 API 的可读性和可维护性。
1. 使用名词表示资源
URI 的路径应该使用名词表示资源，而不是动词。例如：/api/users 表示用户资源，而不是执行某些操作的 API。
2. 使用复数形式
在 URI 中使用复数形式，例如：/api/users 而不是 /api/user。这样可以更好地表示资源集合。
3. 使用斜杠分隔多级 URI
URI 的多级路径应该使用斜杠 / 分隔，例如：/api/users/12345 表示用户资源和用户 ID 为 12345。
4. 使用参数表示资源属性和过滤条件
在 URI 中使用参数表示资源属性或过滤条件。例如：/api/users/{userID} 表示特定的用户资源，/api/users?page=1&limit=10&gender=male 表示获取用户列表，支持分页、过滤和排序。
5. 避免使用大写字母和空格
在 URI 中应避免使用大写字母和空格。URI 应该是大小写敏感的，因此使用大写字母会增加混淆的可能性。空格应该用 URL 编码方式 %20 来表示。
URI 的设计规范
在设计 URI 时，应该尽可能遵循一些规范和标准，以确保 URI 的清晰和简洁。
1. 规范化 URI
所有 URI 应该按照统一的规范进行规范化。例如：/api/users/12345 应该和 /api/users/12345/?format=json 规范化成 /api/users/12345?format=json。
2. 使用虚拟目录来组织 API
可以使用虚拟目录来组织 API，例如：/api/v1 表示 API 的第一个版本，/api/v2 表示 API 的第二个版本。
3. 避免使用动词
URI 应该尽可能使用名词表示资源，而不是动词。例如：/api/users 而不是 /api/get-users。
4. 使用实数 ID
URI 中的资源 ID 应该使用实数表示，而不是使用 UUID 或 GUID。例如：/api/users/12345 而不是 /api/users/aae33c03-8d7b-45ed-bc06-2b8d8b016e9d。
5. 使用 HTTP 动词来表示操作
HTTP 动词应该用于表示对资源的操作。例如：GET 表示获取资源，POST 表示创建资源，PUT 表示更新资源，DELETE 表示删除资源。
总结
在设计 RESTful API 时，URI 是一个非常重要的组成部分。URI 的设计应该遵循一些最佳实践和设计规范，以提高 API 的可读性和可维护性。在本文中，我们介绍了最佳实践和设计规范，并提供了一些示例代码，希望可以对您在设计 RESTful API 时提供帮助。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/64e885bdf6b2d6eab3411a66