首页 > 代码库 > Web API-属性路由
Web API-属性路由
路由(Routing)就是Web API如何将一个URI匹配到一个action的过程。Web API 2 支持一个新的路由方式-属性路由(attribute routing)。顾名思义,属性路由使用标识属性去定义路由,属性路由可以使你在Web API中更方便的定制你的URIs。例如,你可以很容易的创建描述不同层次资源的URIs。
前面将的路由风格,叫做基于约定的路由(convention-based)在Web API中也完全支持,实际上,你能够在项目中同时使用两种路由技术。
这篇文章主要演示如何在项目中启用属性路由(attribute routing)和描述各种属性路由的使用方式,主要内容:
--1、为什么需要属性路由
--2、允许属性路由
--3、添加路由属性
--4、路由前缀
--5、路由约束
--6、可选择的URI参数以及默认值
--7、路由名称
--8、路由顺序
1、为什么需要属性路由
第一个发布版的Web API使用 convention-based routing(基于约定的)。在这种风格的路由中,你定义一个或者多个路由模版,基本上是参数化的字符串。当框架接收到一个请求,框架将URI与路由模版进行匹配。
convention-based路由的一个优势是:路由模版定义在一个文件中,路由规则被应用到所以的控制器上。但是convention-based方式的路由风格,要实现支持像RESTful APIs中常见的特定的URI模式比较麻烦。例如,资源经常包含子资源:Customers have orders, movies have actors, books have authors,等等。创建能够反映这种关系的URI是必须的:/customers/1/orders
使用convention-based 路由很难去实现这种风格的URI(This type of URI is difficult to create using convention-based routing),尽管可以实现,但结果不佳,如果你有很多控制器和资源类型。
使用属性路由,你可以很容易的为这样的URI定义一个路由,只需要给一个控制器的action添加一个标识属性:
[Route("customers/{customerId}/orders")]public IEnumerable<Order> GetOrdersByCustomer(int customerId) { ... }
还有一些情况下使用属性路由将非常方便:
--API 版本(API versioning)
/api/v1/products
/api/v2/products
解释:假设要控制请求访问不同版本的api,如果是convention-based风格的路由,意味着这里的v1 ,v2被定义为参数,那么必须在action中接收这个参数,然后在action中才能判断出版本(貌似这个时候知道版本用处不大了)我们要实现的是v1 ,v2 访问的是不同的控制器。那么使用属性路由很容易实现这一点,比如一个方法只在v2中有:
[Route("/api/v2/products")]public Ienumerable<Product> GetAll(){}
(如何实现版本控制,细节可能要在项目中去感受)
--重载 URI片段(Overloaded URI segments)
/orders/1
/orders/pending
这个例子中"1"是一个订单编号,但是"pending"对应了一个订单集合。
--复杂的参数类型
/orders/1
/orders/2013/06/16
这个例子中"1" 是一个订单编号,但是"2013/06/16"指定了一个日期。
2、允许属性路由
Global.asax文件
protected void Application_Start(){ // Pass a delegate to the Configure method. GlobalConfiguration.Configure(WebApiConfig.Register);}
WebApiConfig类
public static void Register(HttpConfiguration config){ // Web API routes config.MapHttpAttributeRoutes(); // Other Web API configuration not shown.}
config.MapHttpAttributeRoutes()方法启用属性路由。
3、添加路由标识属性
一个例子:
public class OrdersController : ApiController{ [Route("customers/{customerId}/orders")] [HttpGet] public IEnumerable<Order> FindOrdersByCustomer(int customerId) { ... }}
字符串"customers/{customerId}/orders"是路由的URI模版,Web API尝试将请求URI与这个模版匹配,这个例子中"coustomers" 和 "orders" 是纯文本片段,{customerId}是占位符,下面的URI都会与这个模版匹配:
- http://localhost/customers/1/orders
- http://localhost/customers/bob/orders
- http://localhost/customers/1234-5678/orders
可以使用约束限制{customerId}匹配的范围,下面会讲到。
注意在路由模版中的{customerId}参数,和action方法中的customerId参数匹配,当Web API调用控制器的action,将进行参数绑定,例如如果URI是: http://example.com/customers/1/orders
Web API会将值“1”传递的action方法的customerId参数。一个URI模版可以有多个占位符参数:
[Route("customers/{customerId}/orders/{orderId}")]public Order GetOrderByCustomer(int customerId, int orderId) { ... }
--HTTP请求方式
默认情况下Action方法使用方法开头用请求方式名称的方式两匹配不同的HTTP请求(忽略大小写的),可以通过添加标识属性来指定某一个action方法匹配的HTTP请求方式:
[HttpDelete]
[HttpGet]
[HttpHead]
[HttpOptions]
[HttpPatch]
[HttpPost]
[HttpPut]
例如:
[Route("api/books")][HttpPost]public HttpResponseMessage CreateBook(Book book) { ... }// WebDAV method[Route("api/books")][AcceptVerbs("MKCOL")]public void MakeCollection() { }
4、路由前缀
很多时候一个控制器下的action路由模版的前面部分都是相同的,为了不重复书写,可以这样:
[RoutePrefix("api/books")]public class BooksController : ApiController{ // GET api/books [Route("")] public IEnumerable<Book> Get() { ... } // GET api/books/5 [Route("{id:int}")] public Book Get(int id) { ... } // POST api/books [Route("")] public HttpResponseMessage Post(Book book) { ... }}
[RoutePrefix("api/books")] 给控制器下的所有action方法增加了路由模版前缀。
如果有特殊情况,你可以在action方法的标识属性中使用浪符号(~)来覆盖指定的统一的路由前缀:
[RoutePrefix("api/books")]public class BooksController : ApiController{ // GET /api/authors/1/books [Route("~/api/authors/{authorId:int}/books")] public IEnumerable<Book> GetByAuthor(int authorId) { ... } // ...}
路由前缀也可以包含占位符参数:
[RoutePrefix("customers/{customerId}")]public class OrdersController : ApiController{ // GET customers/1/orders [Route("orders")] public IEnumerable<Order> Get(int customerId) { ... }}
5、路由约束
路由约束允许你限制路由模版中占位符参数的匹配范围,基本语法是{parameter:constraint}。例如:
[Route("users/{id:int}"]public User GetUserById(int id) { ... }[Route("users/{name}"]public User GetUserByName(string name) { ... }
GetUserById 方法只匹配id参数为整型的URI
支持的约束条件:
Constraint | Description | Example |
alpha | Matches uppercase or lowercase Latin alphabet characters (a-z, A-Z) | {x:alpha} |
bool | Matches a Boolean value. | {x:bool} |
datetime | Matches a DateTime value. | {x:datetime} |
decimal | Matches a decimal value. | {x:decimal} |
double | Matches a 64-bit floating-point value. | {x:double} |
float | Matches a 32-bit floating-point value. | {x:float} |
guid | Matches a GUID value. | {x:guid} |
int | Matches a 32-bit integer value. | {x:int} |
length | Matches a string with the specified length or within a specified range of lengths. | {x:length(6)} |
long | Matches a 64-bit integer value. | {x:long} |
max | Matches an integer with a maximum value. | {x:max(10)} |
maxlength | Matches a string with a maximum length. | {x:maxlength(10)} |
min | Matches an integer with a minimum value. | {x:min(10)} |
minlength | Matches a string with a minimum length. | {x:minlength(10)} |
range | Matches an integer within a range of values. | {x:range(10,50)} |
regex | Matches a regular expression. | {x:regex(^\d{3}-\d{3}-\d{4}$)} |
有些约束条件可以组合使用,比如"min":必须为整型且大于或等于1
[Route("users/{id:int:min(1)}")]public User GetUserById(int id) { ... }
自定义路由约束
通过实现IHttpRouteConstraint接口来创建自定义的路由约束,例如下面的代码定义了一个“不能为0”的整数约束。
public class NonZeroConstraint : IHttpRouteConstraint{ public bool Match(HttpRequestMessage request, IHttpRoute route, string parameterName, IDictionary<string, object> values, HttpRouteDirection routeDirection) { object value; if (values.TryGetValue(parameterName, out value) && value != null) { long longValue; if (value is long) { longValue = (long)value; return longValue != 0; } string valueString = Convert.ToString(value, CultureInfo.InvariantCulture); if (Int64.TryParse(valueString, NumberStyles.Integer, CultureInfo.InvariantCulture, out longValue)) { return longValue != 0; } } return false; }}
下面代码展示如果注册自定义的约束:
public static class WebApiConfig{ public static void Register(HttpConfiguration config) { var constraintResolver = new DefaultInlineConstraintResolver(); constraintResolver.ConstraintMap.Add("nonzero", typeof(NonZeroConstraint)); config.MapHttpAttributeRoutes(constraintResolver); }}
现在就可以在路由中使用这个自定义的约束条件了:id必须为非0整数
[Route("{id:nonzero}")]public HttpResponseMessage GetNonZero(int id) { ... }
还可以通过实现IInlineConstraintResolver 接口的方式来覆盖所有的内置的约束。
6、可选择的URI参数和默认值
你可以通过给路由参数添加 问号"?”的方式来标识这个参数是可选的,如果路由模版中定义了可选参数,那么必须为action方法参数指定一个默认值(可选参数)。
public class BooksController : ApiController{ [Route("api/books/locale/{lcid:int?}")] public IEnumerable<Book> GetBooksByLocale(int lcid = 1033) { ... }}
上面这个例子,
/api/books/locale/1033 和
/api/books/locale
将返回同样的资源
还可以在路由模版中直接指定默认值:
public class BooksController : ApiController{ [Route("api/books/locale/{lcid:int=1033}")] public IEnumerable<Book> GetBooksByLocale(int lcid) { ... }}
上面两个例子功能基本相同,但也有细微的差别:
--在第一个例子中“{lcid:int?}”,默认值直接在action方法的参数位置指定,所以action方法有一个确定类型的默认值。
--第二个例子中“{lcid=1033}”,因为在路由模版中指定的默认值,那么需要经过模型绑定的过程,模型绑定过程会将“1033”从字符类型转换成数字类型,如何自定义了模型绑定方式,可能还有其他的不同的地方。
两个例子的功能一般情况下都是相同的,除非自定义了模型绑定。
7、路由名称
在Web API中每一个路由项都有一个名称,路由名称在生成链接的时候非常有用,隐藏你可以在返回消息中包含一个有效的链接。
使用Name 属性指定路由名称,下面的例子展示了如何定义路由名称,以及如何使用路由名称生成链接:
public class BooksController : ApiController{ [Route("api/books/{id}", Name="GetBookById")] public BookDto GetBook(int id) { // Implementation not shown... } [Route("api/books")] public HttpResponseMessage Post(Book book) { // Validate and add book to database (not shown) var response = Request.CreateResponse(HttpStatusCode.Created); // Generate a link to the new book and set the Location header in the response. string uri = Url.Link("GetBookById", new { id = book.BookId }); response.Headers.Location = new Uri(uri); return response; }}
8、路由顺序
当框架尝试去将一个URI匹配到一个路由时,会给路由进行排序,如果需要自定义顺序,可以在路由标识属性中使用RouteOrder 属性,较小的值排在前面,默认的排序值是0。
排序是如何确定的:
1.比较路由标识属性的RouteOrder属性值。
2.查看路由模版中的每一个URI片段,对于每一个片段,按照下面的方式排序
1-纯文本片段
2-带约束条件的路由参数
3-不带约束条件的路由参数
4-带约束条件的通配符路由参数
5不带约束条件的通配符路由参数
3.In the case of a tie, routes are ordered by a case-insensitive ordinal string comparison (OrdinalIgnoreCase) of the route template.
看例子:
[RoutePrefix("orders")]public class OrdersController : ApiController{ [Route("{id:int}")] // constrained parameter public HttpResponseMessage Get(int id) { ... } [Route("details")] // literal public HttpResponseMessage GetDetails() { ... } [Route("pending", RouteOrder = 1)] public HttpResponseMessage GetPending() { ... } [Route("{customerName}")] // unconstrained parameter public HttpResponseMessage GetByCustomer(string customerName) { ... } [Route("{*date:datetime}")] // wildcard public HttpResponseMessage Get(DateTime date) { ... }}
那么这些路由的排序如下:
1、orders/details
2、orders/{id}
3、orders/{customerName}
4、orders/{*date}
5、orders/pending
前面有讲过,在URI匹配路由模版时是从路由的排列顺序开始匹配,一旦匹配成功则会忽略后面的路由模版了。
Web API-属性路由