首页 > 代码库 > Web API-路由(一)
Web API-路由(一)
这一篇文章描述了ASP.NET API如何将HTTP请求路由到控制器。
如果你熟悉ASP.NET MVC,Web API路由和MVC路由非常相似,主要的不同地方是Web API使用HTTP方法,而不是URI路径去选择action。你也能够在WebAPI中使用MVC风格的路由,这一篇文章不讨论任何有关MVC的知识。
路由表:
在ASP.NET Web API 中,一个控制器是一个处理HTTP请求的类,Controller中的公共方法称作action方法或者简单方法,当Web API框架接收到一个请求,框架将请求路由到一个action。
Web API框架使用路由表(route table)来决定哪一个action被调用。VS的Web API 项目模版创建了一个默认的路由模版:
routes.MapHttpRoute( name: "API Default", routeTemplate: "api/{controller}/{id}", defaults: new { id = RouteParameter.Optional });
这个路由模版定义在 App_Start目录下的WebApiConfig.cs文件中。更多关于WebApiConfig的信息 可以看:Configuring ASP.NET Web API .
如果使用自寄宿(self-host)的Web API,必须通过HttpSelfHostConfiguration自己设置路由表,更多信息可以参考:Self-Host a Web API.
路由表中的每个条目包含一个模板,默认的Web API路由模版是“api/{controller}/{id}”。这个模版里,“api”是一个纯文本路径段,{controller}和{id}是占位符(参数变量)。当Web API框架接收到一个请求时,尝试将URI与路由表中的项(路由模版)匹配,如果没有可以匹配的路由项,则返回一个404错误,比如下面三个uri可以和默认的路由模版进行匹配。
/api/contacts
/api/contacts/1
/api/products/gizmo1
但是/contacts/1这个就匹配不了因为缺少“api"段。
注:Web API 路由模版使用“api”开头是为了避免与MVC的路由模版冲突,这样你能够使用"/contacts"URI去路由到一个MVC controller,而使用"api/contacts" 路由到一个Web API controller。当然,如果你不喜欢,可以修改默认的路由模版。
一旦找到匹配的路由,Web API则进行controller和action的选择:
--To find the controller, Web API adds "Controller" to the value of the {controller} variable.
--匹配action,Web API 查看本次HTTP 方法,比如:如果是GET方法,则在controller中查找Get开头的方法,这种查询以HTTP请求方式开头的action的方式只适合GET , POST , PUT 和 DELETE 方式Http请求???,你可以通过为action添加标识属性的方法来指定action可匹配的HTTP请求方式以及允许其他的HTTP请求方式。
--其他的路由模版中的占位符变量,比如{id},映射为一个action参数。
下面看一个例子:定义一个如下的controller
public class ProductsController : ApiController{ public void GetAllProducts() { } public IEnumerable<Product> GetProductById(int id) { } public HttpResponseMessage DeleteProduct(int id){ }}
下面表格展示了不同的URI所调用的action
HTTP Method | URI Path | Action | 参数 |
GET | api/products | GetAllProducts | 无 |
GET | api/products/4 | GetProductById | 4 |
DELETE | api/products/4 | DeleteProduct | 4 |
POST | api/products | 没有匹配的action |
|
注意:这里的{id}段,如果指定了{id}的值,则调用有id参数的action方法 GetProductById。
因为没有定义Post开头的aciton方法,所以POST方式的请求找不到匹配的action。
路由拓展
--使用Http Methods 标识属性:除了定义以HTTP请求方式开头的action方法外,我们可以使用HttpGet , HttpPut , HttpPost 或者 HttpDelete标识属性来指定一个action方法匹配的HTTP请求方式(与使用HTTP请求方式开头的方法名效果一样),例如,下面这个方法可以和GET请求方式的HTTP请求匹配。
public class ProductsController : ApiController{ [HttpGet] public Product FindProduct(id) {}}
如果一个action方法需要匹配多种HTTP请求方式,或者需要匹配除GET,POST,PUT,DELETE请求方式外的其他请求,可以使用AccptVerbs标识属性。例如:FindProduct方法可以同时匹配 GET 和 HEAD请求。
public class ProductsController : ApiController{ [AcceptVerbs("GET", "HEAD")] public Product FindProduct(id) { } // WebDAV method [AcceptVerbs("MKCOL")] public void MakeCollection() { }}
--使用MVC风格的路由
定义路由模版:
routes.MapHttpRoute( name: "ActionApi", routeTemplate: "api/{controller}/{action}/{id}", defaults: new { id = RouteParameter.Optional });
在这个路由模版中,{action}参数指定controller中的action的名称,使用这种风格的路由,需要使用标识属性指定action允许匹配的HTTP请求方式,比如:必须使用[HttpGet]、[HttpPost]等标识属性。
public class ProductsController : ApiController{ [HttpGet] public string Details(int id);}
上面的例子中一个“api/products/details/1”的GET请求,将映射到Details方法。这种风格很像MVC,可能更适合用在一个RPC-style API中。
--使用ActionName属性定义action的别名:
public class ProductsController : ApiController{ [HttpGet] [ActionName("Thumbnail")] public HttpResponseMessage GetThumbnailImage(int id); [HttpPost] [ActionName("Thumbnail")] public void AddThumbnailImage(int id);}
我们可以发送uri为 "api/products/thumbnail/id"的GET请求 map to GetThumbnailImage方法。
发送uri为"api/products/thumbnail/id"的POST请求 map to AddThumbnailImage 方法。
通过上面几个例子可以看出,可以使用标识属性,配置一个action方法用作匹配路由的名称和方法。
--使用[NonAction]标识属性来指定一个方法不为action方法。
Web API-路由(一)