WebAPI的中路由设计与ASP.NET相似,但又是独立的一套框架。
HttpRoute
HttpRoute主要提供了路由模板,用于匹配url,生成virtualPath.
public interface IHttpRoute
{
IDictionary<string, object> Constraints { get; }
IDictionary<string, object> Defaults { get; }
string RouteTemplate { get; }
IHttpRouteData GetRouteData(string virtualPathRoot, HttpRequestMessage request);
IHttpVirtualPathData GetVirtualPath(HttpRequestMessage request, IDictionary<string, object> values);
}
在HttpRoute中我们可以看到RouteTemplate是用于定义路由模板。在RouteTemplate中所有带大括号的数据都会作为路由变量,而路由就是url与路由变量的匹配。
比如:
api/{controller}/{action}/{id}
这个RouteTemplate包含三个路由变量:controller,action,id
另外对于IHttpRoute 的其它几个属性与方法都是围绕路由变量展开的。
Defaults:
这个属性用于设置路由变量的默认值。
比如:
HttpRouteValueDictionary defaults = new HttpRouteValueDictionary();
defaults.Add("controller", "Demo");
defaults.Add("action","Get");
HttpRouteConstraint
除了进行参数匹配外,WebAPI还提供了参数格式的匹配:
public interface IHttpRouteConstraint
{
bool Match(HttpRequestMessage request, IHttpRoute route, string parameterName, IDictionary<string, object> values, HttpRouteDirection routeDirection);
}
在IHttpRouteConstraint只定义一个Match方法。方法的第一个参数request即被验证的请求。第二个参数为HttpRouteConstraint所在的HttpRoute对象。第四个参数是Route匹配出来所有的路由变量与路由变量值。第五个参数是验证的方向(即是用于请求url的验证,还是对生成url的验证)。
对于第三个参数parameterName,则可能有两种解释:1.路由变量,2.仅仅是一个标识。对于 第一种情况大家应该好理解。对于第二种情况,我们可以用HttpMethodConstraint作为例子。
HttpMethodContraint是对请求方法的一种限制验证,他不对应任何路由变量。所以这个时候parameterName仅仅只是一个标识。
我们再看一下HttpRoute的Constraints属性。它是IDictionary<string, object>类型。其实string对应的就是就是参数parameterName,object对应的是HttpRouteContraint.
WebAP提供了一些HttpRouteConstraint派生类。都位于System.Web.Http.Routing.Constraints 命名空间下。
类 | 描述 |
AlphaRouteConstraint | 约束某个路由参数,使之仅包含小写或大写英文字母 A 到 Z。 |
BoolRouteConstraint | 约束某个路由参数,使之仅代表布尔值。 |
CompoundRouteConstraint | 按多个子约束来约束路由。 |
DateTimeRouteConstraint | 约束某个路由参数,使之仅代表 DateTime 值。 |
DecimalRouteConstraint | 约束某个路由参数,使之仅代表小数值。 |
DoubleRouteConstraint | 约束某个路由参数,使之仅代表 64 位浮点值。 |
FloatRouteConstraint | 约束某个路由参数,使之仅代表 32 位浮点值。 |
GuidRouteConstraint | 约束某个路由参数,使之仅代表 Guid 值。 |
IntRouteConstraint | 约束某个路由参数,使之仅代表 32 位整数值。 |
LengthRouteConstraint | 将路由参数约束为具有给定长度的或者位于给定长度范围内的字符串。 |
LongRouteConstraint | 约束某个路由参数,使之仅代表 64 位整数值。 |
MaxLengthRouteConstraint | 将路由参数约束为有一个最大长度的字符串。 |
MaxRouteConstraint | 将路由参数约束为有一个最大值的整数。 |
MinLengthRouteConstraint | 将路由参数约束为有一个最大长度的字符串。 |
MinRouteConstraint | 将路由参数约束为有一个最小值的长型值。 |
OptionalRouteConstraint | 根据在可选参数设置为默认值时不会失败的内部约束来约束路由。 |
RangeRouteConstraint | 将路由参数约束为给定值范围内的某个整数。 |
RegexRouteConstraint | 约束某个路由参数以匹配正则表达式。 |
HttpRouteData
HttpRoute的GetRouteData返回路由匹配及验证成功后的结果,即HttpRouteData。
当然HttpRoute中只会包含匹配成功的路由变量。
public interface IHttpRouteData
{
IHttpRoute Route { get; }
IDictionary<string, object> Values { get; }
}
其中Route是进行匹配的Route,Values是匹配成功的路由变量的字典。
HttpRouteCollection
HttpRouteCollection主要功能是存储HttpRoute,再根据HttpRequestMessage查找出HttpRoute.
HttpRouteCollection提供了MapHttpRoute方法用于添加HttpRoute当然我们也可以直接使用Add方法
public static IHttpRoute MapHttpRoute(this HttpRouteCollection routes, string name, string routeTemplate);
public static IHttpRoute MapHttpRoute(this HttpRouteCollection routes, string name, string routeTemplate, object defaults);
public static IHttpRoute MapHttpRoute(this HttpRouteCollection routes, string name, string routeTemplate, object defaults, object constraints);
public static IHttpRoute MapHttpRoute(this HttpRouteCollection routes, string name, string routeTemplate, object defaults, object constraints, HttpMessageHandler handler);
在进行HttpRoute查找的过程过HttpRoute会逐一HttpRoute进行匹配。直到找到对应的HttpRoute。
在HttpRoute匹配与HttpRouteConstraint验证的过程中只要未得到正确结果都将返回404 NOT FOUND
路径生成
在IHttpRouteConstraint.Match方法中的第五个参数(routeDirection)是验证的方向,除了对请求的url进行匹配处,还可以按照HttpRoute生成url。现在我们看下HttpRouteDirection
public enum HttpRouteDirection
{
UriResolution = 0,
UriGeneration = 1,
}
UriResolution与UriGeneration分别表示Uri解析与生成。HttpRoute也提供了一个GetVirtualPath用于生成Uri。
IHttpVirtualPathData GetVirtualPath(HttpRequestMessage request, IDictionary<string, object> values);
values.Add(HttpRoute.HttpRouteKey, true);
如果我们去调用GetVituralPath可能需要在values参数中添加一个<HttpRoute.HttpRouteKey,true>项
特性路由
对于上述的路由设置是全局的,另外WebAPI还提供了特性路由用于对Action的路由设置。
WebAPI提供了RouteAttribute来标识特性路由。
[AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, Inherited = true, AllowMultiple = true)]
public sealed class RouteAttribute : Attribute, IDirectRouteFactory, IHttpRouteInfoProvider
{
public string Name { get; set; }
public int Order { get; set; }
public string Template { get; }
}
通过Template属性我们可以直接给路由模板。
另外WebApi还提供了一个用于路由前缀的特性标识:RoutePrefixAttribute。RouteAttrbute与RoutePrefixAttribute合并起来就是一个完整的路由。(当然前缀里面是不能包含路由变量的)
特性路由的注册
特性路由也存储在HttpRouteCollection中,但是WebAPI采用RouteCollectionRoute进行路由存储,所以数据特性路由都以MS_attributerouteWebApi的name存储在HttpRouteCollection中,对于这点,因为RouteCollectionRoute是一个internal类,所以这里我就不扩展了。
特性路由的注册与HttpConfiguration的扩展方法MapHttpAttributeRoute执行。
特性路由的约束
特性路由也为我们提供了路由变量约束的功能,它是通过表达示的方式来进行的。
比如
[Route("Attr/Add/{a:int}/{b:int}")]
这个时候a,b两个路由变量都加上了IntRouteConstraint.
下面是WebAP提供了约束列表:
约束类型 | HttpRouteConstraint类型 |
bool | BoolRouteConstraint |
datetime | DateTimeRouteConstraint |
decimal | DecimalRouteConstraint |
double | DoubleRouteConstraint |
float | FloatRouteConstraint |
guid | GuidRouteConstraint |
int | IntRouteConstraint |
long | LongRouteConstraint |
alpha | AlphaRouteConstraint |
regex | RegexRouteConstraint |
max | MaxRouteConstraint |
min | MinRouteConstraint |
range | RangeRouteConstraint |
maxlength | MaxLengthRouteConstraint |
minlength | MinLengthRouteConstraint |
length | LengthRouteConstraint |
源码
Github: https://github.com/BarlowDu/WebAPI (API_7)