WebApi:路由和Action选择

素颜马尾好姑娘i 2021-06-26 16:06 392阅读 0赞

本文描述了`ASP.NET Web API`怎么将一个`HTTP`请求路由到控制器的指定方法上。

对于更高级别路由概览，请看 [Routing in ASP.NET Web API][]。

本文看起来更像是对路由处理的详细过程。如果你想创建一个Web API项目并发现那些不想被路由的请求，那么希望本文可以帮助到你。

路由有三个主要的阶段：

1.  将URI匹配到一个路由模板。
2.  选择一个控制器
3.  选择一个action（注：由于将action译为什么都觉得不好，干脆就不译，保持应为，其意义可以理解为方法，动作）

你还可以使用自定义实现来替换路由某部分处理过程。本文中，我将描述默认的行为。文末，我将指出哪些地方是可以扩展自定义行为的。

## 1.路由模板 ##

一个路由模板看起来和URI路径很相似，区别是路由模板拥有大括号标记的占位符：

“`api/{controller}/public/{category}/{id}`”

当创建一个路由映射时，可以为部分或者全部占位符提供默认值：

defaults: new { category = "all" }

也可以设置约束，用来限制URI段中占位符的匹配方式：

constraints: new { id = @"\d+" }   // 只能匹配一个或多个数字。

路由框架会尝试匹配模板里面的URI路径。而纯文本字面量则必须全匹配。默认情况下，占位符将会匹配任何字符串，除非指定一个约束（一般是正则表达式）。路由框架并不会匹配URI的其他部分，比如主机名或者查询参数。路由框架将会在路由表中选择第一个匹配到路由。

有两个特殊的占位符："`{controller}`" 和 “`{action}`”。

*  "`{controller}`"提供控制器的名字。
 *  “`{action}`“提供action的名称。在Web API中，默认约定是忽略"action”（注：即可以不指定”\{action\}"，而通过其他约定规则来分配action，将会在下面介绍到）。

### 1.1占位符默认值 ###

如果为占位符设置了默认值，那么路由将会匹配丢失的这些URI片段，选择默认值进行来填充。例如：

routes.MapHttpRoute(
        name: "DefaultApi",
        routeTemplate: "api/{controller}/{category}",
        defaults: new {  category = "all" }
    );

URI"`http://localhost/api/products`“会匹配这个路由配置映射。而”`{category}`“片段被赋值为”`all`"。

### 1.2路由字典 ###

如果路由框架找一个URI的匹配，那么将会创建一个包含每一个占位符的字段。键为占位符的名称，但不包含大括号。值为从`URI`路径中得到，或者使用默认值。路由字典存储在`IHttpRouteData` 对象中。

在路由匹配阶段，"`{controller}`" 和 "`{action}`"占位符，和其他占位符的处理方式一样，将会被简单地存储在字典中。

可以使用`RouteParameter.Optional`来作为默认值。如果一个占位符被赋值为可选的，那么将不会添加到路由字典中。例如：

routes.MapHttpRoute(
        name: "DefaultApi",
        routeTemplate: "api/{controller}/{category}/{id}",
        defaults: new {  category = "all", id = RouteParameter.Optional }
    );

对于URI路径"`api/products`"，路由字典包含：

*  controller: “products”
 *  category: “all”

对于"`api/products/toys/123`"，则路由字典将包含：

*  controller: “products”
 *  category: “toys”
 *  id: “123”

默认值也可以设置为没有包含在路由模板中的值。如果产生匹配，那么此默认值将会存储在字典中。例如：

routes.MapHttpRoute(
        name: "Root",
        routeTemplate: "api/root/{id}",
        defaults: new {  controller = "customers", id = RouteParameter.Optional }
    );

如果URI路径是"`api/root/8`"，那么字典将包含两个值：

*  controller: “customers”
 *  id: “8”

## 2.控制器选择 ##

使用`IHttpControllerSelector.SelectController`方法来处理控制器的选择。`SelectController`方法输入一个`HttpRequestMessage` 的实例，返回一个`HttpControllerDescriptor`。 `DefaultHttpControllerSelector` 类是`IHttpControllerSelector`的默认实现，其使用了一个简单的算法：

