使用ASP.NET Core 3.x 构建 RESTful API - 3.1 API资源命名

最新推荐文章于 2021-06-25 14:58:51 发布

dotNET跨平台

最新推荐文章于 2021-06-25 14:58:51 发布

阅读量539

点赞数

为了与RESTful API进行交互，API消费者需要使用到三个概念：

资源的标识。也就是可以找到资源的URI。
HTTP方法。例如GET，POST等等，这些方法是HTTP协议的一部分。
有效载荷（可选），英文就是Payload。例如，当你想创建资源的时候，HTTP请求里面会包含着你想要创建的资源的一个表述。或者当获取资源的时候，HTTP响应里面会它的Body里面包含着资源的表述。这些表述的格式就是我们使用的media type，例如application/json。

之前讲了RESTful API的统一资源接口这个约束，里面提到了资源是通过URI来进行识别的，每个资源都有自己的URI。URI里还涉及到资源的名称，而针对资源的名称却没有一个标准来进行规范，但是业界还是有一些最佳实践的。那么我们首先看看这些最佳实践对资源命名是如何建议的。

资源命名

使用名词，而不是动词

一个资源的URI代表的是一个实际上或概念上存在的东西，因此，它应该是名词，所以也就不应该出现动词，动词应该使用HTTP方法来表达。

需求：我们看这样一个需求的例子：“我想获得系统里所有的用户”。

常见错误做法：你可能把API的URI设计成这样：api/getusers。这样的设计是不好的，因为里面出现了一个动词get。

分析：这个句话的主要动词就是“获取”，而想要获取的资源（也就是主要的名词）是“用户”。

正确的做法：需求里面主要的动词应该通过HTTP方法来体现，“获取”对应的HTTP方法就是GET。而“用户”这个资源可以用英文user或者users来表示（是否使用复数一直存在争议，两种方法都行，但你在使用的时候需要保持一致）。所以正确的uri应该是 GET api/user。

人类能读懂

还是上面那个需求：“我想获得系统里所有的用户”。

我们可以把uri设计成 api/u 或者 api/ur。但是这样设计的话，对API的消费者来说非常的不友好，因为不能直观的看出来它到底代表的是什么资源，可能是user，也可能是university。

所以建议的做法是要足够友好，并且比较简短，例如：api/users。

要体现资源的结构关系

假设如果后端API系统里面有若干种资源，而用户这个资源与其它的资源并没有直接的关系，这样的话获取用户资源的uri应该是 api/users。而不是 api/products/users，也不是api/catalogs/products/users，因为user和product或者catalog没有直接的关系。

通过id获取单个用户的uri应该是：api/users/{userId}，而不是api/userid/users。

这样写的好处是可以让API具有很好的可预测性和一致性。

需求1：系统里有两类资源，公司（Company）和员工（Employee），它们俩是包含关系，也就是一个公司包含多个员工。现在我想获取某个公司下所有的员工信息。

分析：这里的主要动词还是“获取”，所以我们可以使用HTTP的GET。而这里的资源有两个，分别是公司和员工，而且它们是包含关系：一个公司包含多个员工或者说一个公司是一个员工的集合。所以API的URI在设计的时候需要体现这种包含关系。

常见的错误做法：如果你想获得公司这个资源，我想你现在应该不会出错，uri应该是 api/companies。而想要获取某个公司下的员工，常见的错误做法有：api/employees，api/employees/{companyId}等等。这些设计非常不好是因为它无法体现出Company和Employee之间的结构关系。

建议的做法：需要体现Company和Employee之间的关系，所以uri应该是GET api/companies/{companyId}/employees。这样做直接体现出了Company和Employee之间的结构关系，而且也体现出了一个Company就是一个Employee的集合体。

需求2：我想获取某个公司的某个员工信息。

常见的错误做法：api/employees/{employeeId}，api/companies/{employeeId}等等。这些做法都无法体现出Company和Employee之间的关系。

建议的做法：api/companies/{companyId}/employees/{employeeId}。

自定义查询怎么命名

我们经常会遇到这样的需求，比如获取按照某个资源排序后的资源，或者按照某些条件过滤后的资源。这时候应该怎对资源进行命名呢？

需求：“我想获取所有的用户信息，并要求结果是按年龄从小到大进行排列的”。

常见错误的做法：api/users/orderby/age。之前说了，uri里面使用的都应该是名词，如果按照这个uri的结构来看，那么orderby和age就应该是另外两个资源，并且users包含orderby，orderby包含age，这显然是错误的。

建议的做法：api/users?orderby=name，这样设计更合理一些。这里使用了query string作为查询参数进行排序。

例外

有一些需求总是无法满足的达到RESTful的约束。

需求：“我想获取系统里所有用户的数量”。

妥协的做法：我们确实可以先通过 GET api/users来获取系统里所有的用户信息，然后再算出用户的数量，但是这样做也太浪费资源并且效率也太低了。我们也很难使用某个名词来表示这个需求的资源。例如：api/users/totalamountofuser。这样的uri按理说就代表着我们将会获取到一个集合资源，里面是一堆数字，但针对这个需求，我也没有特别好的办法让uri命名完全符合RESTful的约束，所以针对这个需求，我使用的就是这个uri。

Microsoft Learn的官方教程《使用 ASP.NET Core 创建 Web API》请点击原文链接。