Web API路由和动作选择

时间:2023-03-08 17:01:19

前言

  本文描述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。例如:

Web API路由和动作选择
routes.MapHttpRoute(
name: "DefaultApi",
routeTemplate: "api/{controller}/{category}",
defaults: new { category = "all" }
);
Web API路由和动作选择

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

Route Dictionary(路由字典)

  如果这个框架发现了一个匹配的URI,它会创建包含每个占位符值的一个字典。这个键值是不带花括号的的占位符名称。这个值取自于URI路径或者是默认值中的。这个字段被存在IHttpRouteData对象中。在匹配路由阶段,这个特殊的"{controller}" and "{action}"占位符的处理和其他占位符是一样的。它们用另外的值被简单的存储在字典中。

  在默认值中可以使用特殊的RouteParameter.Optional值。如果一个占位符被赋予了这个值,那么这个值将不会被添加到路由字典中,例如:

Web API路由和动作选择
routes.MapHttpRoute(
name: "DefaultApi",
routeTemplate: "api/{controller}/{category}/{id}",
defaults: new { category = "all", id = RouteParameter.Optional }
);
Web API路由和动作选择

对于URI路径“api/products”,路由字典将含有:controller:"products"、category:"all"。

然而,对于“api/products/toys/123”,路由字典将含有:controller:"products"、category:"toys"、id:"123"。

这个默认值也可以包含未出现在路由模板中的值。若这条路由匹配,则该值会被存储在路由字典中。例如:

Web API路由和动作选择
routes.MapHttpRoute(
name: "Root",
routeTemplate: "api/root/{id}",
defaults: new { controller = "customers", id = RouteParameter.Optional }
);
Web API路由和动作选择

如果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

看如下路由:

Web API路由和动作选择
Web API路由和动作选择
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 }
);
Web API路由和动作选择
Web API路由和动作选择

再看如下Contoller下的内容:

Web API路由和动作选择
Web API路由和动作选择
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) {}
}
Web API路由和动作选择
Web API路由和动作选择

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动作。

Web API路由和动作选择

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

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

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

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

Extension Points

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

Web API路由和动作选择

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

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

总结