用键为"`controller`“来查询在路由字典中查找键为”`controller`“的值。  
将获取到的值的末尾加上”`Controller`"，得到类型名称。  
根据类型名称，从Web API中查找此控制器。  
例如：如果路由字典包含键值对"controller" = “products”，那么控制器的类型为" `ProductsController`"。如果没有匹配的类型，或者有多个匹配，则路由框架会返回一个错误给客户端。

对于步骤3，`DefaultHttpControllerSelector` 使用`IHttpControllerTypeResolver` 接口来获取Web API控制器类型列表。

`IHttpControllerTypeResolver` 的默认实现是——返回所有：

（a）实现了`IHttpController`接口，

（b）不是抽象类，

（c）以"`Controller`"结尾

的公共类。

## 3.`Action`选择 ##

控制器选择了之后，路由框架通过调用`IHttpActionSelector.SelectAction`方法选择`action`。`SelectAction`方法输入一个`HttpControllerContext` 并返回一个`HttpActionDescriptor`。

`IHttpActionSelector`的默认实现是`ApiControllerActionSelector` 类。以下执行 `Action`选择：

*  请求的HTTP方法。
 *  如果标记了"\{action\}"，获得路由模板中的"\{action\}"占位符。
 *  控制器的action参数。

在看`action`选择算法之前，我们需要进一步理解控制器的`action`.

控制器上的哪些方法被当做"`actions`"？当`action`选择时，路由框架只关心控制器中的公有的实例方法。当然，要排除"特殊名称"的方法（如：构造函数，事件，运算符重载，等等），以及从`ApiController`类继承的方法。

**HTTP 方法**。路由框架只选择匹配请求的HTTP方法，判断如下：

*  通过用属性来标记为HTTP方法：`AcceptVerbs, HttpDelete, HttpGet, HttpHead,HttpOptions, HttpPatch, HttpPost`, 或者 `HttpPut`
 *  或者，如果方法的名称以"Get", “Post”, “Put”, “Delete”, “Head”, “Options”, 或者 "Patch"开头的，那么默认约定支持HTTP方法。
 *  如果上面两条都没有满足，那么此方法被认为是支持POST的。

**参数绑定**。参数绑定是Web API为参数创建一个值的过程。以下是参数绑定的默认规则：

*  从URI获取（绑定）简单类型。
 *  从请求主体(request body)获取（绑定）复杂类型。

简单类型包括.NET框架的原生类型，再加上`DateTime，Decimal，Guide，String`和`TimeSpan`。对每一个`action`，最多可以从请求主体中读取一个参数。

可能需要重写默认的绑定规则。请看 WebAPI Parameter binding under the hood。

有了以上的背景知识以后，以下是`Action`选择算法。

1.  对于一个控制器，创建所有匹配HTTP请求方法的`action`列表。
2.  如果路由字典中有"`action`"项，则删除`action`列表中那些名称不为此项的。
3.  尝试从URI中匹配action参数，如下：
    
     *  对于每一个action，从URI获取简单类型参数的列表，排除可选参数。

*  在此参数列表中，在路由字典或者URI请求字符串中，为每一个参数名找到一个匹配。匹配是不分大小写的，且是无序的。
 *  选择参数列表中的每一个参数均匹配的action。
 *  如果有多个匹配的action，则选择参数最多的一个。

1.  忽略\[NonAction\]属性标记的`actions`。

步骤\#3大概是最疑惑的。基本的想法是一个参数可以从URI、请求主体、自定义绑定，获取到值。对于从URI获取到的参数，我们要确保URI实际只包含一个参数对应的值，或者在路径（通过路由字典获得）中，或者在查询字符串中。

例如，考虑如下`action`：

public void Get(int id)

id参数 绑定到`URI`。因此，此`action`只能匹配到包含"`id`“值的URI， 或者在路由字典中有”`id`"，或者查询字符串中有id。

可选参数是可以被忽略，因为他们是可选的。对于一个可选参数，如果从`URI`中获取不到值，也是允许的。

有很多原因表明，复杂类型是一个例外。复杂类型只能通过自定义绑定绑定到URI。但在这种情况下，路由框架预先不知道参数是否将绑定到特定的URI上。为了确认是否可以绑定，将会直接调用自定义绑定。选择算法的目标是在调用任何绑定之前，从静态的描述中选择出一个`action`。因此，复杂类型被排除在匹配算法之外。

