【Web API系列教程】2.1 — ASP.NET Web API中的路由机制

这篇文章描述了ASP.NET Web API如何将HTTP请求发送(路由)到控制器。

备注:如果你对ASP.NET MVC很熟悉,你会发现Web API路由和MVC路由非常相似。主要区别是Web API使用HTTP方法来选择动作(action),而不是URI路径。你也可以在Web API中使用MVC风格的路由。这篇文章不需要ASP.NET MVC的任何知识。

路由表

在ASP.NET Web API中,控制器是一个用于处理HTTP请求的类。控制器中的公共方法被称为动作方法或简单动作。当Web API框架收到请求时,它会将该请求路由到相应的动作中。

为了确定哪个动作该被执行,框架就会使用本节将讲解的路由表。Visual Studio的Web API项目模板就创建了一个默认的路由表:

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

这个路由被定义在App_Start目录下的WepApiConfig.cs文件中。

这里写图片描述

路由表中的每条记录都包含了一个路由模板。Web API的默认路由模板是“api/{controller}/{id}”。在这个模板中,”api”是一个字面路径字段,而{controller}和{id}都是占位符变量。

当Web API框架收到了HTTP请求时,它将会尽力匹配URI到路由表中的路由模板的其中一个。如果没有路由被匹配到,客户端就会收到404错误。例如,以下URI会匹配到默认路由:

  1. /api/contacts
  2. /api/contacts/1
  3. /api/products/gizmo1

然而,以下URI不会匹配到,因为它缺乏“api”字段。

/contacts/1

备注:在路由中使用“api”的原因是为了避免和ASP.NET MVC的路由冲突。也就是说,你可以使用”/contacts”匹配到MVC的路由,使用“api/contacts”匹配到Web API的路由。当然了,如果你不喜欢这种约定,你也可以修改默认路由表。

一旦某个路由匹配到了,Web API就会选择相应的控制器及动作:

  1. 为了找到控制器,Web API将“Controller”添加到{controller}变量上。
  2. 为了找到动作,Web API会遍历HTTP方法,然后查找一个其名字以HTTP方法的名字开头的动作。例如,有一个GET请求,Web API会查找以“Get….”开头的动作,比如”GetContact”或”GetAllContacts”。这种方式仅仅适用于GET、POST、PUT和DELETE方法。你可以通过在你的控制器中使用属性来启用其他HTTP方法。将晚些看到一个示例(超链接到本章的第三节……
  3. 路由模板的其他占位符变量,比如{id},会被映射到动作的参数。

让我们来看一个示例。假定你定义了如下的控制器:

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

这里是一些可能的HTTP请求,以及相应的得到执行的动作:

HTTP MethodURI PathActionParameter
GETapi/productsGetAllProducts(none)
GETapi/products/4GetProductById4
DELETEapi/products/4DeleteProduct4
POSTapi/products(no match)

注意URI的{id}字段,如果存在,它会被映射到动作的id参数中。在本例,控制器定义了两个GET方法,其中一个包含id参数,而另一个不包含id参数。

同样的,注意到POST请求会失败,因为控制器中并没有定义”POST…”方法。

路由偏差(Routing Variations)

前一节描述了ASP.NET Web API的基本路由机制。本节将开始描述一些变化。

HTTP方法

除了使用这些HTTP方法的命名约定,你也可以通过用HttpGet、HttpPut、HttpPost或HttpDelete属性来赋予这些动作来具体地为每个动作设定HTTP方法。

在下面这个例子中,FindProduct方法被映射到GET请求:

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

为了让一个动作支持多个HTTP方法,或支持除GET、PUT、POST和DELETE之外的HTTP方法,你可以使用AcceptVerbs属性,它以一个HTTP方法列表为参数。

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

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

通过动作名进行路由

有了默认的路由模板,Web API使用HTTP方法来选择动作。然而,你也可以创建一个将动作名包含在URI中的路由表。

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

在这个路由模板中,{action}参数在控制器中命名了一个动作方法。在这种风格的路由中,应使用属性来指定允许的HTTP方法。例如,假定你的控制器有了以下方法:

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

在这种情况下,对于“api/products/details/1”的GET请求被被映射到Details方法。这种风格的路由和ASP.NET MVC很接近,并且可能适合于RPC风格的API。

你可以通过ActionName属性来重写动作名。在接下来的例子中,存在两个都映射到”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);
}

无动作(Non-Actions)

为了阻止一个方法被当作动作来执行,可以使用NonAction属性。这会框架指明该方法并非一个动作,即使是它可能匹配到路由规则。

// Not an action method.
[NonAction]  
public string GetPrivateData() { ... }
  • 2
    点赞
  • 7
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
我觉得大部分人都是“眼球动物“,他们关注的往往都是目光所及的东西。对于很多软件从业者来说,他们对看得见(具有UI界面)的应用抱有极大的热忱,但是对背后支撑整个应用的服务却显得较为冷漠。如果我们将整个“生态系统”比喻成海面上漂浮的冰山,我们所能看的到的只是露出水面的冰山一角,水面之下才是一个“庞然大物”。 提到服务,我们自然想到Web Service。但是传统意义上的Web Service却有点名不副实,因为支撑它的其实不是Web而是SOAP,承载一个Web Service甚至可以根本不需要Web。随着互联网的普及,互联网应用(尤其移动互联网应用)已经成为主流,“SOAP之重”已经越来越令我们无法承受,于是采用REST架构风格并直接采用Web进行通信的轻量级Web Service走进了我们的视野并登堂入室。为了与传统的基于SOAP的Web Service以示区别,我们将后者称为Web API。 很多人鼓吹SOAP已死,我个人对此持不同的看法。上面讲的“重”与“轻”都是不带任何感情色彩的性词,至于优劣评价则决定于它们是否适合应用的场景。到目前为止,对于企业级应用之间的内部集成互联,我觉得传统的Web Service依然是最好的选择。传统Web Service应用的领域貌似在不断被Web API占据,但是后者并不能完全被视为前者的替代品,它只是让“踩过界”的Web Service退回到它应该坚守的领地。Web Service和Web API在各自适合的领域各司其职,使“路归路、桥归桥”是一种理想的状态。 Web Service和Web API的合理布局同样也体现在微软技术平台上。WCF在过去是唯一的选择,这是一个具有“SOAP”基因的通信平台,微软后来利用扩展让它提供了针对REST的支持。正因为如此,如果使用WCF来构建Web API的话,我们依然需要采用传统的编程方式,Web API的“简单、快捷”完全得不到体现。微软意识到在一个“重量级”通信框架上通过扩展实现“轻量级”的通信,还不如重新构建一个通信平台,于是ASP.NET Web API应运而生。

“相关推荐”对你有帮助么?

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值