Restful API设计规范及实战

Posted 2020-11-19 周伯通的麦田

Restful API的概念在此就不费口舌了，博友们网上查哈定义文章很多，直入正题吧：

首先抛出一个问题：
判断id为 用户下，名称为 使命召唤14(COD14) 的产品是否存在(话说我还是很喜欢玩类似二战的使命召唤这款额，题外话...)？如果这个问题出现在 MVC 项目中，我想我们一般会这样设计：

api/products/isexist/{userId}/{productName}

我想你应该发现一些问题了，这种写法完全是 MVC 的方式，但并不适用于 WebAPI，主要有三个问题：
Route 定义混乱，完全违背 REST API URI 的一些设计原则。Action 命名不恰当。bool 返回值不合适。对于上面的三个问题，我们分别来探讨下。

1. URI 设计首先，我们知道在 REST API 中，URI 代表的是一种资源，它的设计要满足两个基本要求，第一名词而非动词，第二要能清晰表达出资源的含义，

换句话说就是，从一个 URI 中，你可以很直接明了的知道访问的资源是什么，我们再来看我们设计的 URI：

api/products/isExist/{userId}/{productName}

这是神马玩意啊？？？这种设计完全违背 URI 原则，首先，我们先梳理一下，我们想要请求的资源是什么？没错，是产品（Products），但这个产品是某一个用户下的，

所以用户和产品有一个上下级关系，访问产品首先得访问用户，这一点要在 URI 中进行体现，其次，我们是获取产品？还是判断产品是否存在？这个概念是不同的，

产品的唯一标识和用户一样，都是 id，在 URI 的一般设计中，如果要访问某一唯一标识下的资源（比如 id 为 1 的 product），会这样进行设计：

api/products/{id}

HttpClient 请求中会用 HttpGet 方法（api/products/1），这样我们就可以获得一个 id 为 1 的 product，但现在的场景是，获取产品不通过唯一标识，而是通过产品名称，难道我们要这样设计：

api/products/{productName}

咋看之下，这样好像设计也没毛病啊，但总觉得有些不对劲，比如如果再加一个产品大小，难道要改成这样：api/products/{productName}/{productSize}，这种设计完全是不恰当的，上面说到，

URI 代表的是一种资源，通过 URI 获取资源的唯一方式是通过资源的唯一标识，除此之外的获取都可以看作是对资源的查询（Query），所以，针对我们的应用场景，URI 的设计应该是这样（正确）：

格式标准: api/users/{userId}/products:
示 例  : api/users/1/products?productName=使命召唤COD14

上面的 URI 清晰明了的含义：查询 id 为 1 用户下名称为 COD14 的产品。