在`action`选择之后，所有参数绑定被调用。

总结：

*  `action`必须匹配请求的HTTP方法。
 *  如果有"`action`“模板，action的名称必须匹配路由字典中的”`action`"项。
 *  对于action的每一个参数，如果参数是在URL中，则参数的名称必须在路由字典，或者查询字符串中被找到（排除可选参数和复杂类型的参数）
 *  尝试匹配最大量的参数。而最佳匹配可能是不带参数的方法。

## 4.扩展示例 ##

路由映射：

routes.MapHttpRoute(
        name: "ApiRoot",
        routeTemplate: "api/root/{id}",
        defaults: new {  controller = "products", id = RouteParameter.Optional }
    );
    routes.MapHttpRoute(
        name: "DefaultApi",
        routeTemplate: "api/{controller}/{id}",
        defaults: new {  id = RouteParameter.Optional }
    );

控制器：

public class ProductsController : ApiController
    { 
    
    public IEnumerable<Product> GetAll() {  }
    
    public Product GetById(int id, double version = 1.0) {  }
    
    [HttpGet]
    
    public void FindProductsByName(string name) {  }
    
    public void Post(Product value) {  }
    
    public void Put(int id, Product value) {  }
    
    }

HTTP请求：

GET http://localhost:34701/api/products/1?version=1.5&details=1

### 4.1路由匹配 ###

此URI匹配名为"DefaultApi"的路由映射。路由字典包含两项:

*  controller: “products”
 *  id: “1”

路由字典中不包含查询字符串参数——“version” and “details”，但这两个参数在action选择时仍会被考虑。

### 4.2控制器选择 ###

从路由字典中的"`controller`"项，控制器类型的`ProductsController`。

### 4.3Action选择 ###

HTTP请求是一个GET请求。控制器支持GET的`action`是`GetAll, GetById, andFindProductsByName`. 路由字典中不包含"`action`"的项，所以我们并不需要匹配的`action`名称。

接下来，我们尝试为`action`匹配参数名称，只看GET action的。  
![在这里插入图片描述][20190510165835260.png]  
注意到`GetById` 的`version`参数不考虑的，因为它是可选参数。

`GetAll` 方法平凡匹配。`GetById` 方法也符合，因为路线字典有"身份证"。`FindProductsByName` 方法不匹配。

`GetById` 方法将被匹配，因为它匹配一个参数，与无参数`GetAll`相比。`GetById` 方法用以下参数值被调用：

*  id = 1
 *  version = 1.5

请注意，尽管选择算法中不使用`version`参数，但是`version`的值来自`URI`查询字符串。

5．扩展点  
Web API为路由处理的某些部分提供了扩展点。

<table> 
 <thead> 
  <tr> 
   <th align="left">接口</th> 
   <th align="left">描述</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left">IHttpControllerSelector</td> 
   <td align="left">选择一个控制器。</td> 
  </tr> 
  <tr> 
   <td align="left">IHttpControllerTypeResolver</td> 
   <td align="left">获取控制器类型列表。 DefaultHttpControllerSelector从此列表中选择控制器的类型。</td> 
  </tr> 
  <tr> 
   <td align="left">IAssembliesResolver</td> 
   <td align="left">Gets the list of project assemblies. 获取项目中的程序集列表IHttpControllerTypeResolver接口使用此列表找到控制器类型。</td> 
  </tr> 
  <tr> 
   <td align="left">IHttpControllerActivator</td> 
   <td align="left">创建一个新的控制器实例</td> 
  </tr> 
  <tr> 
   <td align="left">IHttpActionSelector</td> 
   <td align="left">选择一个Action</td> 
  </tr> 
  <tr> 
   <td align="left">IHttpActionInvoker</td> 
   <td align="left">调用一个Action</td> 
  </tr> 
 </tbody> 
</table>

使用`HttpConfiguration` 上的`Services` 集合，来提供这些接口的自定义实现。

var config = GlobalConfiguration.Configuration;
    config.Services.Replace(typeof(IHttpControllerSelector), new MyControllerSelector(config));

[Routing in ASP.NET Web API]: http://www.asp.net/web-api/overview/web-api-routing-and-actions/routing-in-aspnet-web-api
[20190510165835260.png]: /images/20210626/e0daa9ed62974921bd1a76283b137dab.png