ASP.NET Web API 中的属性路由

为什么要有属性路由 

基于约定路由的一个优点是模板在单个位置中定义，并且路由规则在所有控制器上一致的应用。但是基于约定的路由很难支持RESTFUl 中常见的某些URI模式。例如，资源通常包含子资源，客户有订单，电影有演员，书有作者等等。创建反应这些URI是很自然的，如下图所示：

/customers/1/orders

 使用属性路由，为此URI定义路由很简单，只需向控制器中添加一个属性，如下图所示：

[Route("customers/{customerId}/orders")]
public IEnumerable<Order> GetOrdersByCustomer(int customerId) { ... }

 

---

启用属性路由 

要启用属性路由，要在配置期间调用MapHttpAttributeRoutes，此方法在System.Web.Http.HttpConfigurationExtensions类中定义。如下图所示： 

using System.Web.Http;

namespace WebApplication
{
    public static class WebApiConfig
    {
        public static void Register(HttpConfiguration config)
        {
            // Web API routes
            config.MapHttpAttributeRoutes();

            // Other Web API configuration not shown.
        }
    }
}

属性路由可以和约定路由相结合，要定义基于约定的路由，可以调用MapHttpRoute方法。如下图所示： 

public static class WebApiConfig
{
    public static void Register(HttpConfiguration config)
    {
        // Attribute routing.
        config.MapHttpAttributeRoutes();

        // Convention-based routing.
        config.Routes.MapHttpRoute(
            name: "DefaultApi",
            routeTemplate: "api/{controller}/{id}",
            defaults: new { id = RouteParameter.Optional }
        );
    }
}

---

添加属性路由 

public class OrdersController : ApiController
{
    [Route("customers/{customerId}/orders")]
    [HttpGet]
    public IEnumerable<Order> FindOrdersByCustomer(int customerId) { ... }
}

字符串“customers/{customerId}/orders”是路径的URI模板，Web API尝试将请求URI和模板匹配。在此示例中，“customers”和“orders”是静态片段，{customerId}是可变参数，以下URI将与此模板匹配：

• http://localhost/customers/1/orders
• http://localhost/customers/bob/orders
• http://localhost/customers/1234-5678/orders

请注意：路由模板中的{customerId}参数要和方法中customerId相匹配，当WebAPI调用控制器操作时，它会尝试绑定路由参数。例如 URI为 http://example.com/customers/1/orders ,则Web API会尝试将 值“1”绑定到操作的customerId参数中。

URI模板中可以有多个参数，如下图所示：

[Route("customers/{customerId}/orders/{orderId}")]
public Order GetOrderByCustomer(int customerId, int orderId) { ... }

 

Web API还根据请求的Http方法(Get，Post等)选择操作。默认情况下，Web API会查找与控制器方法名称的开头不区分大小写的匹配项。例如，控制器方法PutCustomer匹配HTTP PUT请求。 

以下示例将CreateBook方法映射到HTTP POST请求。 

[Route("api/books")]
[HttpPost]
public HttpResponseMessage CreateBook(Book book) { ... }

对于所有其他HTTP方法（包括非标准方法），请使用AcceptVerbs属性，该属性采用HTTP方法列表。 

// WebDAV method
[Route("api/books")]
[AcceptVerbs("MKCOL")]
public void MakeCollection() { }

 

---

路由前缀 

通常，控制器的中的路由都以相同的前缀开头，例如： 

public class BooksController : ApiController
{
    [Route("api/books")]
    public IEnumerable<Book> GetBooks() { ... }

    [Route("api/books/{id:int}")]
    public Book GetBook(int id) { ... }

    [Route("api/books")]
    [HttpPost]
    public HttpResponseMessage CreateBook(Book book) { ... }
}

您可以使用[RoutePrefix]属性为整个控制器设置公共前缀： 

[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) { ... }
}

在method属性上使用波浪号（〜）来覆盖路由前缀： 

[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) { ... }
}

---

路径约束允许限制路径模板中的参数匹配方式。一般语法是“{parameter：constraint}”。例如： 

[Route("users/{id:int}")]
public User GetUserById(int id) { ... }

[Route("users/{name}")]
public User GetUserByName(string name) { ... }

 这时候，只有id是整数时，才匹配第一路径。否则，将选择第二路径。完整的约束列表如下图所示：

约束	描述	例子
alpha	匹配大写或者小写拉丁字母：（a-z , A-Z）	{x:alpha}
bool	匹配布尔类型	{x:bool}
datetime	匹配DataTime类型	{x:datetime}
decimal	匹配小数值	{x:decimal}
double	匹配64位浮点数	{x:double}
float	匹配32位浮点数	{x:float}
guid	匹配Guid值	{x:guid}
int	匹配32位整型	{x:int}
length	匹配具有指定长度或者具有指定长度范围的字符串	{x:length(6)} {x:length(1,20)}
long	匹配64位整数值	{x:long}
max	匹配具有最大值的整数	{x:max(10)}
maxlength	匹配具有最大长度的字符串	{x:maxlength(10)}
min	匹配具有最小值的整数	{x:min(10)}
minlength	匹配具有最小长度的字符串	{x:minlength(10)}
range	匹配值范围内的整数	{x:range(10,50)}
regex	匹配正则表达式	{x:regex(^\d{3}-\d{3}-\d{4}$)}

可以将多个约束应用于参数，以冒号分隔 

[Route("users/{id:int:min(1)}")]
public User GetUserById(int id) { ... }

 

可以通过实现IHttpRouteConstraint，来创建自定义路由约束。例如，以下约束将参数限制为非零整数值。 

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);
    }
}

可以在路由中应用约束： 

[Route("{id:nonzero}")]
public HttpResponseMessage GetNonZero(int id) { ... }

 

---

可选的URI参数和默认值 

 可以通过向路由参数添加问号来使URI参数可选。如果route参数是可选的，则必须为方法参数定义默认值

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) { ... }
}

---

路由名称 

在Web API 中，每个路由都有一个名称。路由名称对于对于生成链接十分有用，因此可以在HTTP响应中包含链接。

要指定路由名称，请在属性上设置“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;
    }
}

---

路由顺序 

当框架尝试将URI与路由匹配时，它会按特定的顺序评估路由，要指定顺序，需要在Route属性上设置Order属性，框架首先评估Order值较低的方法，默认Order值为零。

以下是确定总排序的方式：

1、比较Route属性的Order属性。

2、查看路由模板中的每个URI片段，对于细分，约定如下：

      a、静态片段。

      b、使用约束路由参数。

      c、路由参数没有约束。

      d、具有约束的通配符参数段

      e、没有约束的通配符参数段

[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