RESTful API 是一种架构风格，它基于 HTTP 协议，通过 URI、HTTP 动词、请求头和响应体等规范来实现 Web 服务的统一设计。URI 起到了重要的作用，它可以描述资源的位置和名称，同时也需要遵循一些设计原则，以保证 API 的可读性、可扩展性和安全性。
URI 的设计原则
1. 使用名词
URI 应该描述资源而非行为，因此应该使用名词作为 URI 的一部分，而非动词。比如：
// Good GET /api/users GET /api/users/123 // Bad GET /api/getAllUsers GET /api/getUserById/123
2. 使用复数形式
URI 应该使用复数形式来描述资源，以表示 URI 所描述的资源实际上可能是一个集合。比如：
// Good GET /api/users GET /api/users/123/posts // Bad GET /api/user GET /api/user/123/post
3. 避免嵌套层次过深
URI 不应该包含过多的层次，否则会让 URI 变得混乱和难以理解。比如：
// Good GET /api/users/123 // Bad GET /api/department/1/team/2/user/123
4. 形式一致
URI 应该形式一致，可以采用不同的 URI 模板来描述不同类型的资源，但同种类型的资源对应的 URI 模板应该一致。比如：
// Good GET /api/users GET /api/users/123 // Bad GET /api/user GET /api/user/123 GET /api/users?id=123
5. 可扩展性
URI 应该具有可扩展性，以满足未来的需求。比如：
// Good GET /api/users?name=john&status=active GET /api/users?fields=id,name,email // Bad GET /api/users/name/john/status/active GET /api/users/123/id,name,email
URI 的设计实践
在实践中，我们需要根据具体的业务需求来设计 URI，以下是一个实例。
假设我们要设计一个 RESTful API，来查询一家医院的所有科室和医生信息。我们可以使用以下 URI：
GET /api/hospital/departments
GET /api/hospital/departments/{id}
GET /api/hospital/departments/{id}/doctors
GET /api/hospital/doctors
GET /api/hospital/doctors/{id}
GET /api/hospital/doctors/{id}/departments其中，/api/hospital/departments 用于查询所有科室信息，/api/hospital/departments/{id} 用于查询某个具体科室的信息，/api/hospital/departments/{id}/doctors 用于查询某个科室下的所有医生信息，/api/hospital/doctors 用于查询所有医生信息，/api/hospital/doctors/{id} 用于查询某个具体医生的信息，/api/hospital/doctors/{id}/departments 用于查询某个医生所在的所有科室信息。
以上 URI 设计符合 RESTful API 的设计原则，既可读性良好，又具有可扩展性和安全性。
总结
在设计 RESTful API 中，URI 的设计至关重要。URI 应该使用名词、复数形式、形式一致、可扩展性，避免嵌套层次过深等原则，以达到可读性、可扩展性和安全性的设计目的。在实践中，我们应该根据具体的业务需求来设计 URI，以满足不同场景的需求。
来源：JavaScript中文网 ，转载请注明来源 本文地址：https://www.javascriptcn.com/post/65498d127d4982a6eb3bf592