ASP.NET Web API 中的路由

原文更新日期：2012.02.11

导航页面

http://blog.csdn.net/wf824284257/article/details/79475115

上一步

为ASP.NET Web API 创建帮助页面
http://blog.csdn.net/wf824284257/article/details/79462983

开始

这篇教程讲了ASP.NET Web API是如何将HTTP请求路由到controller的。

注意：如果你熟悉ASP.NET MVC，那太好了因为Web API的路由规则与MVC的非常相似，两者最主要的区别是Web API在选择action时使用的是HTTP路径，而不是URI路径。当然你也可以为Web API使用MVC风格的路由规则。这篇文章不涉及任何ASP.NET MVC的知识。

路由表（routing table）

在 ASP.NET Web API 中，controller是一个被用来处理HTTP请求的实体类（class），它的public的方法被称为action（action methods or simply actions）。当Web API framework 收到一个请求时，会将这个请求路由给一个action来处理。

Web API framework 使用一个路由表来判断调用哪个action。Visual Studio 里的Web API项目模板中含有一个默认的路由规则：

routes.MapHttpRoute(
    name: "API Default",
    routeTemplate: "api/{controller}/{id}",
    defaults: new { id = RouteParameter.Optional }
);

这个路由规则被定义在App_Start/WebApiConfig.cs里面。

################# 1

若想了解更多的关于“WebApiConfig”类的信息，可以看这篇教程：
https://docs.microsoft.com/en-us/aspnet/web-api/overview/advanced/configuring-aspnet-web-api

如果你有自己搭建的 Web API ，你一定要直接在HttpSelfHostConfiguration实体类上设置路由表。更多信息可以看这篇教程：
https://docs.microsoft.com/en-us/aspnet/web-api/overview/older-versions/self-host-a-web-api

路由表的每个入口都包含了一个路由模板，其中Web API的默认路由模板是”api/{controller}/{id}”。在这个路由模板中，“api”是一个字面意义的路径段，”{controller}”和”{id}”是一个变量占位符。

当 Web API framework 收到 HTTP请求时，它会尝试去匹配某个路由表中的某个路由模板的URI。如果都没有匹配成功，客户端将会收到一个404错误。举个例子，以下URI是可以匹配默认路由的：

/api/contacts
/api/contacts/1
/api/products/gizmo1

然而，以下URI是不会匹配成功的，因为它的URI中少了“api”字段：

/contacts/1

注意：之所以在路由模板中使用“api”字段，是为了避免与ASP.NET MVC的路由规则重复。这样的话，你就可以使用”/contacts”来访问MVC的controller，使用”/api/contacts”来访问 Web API controller。当然，如果你不喜欢按照这样的规定来做，你也可以修改默认的路由表。

一旦找到了一个匹配的路由模板，Web API 将会选择适用的controller和action。

为了找到对应的controller，Web API 将“controller”填入到{controller}变量中。
为了找到对应的action，Web API 先依据HTTP方法，找到一个以这个HTTP方法名开头的
action。比如，对于GET请求，Web API 会寻找一个以“Get…”开头的action，就像“GetContact”或者“GetAllContacts”。这些惯例仅适用于 GET, POST, PUT 和 DELETE 方法。你可以通过给你的controller添加特性来适用其他的HTTP方法。一会我们将会看一个例子。
路由模板中的其他的占位变量，比如{id}，代表action的参数。

让我们来看一个例子。假设你定义了这样一个controller：

public class ProductsController : ApiController
{
    public IEnumerable<Product> GetAllProducts() { }
    public Product GetProductById(int id) { }
    public HttpResponseMessage DeleteProduct(int id){ }
}

下面是一些可能的HTTP请求，包含了它们用到的action：

############# 2

注意URI中的{id}字段，该字段对应的是action中的名为id的参数。在这个例子中，这个controller定义了两个GET方法，其中一个带有id参数，另外一个不带有id参数。

同时也要注意到，因为这个controller没有定义一个”Post…”开头的方法，所以POST请求会失败。

路由变化

前面的段落讲了 ASP.NET Web API 的基本的路由机制。在该段落将会介绍一些路由变化。

HTTP方法

对于action对应的HTTP请求类型，你除了使用HTTP请求方法开头来命名action之外，还可以使用HttpGet, HttpPut, HttpPost, 以及 HttpDelete 特性来为action指定对应的HTTP请求类型。

在下面这个例子中，FindProduct 方法会与GET请求对应。

public class ProductsController : ApiController
{
    [HttpGet]
    public Product FindProduct(id) {}
}

为了使一个action可以接受多个HTTP请求类型，或者为了让一个action不仅可以接受GET, PUT, POST，和 DELETE请求，可以为action使用AcceptVerbs特性来指定多个HTTP方法。

public class ProductsController : ApiController
{
    [AcceptVerbs("GET", "HEAD")]
    public Product FindProduct(id) { }

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

通过Action名字路由

Web API 通过默认的路由模板和HTTP方法来选择action。然而，你也可以创建一个路由规则，使路由的URI中包含action名字。

routes.MapHttpRoute(
    name: "ActionApi",
    routeTemplate: "api/{controller}/{action}/{id}",
    defaults: new { id = RouteParameter.Optional }
);

在上面的路由模板中，{action}参数代表controller中的action方法。在这种风格的路由规则中，可以使用特性来指定允许的HTTP方法。举个例子，假设你的controller含有以下方法：

public class ProductsController : ApiController
{
    [HttpGet]
    public string Details(int id);
}

在这个例子中，对”api/products/details/1”的GET请求将会匹配Details方法。这种路由风格与ASP.NET MVC非常相似，或许也与PRC风格的API类似。

你可以使用ActionName特性来重写action的名字。在下面的例子中，有两个action匹配”api/products/thumbnail/id”，一个支持GET方法，另一个支持POST。

public class ProductsController : ApiController
{
    [HttpGet]
    [ActionName("Thumbnail")]
    public HttpResponseMessage GetThumbnailImage(int id);

    [HttpPost]
    [ActionName("Thumbnail")]
    public void AddThumbnailImage(int id);
}

禁止action

我们可以使用 NonAction 特性来防止某个方法被作为action调用。使用该特性，就等于告诉framework这个方法不是一个action，就算这个方法可以匹配某个路由规则。

// Not an action method.
[NonAction]  
public string GetPrivateData() { ... }

下一步

结束

本文为微软官方文档的个人译文。本译文的非商用转载请注明地址及作者，感谢。禁止商用转载。若经发现，将依法追究责任。
英文原文地址：https://docs.microsoft.com/en-us/aspnet/web-api/overview/web-api-routing-and-actions/routing-in-aspnet-web-api
原文作者： MikeWasson and Other 3 Contributors
主作者链接：https://github.com/MikeWasson
作者尊重微软公司的知识产权，若贵公司认为该博客有损贵公司利益，请联系作者删除
译者：大吴凡 http://dawufan.cn