使用ASP.NET Core 3.x 构建 RESTful API - 3.2 路由和HTTP方法

ASP.NET Core 3.x 的路由

路由机制会把一个请求的URI映射到一个Controller上面的Action，所以当你发送一个HTTP请求的时候，MVC框架会解析这个请求的URI，并尝试着把它映射到一个Controller上面的Action。

两个路由中间件

在ASP.NET Core 3.x里面，建议使用Endpoint路由来进行设置。但是我们需要先在请求的管道里面添加两个中间件：

• app.UseRouting()。它是用来标记路由决策在请求管道里发生的位置，也就是在这里会选择端点。

• app.UseEndpoints()。它是用来标记选择好的端点在请求管道的什么地方来执行。

这样做的好处就是，我们可以在选择端点和执行端点的中间位置插入其它的中间件。这样的话，插入到中间位置的中间件就会知道哪个端点被选取了，而且它也有可能会选择其它的端点。

一个非常好的例子就是授权中间件：

如果授权成功，那么就继续执行到之前选定的端点，否则的话就会跳转到其它端点或者短路返回。

官方文档：Startup里面路由配置的官方文档。

映射端点

还是可以有两种方式进行设置：基于约定 或者 基于属性。

基于约定的路由，例如这两种：

这种方式更适合于服务器端的Web应用程序。

而针对Web API，使用基于属性的路由更加适合：

可以看到，这里面仅仅映射了Controller，并没有使用任何约定，所以我们需要采用属性（Attribute）来进行设定。这里需要用到属性（attribute）和URI模板。

• 属性（Attribute）。例如[Route]，[HttpGet]，[HttpPost]等等，可以把它们放在Controller级别，也可以放在Action级别上。

• URI模板。将属性结合URI模板一起使用，就可以把请求映射到Controller的Action上面。

例如：

官方文档：路由基础知识。

HTTP 方法

不同的动作可以作用于相同的资源URI，例如获取一个公司（api/company/3）和删除一个公司（api/company/3）的URI就是一样的。但是它们的HTTP方法则不同，一个是GET，一个是DELETE。下面我们就来看看那些动作应该对应哪些 HTTP 方法。

POST

需求：添加一个公司信息。

需求图解：

HTTP请求图解：

文字解释：

添加公司这个需求的HTTP表示就是 POST api/companies。

当我们向 api/companies这个标示添加一个公司信息的时候，就会利用提供的公司信息创建一个公司的资源。这里对应的HTTP方法是POST。

POST请求的参数通常存放在请求的body里面，所以公司的信息就放在了body里面。

当公司资源创建好之后，这个action应该返回新创建的资源以及可以获取该资源的路径标识，也就是api/companies/{新资源的id}。

GET

获取单个资源

需求：获取一个公司信息

需求图解：

HTTP请求图解：

文字解释：

我们想要通过 api/companies/{companyId} 这个标示来获取一个公司资源，这里就需要使用HTTP GET 方法，放在一起就是 GET api/companies/{companyId}。

GET请求总是会返回请求 URI 所对应的资源，所以这个请求会返回这个资源的内容。

获取集合资源

需求：获取符合查询条件的公司资源

需求图解：

HTTP请求图解：

这个需求是按条件搜索资源，可能返回0个或者多个符合条件的资源。这里我们使用HTTP的GET方法，如果想获取所有的公司资源，那么请求路径是 api/companies；如果想获取符合查询条件的公司资源，那么请求里就需要一些参数，通常使用查询字符串（query string）来传递参数，例如：

GET api/someresources?param1=value1&param2=value2

GET api/products?xxxxx=something

在这里，参数是在问号？后边，以name=value的形式存在。如果有多个查询参数，它们之间使用 & 符号分隔开。

当搜索资源的工作结束后，GET请求会返回匹配该路径（包括参数部分）的资源。

DELETE

需求：删除一个公司

需求图解：

HTTP请求图解：

文字解释：

HTTP 的 DELETE 方法就很好理解了，就是删除指定路径的资源而已，而且不需要返回任何东西。

PATCH

需求：更新公司的信息。

需求图解：

HTTP请求图解：

文字解释：

这里有些初学者可能会出错。HTTP 用来表示更新信息的方法是 PATCH，所以整个请求时 PATCH api/companies/{companyId}。注意PATCH表示对资源进行局部更新。

和POST一样，PATCH的参数也位于请求的body里面。例如，如果你想更新公司的名称，那么就要把新的公司名称放在body里面。

PATCH的请求无需返回任何东西。

PUT

需求：替换公司信息。

需求图解：

HTTP请求图解：

文字解释：

HTTP 的 PUT 方法用于完全替换已存在的一个资源；或者如果标识URI对应的资源不存在，那么就创建一个资源。对于后一种情况，它的效果和添加操作是一样的。

和 POST 一样，PUT的参数也位于请求的body里面。

如果是替换现有资源，那么无需返回任何东西；但如果是创建资源的操作，就应该返回新创建的资源。

综上

通过HTTP方法可进行的CRUD基本操作已经介绍的差不多了，但是这里的CRUD只是从API消费者的角度而言。例如，DELETE api/companies/12 并不意味着id为12的公司信息从数据库中被删除了，也许只是把该公司的信息的状态设置为deleted而已。

对于不限于CRUD的其它操作，我们也得使用这些HTTP方法来进行表示，多少要进行一些妥协。

最后使用一张图表总结一下这些HTTP方法对应的操作：

实际上还有 HTTP 的 OPTIONS 和 HEAD 也会直接或者间接的用到，这俩以后再说吧。