实战 ASP.NET Web API

Web API 框架是一个面向 Http 协议的通信框架。相对于 WCF 而言，Web API 只面向于 Http 协议设计，而且没有 WCF 那么繁琐的配置。Web API 的开发类似于 ASP.NET MVC 中控制器的开发，但是相对于直接使用 ASP.NET MVC 来返回 Json 对象的方式而言，Web API 封装了数据的序列化、反序列化，接口、实现都更加简单。
简单地说，如果要向浏览器、移动端提供 Json 数据格式的 API，则应该首选 Web API 作为通信框架。

以下，我列出了在当前使用 Web API 开发系统时，遇到的几个知识点或问题。

 

数据序列化

---

Web API 框架目前支持两种数据格式的序列化：Json 及 Xml。在不做任何配置的情况下，如果 Http 请求中，HttpHeader 中 Accept 被指定为 accept: application/xml，则 Web API 会自动把数据使用 xml 进行序列化，否则使用 json 序列化。
如果期望不使用 xml 序列化数据，我们可以通过 GlobalConfiguration.Configuration.Formatters 来进行配置：config.Formatters.Remove(config.Formatters.XmlFormatter)。

一般情况下，我们会使用 Json 序列化。跟 ASP.NET MVC 的 Json 序列化不同的是，Web API 使用了 Newtonsoft.Json 框架来进行序列化。（例如，JsonMediaTypeFormatter.SerializerSettings 属性就是 Newtonsoft.Json.JsonSerializerSettings 类型，可以直接对序列化进行配置。）
Json 序列化支持对匿名类型进行进行序列化，这大大方便了开发人员，例如，我们可以随意组装数据并直接返回：

[HttpGet]
public IEnumerable AllGet()
{
    return new string[] { "Item1", "Item2" }.Select(s => new
    {
        Name = s,
        Code = s,
        Items = new ArrayList
        {
            new { Name = "Item1" },
            new { Name = "Item2" },
            new { Name = "Item3" },
            new { Name = "Item4" },
        }
    });
}

另外，Web API 提供了 HttpResponseMessage 类型可作为返回值，使得开发人员可以对 HttpResponse 做一些更详细的设置。而且，如果不期望修改返回值类型而直接返回 HttpResponse 时，可以使用 HttpResponseException 间接返回一个 HttpResponseMessage。

 

Action 匹配

---

Web API 框架默认是基于 Restful 架构模式的，与 ASP.NET MVC 有区别的是，它会根据 Http 请求的 HttpMethod（Get、Post、Put、Delete） 来在 Controller 中查找 Action，规则是：Action 名中是否以 Get、Post 开头？Action 上标记 HttpGet、HttpPost 等标记？并会完全忽视 Action 的方法名。

例如，Web API 对于资源的 CRUD 操作，采用如下格式：
get /API/models/ 查询所有实体
get /API/models/1000 查询id为1000的实体
post /API/models/ {id:-1, name:'name'} 添加一个实体
put /API/models/ {id:1000, name:'name'} 更新指定实体
delete /API/models/1 删除指定实体

由于忽视了方法名，所以的几个方法，在调用时会抛出异常：

 

在面向服务的架构中，往往不会直接把底层的实体公布出来，让客户端直接进行 CRU 操作；而是公布一些粗粒度的 RPC 形式的服务操作。要使用 Web API 框架，我们需要修改默认的配置。例如，让客户端在调用时显式指定 action 名称：

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

这样，由于显式指定了 Action 名称，Web API 会使用该名称来查找对应的 Action 方法，而不再按照 HttpMethod 约定来查找对应的 Action。例如，对于以下 API 的调用如下：

[HttpGet]
public HttpResponseMessage Login(string userName, string password)
{
    return Request.CreateResponse(HttpStatusCode.NotFound);
}

调用方法：
get /api/account/login/?username=hqf@qq.com&password=dsd

 

关于 POST 参数绑定

---

Web API 相对于 ASP.NET MVC，使用了新的参数绑定类。要注意的是，Action 参数列表中只能有一个参数可以从 Http Post Body 中反序列化出来。如果参数列表中只有一个参数，而且它的类型是一个复杂类型，那么 Web API 会直接把 Body 尝试反序列化为该类的对象。如果有多个参数，那么要从 Body 反序列化的那个参数，需要标记上 [FromBodyAttribute]。
相关内容，比较复杂，可以参考以下文章： 
http://www.cnblogs.com/sicket/archive/2012/06/28/2567129.html
http://www.cnblogs.com/lushuicongsheng/archive/2012/10/27/2742214.html
http://www.tuicool.com/articles/eQzyEv
http://weblogs.asp.net/cibrax/archive/2012/08/10/binding-form-data-in-asp-net-web-api.aspx

 

不错的示例代码

---

MSDN 上有一个比较全面的示例代码：
http://code.msdn.microsoft.com/ASPNET-Web-API-JavaScript-d0d64dd7

 

 

本文讲得比较浅，只是列举一些开发过程中会经常遇到的需要注意的点。解决这些问题后，我们的系统，已经开始使用 Web API 来进行开发了。