WebApi:路由和Action选择

时间:2024-01-02 10:46:02

 

译自:http://www.asp.net/web-api/overview/web-api-routing-and-actions/routing-and-action-selection

 

本文描述了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的默认实现,其使用了一个简单的算法:

  1. 用键为"controller"来查询在路由字典中查找键为"controller"的值。
  2. 将获取到的值的末尾加上"Controller",得到类型名称。
  3. 根据类型名称,从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方法,判断如下:

  1. 通过用属性来标记为HTTP方法:AcceptVerbsHttpDeleteHttpGetHttpHead,HttpOptionsHttpPatchHttpPost, 或者 HttpPut
  2. 或者,如果方法的名称以"Get", "Post", "Put", "Delete", "Head", "Options", 或者 "Patch"开头的,那么默认约定支持HTTP方法。
  3. 如果上面两条都没有满足,那么此方法被认为是支持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参数,如下:
    1. 对于每一个action,从URI获取简单类型参数的列表,排除可选参数。
    2. 在此参数列表中,在路由字典或者URI请求字符串中,为每一个参数名找到一个匹配。匹配是不分大小写的,且是无序的。
    3. 选择参数列表中的每一个参数均匹配的action。
    4. 如果有多个匹配的action,则选择参数最多的一个。
  4. 忽略[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的。

Action 

要匹配的参数

GetAll

none 

GetById

"id" 

FindProductsByName

"name"

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

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

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

  • id = 1
  • version = 1.5

 

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

 

 

 

 

5.扩展点

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

接口

描述

IHttpControllerSelector

选择一个控制器。

IHttpControllerTypeResolver

获取控制器类型列表。
DefaultHttpControllerSelector从此列表中选择控制器的类型。

IAssembliesResolver

Gets the list of project assemblies. 获取项目中的程序集列表IHttpControllerTypeResolver接口使用此列表找到控制器类型。

IHttpControllerActivator

创建一个新的控制器实例

IHttpActionSelector

选择一个Action

IHttpActionInvoker

调用一个Action

 

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

var config = GlobalConfiguration.Configuration;

config.Services.Replace(typeof(IHttpControllerSelector), new
MyControllerSelector(config));