Web API路由和动作选择

前言

　　本文描述ASP.NET Web API如何把一个HTTP请求路由到控制器的一个特定的Action上。关于路由的总体概述可以参见上一篇教程 http://www.cnblogs.com/aehyok/p/3442051.html。这篇文章主要来学习路由过程的细节。如果你创建了一个Web API项目，发现有一些请求没有按照你期望的方式被路由，希望这篇文章将对你有所帮助。

本文主要分为三个阶段：

　　1.匹配URI到一个Route Template。

　　2.选择一个Controller。

　　3.选择一个Action。

　　你可以用自己的自定义行为来替换这一过程中的某些部分。在本文中，我将来描述默认的行为。在文章结尾，我会注明可以在什么地方自定义行为。

　　

Route Templates

路由模版看上去类似于一个URI路径，但它可以具有占位符，并用花括号来指示：

"api/{controller}/public/{category}/{id}"

当创建一个路由的时候，你可以为某些或所有占位符提供默认值：

defaults: new { category = "all" }

你也可以提供约束，它限制URI片段如何与占位符匹配：

constraints: new { id = @"\d+" }   // Only matches if "id" is one or more digits.

上面语句是通过正则表达式来限制片段的取值，上面的注释说明 id片段只匹配一个或多个数字，因此URI中的id片段必须是数字才能与这个路由进行匹配。

这个框架试图把URI路径中的片段与这个模板进行匹配。模板中的文字必须严格匹配。一个占位符可以匹配任何值，除非你指定了约束。这个框架不会匹配URI另外的部分，例如主机名或者一个查询字符串。这个框架会选择路由表中第一个匹配的路由。

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

• “{controller}”提供控制器名。
• “{action}”提供动作名。在Web API中，通常的约定是忽略“{action}”的。

Defaults(默认值)

如果你提供默认值，那么这个路由将匹配缺少这些片段的URI。例如：

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

这个URI“http://localhost/api/products”与这个路由是匹配的。“{category}”片段被赋成了默认值“all”。

Route Dictionary（路由字典）

　　如果这个框架发现了一个匹配的URI，它会创建包含每个占位符值的一个字典。这个键值是不带花括号的的占位符名称。这个值取自于URI路径或者是默认值中的。这个字段被存在IHttpRouteData对象中。在匹配路由阶段，这个特殊的"{controller}" and "{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"。

Selecting a Controller

控制器选择是由IHttpControllerSelector.SelectController方法来处理的。这个方法以HttpRequestMessage实例为参数，并返回HttpControllerDescriptor。

其默认实现是由DefaultHttpControllerSelector类提供的。这个类使用了一种很直接的算法：

　　1.查找路由字典的“controller”键。

　　2.取得这个键的值，并附加字符串“Controller”，以得到控制器的类型名。

　　3.用这个类型名查找Web API控制器。

　　例如，如果路由字典中的键-值对为“controller”=“products”，那么控制器类型便为“ProductsController”。如果没有匹配类型，或有多个匹配，这个框架会给客户端返回一条错误。

对于步骤3，DefaultHttpControllerSelector使用IHttpControllerTypeResolver接口以获得Web API控制器类型的列表。 IHttpControllerTypeResolver的默认实现会返回所有符合以下条件的public类：

a:实现IHttpController的类。

b:是非抽象类。

c:名称以“Controller”结尾的类。

Action Selection

　　选择了控制器之后，这个框架会通过调用IHttpActionSelector.SelectAction方法来选择动作。这个方法以HttpControllerContext为参数，并返回HttpActionDescriptor。

这个默认实现是由ApiControllerActionSelector类提供的。为了选择一个动作，会查找以下方面：

　　1.HTTP请求的方法。

　　2.这个路由模板中的“action”占位符。

　　3.控制器中动作的参数。

在查找选择算法之前，我们需要理解控制器动作的一些事情。

　　控制器中的哪些方法被看成为是“动作”？当选择一个动作时，这个框架只考察控制器的public实例方法。而且，它会排除特殊名称的方法（构造器、事件、操作符、重载等等），以及集成自ApiController的类方法。

HTTP Methods

这个框架只会选择与请求的HTTP方法匹配的动作，确定如下：

