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)} {x:length(1,20)}
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匹配路由模版时是从路由的排列顺序开始匹配，一旦匹配成功则会忽略后面的路由模版了。