　　1.你可以用注解属性AcceptVerbs、HttpDelete、HttpGet、HttpHead、HttpOptions、HttpPatch、HttpPost、或HttpPut来指定HTTP方法。

　　2.否则，如果控制器方法名称以“Get”、“Post”、“Put”、“Delete”、“Head”、“Options”、或“Patch”开头，那么根据这个约定，该Action将支持相应的HTTP方法。

　　3.如果以上都不是，那么这个方法将支持Post。

Parameter Bindings.

　　参数绑定是指Web API如何创建参数值。以下是参数绑定的默认规则：1.简单类型取自URI。2.复杂类型取自请求正文。

简单类型包括所有“.NET框架简单类型”，另外还有，DateTime、Decimal、Guid、String和TimeSpan。对于每一个动作，最多只有一个参数可以读取请求正文。

它也可以重写这种默认的绑定规则。See WebAPI Parameter binding under the hood。

在这种背景下，动作选择算法如下：

1.创建该控制器中与HTTP请求方法匹配的所有动作的列表。

2.如果路由字典有“action”条目，移除与该条目值不匹配的动作。

3.试图将动作参数与该URI匹配，如下：

　　a:针对每个动作，获得简单类型的参数列表，这是绑定得到URI参数的地方。该列表不包括可选参数。

　　b:从这个列表中，试着在路由字典或是在URI查询字符串中，找到每个参数的匹配。匹配是与大小写无关的，且与参数顺序无关。

　　c：选择这样的一个action,在列表中的每个参数在URI中有一个匹配。

　　d:如果满足这些条件的动作不止一个，选用参数匹配最多的一个。

4.忽略用[NonAction]注解属性标注的动作。

第3步可能会让人困扰。其基本思想是，可以从URI、或请求体、或一个自定义绑定来获取参数值。对于来自URI的参数，我们希望确保URI在其路径（通过路由字典）或查询字符串中实际包含了一个用于此参数的值。

例如，考虑以下动作：

public void Get(int id)

其id参数绑定到URI。因此，这个动作只能匹配在路由字典或查询字符串中包含了“id”值的URI。

可选参数是一个例外，因为它们是可选的。对于可选参数，如果绑定不能通过URI获取它的值，是没关系的。

复杂类型是另一种原因的例外。一个复杂类型只能通过自定义绑定来绑定到URI。但是在这种情况下，这个框架不能提前知道是否这个参数被绑定到一个特殊的URI。为了查明情况，这个框架需要调用这个绑定。选择算法的目的是在调用绑定之前根据静态描述来选择一个动作。因此，复杂类型是属于匹配算法之外的。

动作选择之后，会调用所有参数绑定。

Summary:

1.动作必须匹配请求的HTTP方法。

2.动作名必须匹配路由字典中的“action”条目，如果有。

3.对于动作的各个参数，如果参数取自URI，那么该参数名必须在路由字典或URI查询字符串中能够被找到。（可选参数和复杂类型除外）。

4.试图匹配最多数目的参数。最佳匹配可能是一个无参数的方法。

Extended Example

看如下路由：

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 }
);

再看如下Contoller下的内容：

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请求：

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

路由匹配：

该URI与名为“DefaultApi”路由匹配。路由字典包含以下条目：controller:"products",id:"1"。该路由字典并未包含查询字符串参数“version”和“details”，但这些将在动作选择期间考虑。

控制器选择：

根据路由字典中的“controller”条目，控制器类型是ProductsController。

动作选择：

这个HTTP请求是一个GET请求。支持Get的控制器动作是GetALL、GetById、FindProductsByName。这个路由字典不包含”action“条目，因此不需要匹配动作名称。

下一步，会试图匹配这些动作的参数名，只考查GET动作。

注意，不会考虑GetById的version参数，因为它是一个可选参数。

GetAll方法非常匹配。GetById方法也匹配，因为路由字典包含了“id”。FindProductsByName方法不匹配。

GetById方法是赢家，因为它匹配了一个参数，而GetAll无参数。该方法将以以下参数值被调用：id=1,version=1.5

注意，虽然version未被用于选择算法，但该参数值会取自URI查询字符串。

Extension Points

Web API为路由过程的某些部分提供了扩展点。

要为以上任一接口提供自己的实现，可使用HttpConfiguration对象的Services集合：

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

总结