ASP.NET Web API基础（03）--- Action的返回结果
3.1 Action的返回类型
Webapi的Action返回值主要有四种类型
- void无返回值
- IHttpActionResult
- HttpResponseMessage
- 自定义类型
依据不同返回类型，WebApi会选择不同的机制来创建Http Reponse
返回类型 | 响应 |
void | Return empty 204 (No Content) 返回无内容 |
HttpResponseMessage | Convert directly to an HTTP response message. 直接转换为一个Http Reponse消息。 |
IHttpActionResult | Call ExecuteAsync to create an HttpResponseMessage, then convert to an HTTP response message. 调用ExecuteAsync先创建一个HttpReponseMessage，在转换为Http Reponse输出。 |
其它类型 | Write the serialized return value into the response body; return 200 (OK). 序列化后的信息返回到消息体中。 |
本章内容就围绕这四块分别来看看它们的使用。
3.1.1 void无返回值
使用void关键字申明方法没有返回值。它的使用也很简单，我们来看一个示例。
public class ORDER { public string ID { get; set; } public string NO { get; set; } public string NAME { get; set; } }
public class OrderController : ApiController { [HttpPost] public void SaveOrder(ORDER name) { //处理业务逻辑 } }
$(function () { $.ajax({ type: 'post', url: 'http://localhost:21528/api/Order/SaveOrder', data: { ID: "aaa", NAME: "test" }, success: function (data, status) { alert(data); } }); }); |
运行结果如下：
可以看到，使用void申明的方法，在success方法里面得不到返回值，并且会返回http状态码204，告诉客户端此请求没有返回值。
3.1.2 IHttpActionResult
IHttpActionResult类型是WebApi里面非常重要的一种返回值类型。下面是这种类型的返回值的一些常见用法。
- Json<T>(T content)
在WebApi的ApiController这个抽象类里面，为我们封装了Json<T>(T content)这个方法，它的用法和MVC里面的JsonResult基本类似。我们通过一个例子来说明它的用法：
[HttpGet] public IHttpActionResult GetOrder() { var lstRes = new List<ORDER>(); lstRes.Add(new ORDER() { ID = "aaaa", NO = "111", NAME = "111" }); lstRes.Add(new ORDER() { ID = "bbbb", NO = "222", NAME = "222" }); return Json (lstRes); } |
Json( )方法的返回类型JsonResult<T>，实现了IHttpActionResult接口。
使用Ajax请求来调用该方法。
$(function () { $.ajax({ type: 'get', url: 'http://localhost:21528/api/Order/GetOrder', data: {}, success: function (data, status) { alert(data); } }); }); |
运行结果如下：
2. Ok()、 Ok<T>(T content)
Ok( )方法的定义如下：
protected internal virtual OkResult Ok();
例如：
[HttpGet] public IHttpActionResult GetOKResult() { return Ok(); } |
结果如下：
如果返回Ok()，就表示不向客户端返回任何信息，只告诉客户端请求成功。
除了Ok()之外，还有另外一个重载Ok<T>(T content)。如下：
[HttpGet] public IHttpActionResult GetOKResult(string name) { return Ok<string>(name); } |
结果如下：
Ok( )用法和Json<T>(T content)比较类似，如果你非要问这两者有什么区别，或者说怎么选择两者。如果是返回实体或者实体集合，建议使用Json<T>(T content)，如果是返回基础类型（如int、string等），使用Ok<T>(T content)。
3. NotFound()
当需要向客户端返回找不到记录时，有时需要用到NotFound()方法。声明如下：
protected internal virtual NotFoundResult NotFound();
用法如下：
[HttpGet] public IHttpActionResult GetNotFoundResult(string id) { var lstRes = new List<ORDER>(); //实际项目中，通过后台取到集合赋值给lstRes变量。这里只是测试。 lstRes.Add(new ORDER() { ID = "aaaa", NO = "111", NAME = "111"}); lstRes.Add(new ORDER() { ID = "bbbb", NO = "222", NAME = "222"}); var oFind = lstRes.FirstOrDefault(x => x.ID == id) ; if (oFind == null) { return NotFound(); } else { return Json<ORDER>(oFind); } } |
NotFound()方法会返回一个404的错误到客户端。
4. Content<T>（）
[HttpGet] public IHttpActionResult GetContentResult() { return Content<string>(HttpStatusCode.OK, "OK"); } |
向客户端返回值和http状态码。
5. BadRequest()
[HttpGet] public IHttpActionResult GetBadRequest(ORDER order) { if (string.IsNullOrEmpty(order.ID)) return BadRequest(); return Ok(); } |
向客户端返回400的http错误。
6. Redirect(string location)
[HttpGet] public IHttpActionResult RedirectResult() { return Redirect("http://localhost:21528/api/Order/GetContentResult"); } |
将请求重定向到其他地方。
7. 自定义IHttpActionResult
上面介绍了一些系统内置的常用的实现IHttpActionResult接口的方法。如果我们需要自定义IHttpActionResult的返回呢？
在介绍之前，我们有必要先来看看IHttpActionResult类型的定义，将IHttpActionResult转到定义可以看到：
namespace System.Web.Http
{
public interface IHttpActionResult
{
Task<System.Net.Http.HttpResponseMessage> ExecuteAsync(CancellationToken cancellationToken);
}
}
这个接口包含唯一的一个方法ExecuteAsync()，此方法将以异步方式创建一个HttpResponseMessage实例返回给客户端。
有了这个作为基础，下面，我们自定义一个bootstrapTable服务端分页的子类去展示自定义IHttpActionResult的用法。
首先，自定义一个实现类。
public class PageResult : IHttpActionResult { object _value; HttpRequestMessage _request;
public PageResult(object value, HttpRequestMessage request) { _value = value; _request = request; }
public Task<HttpResponseMessage> ExecuteAsync(System.Threading.CancellationToken cancellationToken) { var response = new HttpResponseMessage() { Content = new ObjectContent(typeof(object), _value, new JsonMediaTypeFormatter()), RequestMessage = _request }; return Task.FromResult(response); } } |
然后，在API接口里面返回PageResult对象。
[HttpGet] public IHttpActionResult GetPageRow(int limit, int offset) { var lstRes = new List<ORDER>();
lstRes.Add(new ORDER() { ID = "aaaa", NO = "111", NAME = "111" }); lstRes.Add(new ORDER() { ID = "bbbb", NO = "222", NAME = "222" });
var oData = new { total = lstRes.Count, rows = lstRes.Skip(offset).Take(limit).ToList() }; return new PageResult(oData, Request); } |
3.1.3 HttpResponseMessage
在上文自定义IHttpActionResult返回类型的时候，提到过HttpResponseMessage这个对象。它表示向客户端返回一个http响应的消息对象（包含http状态码和需要返回客户端的消息）。这个对象也有它独特的使用场景：需要向客户端返回HttpResponse时就要用到这个对象。以导出为例，由于需要将导出的Excel文件输出到客户端浏览器，Webapi的服务端需要向Web的客户端输出文件流，这个时候一般的IHttpActionResult对象不方便解决这个问题，于是HttpReponseMessage派上了用场。我们来看看它的使用示例。
public HttpResponseMessage Export() { //取数据 var lstRes = OrderBLL.Export();
//向Excel里面填充数据 HSSFWorkbook workbook = new HSSFWorkbook(); CreateAndFillSheet(workbook, lstRes);
//保存到服务 var fileName = "Excel" + DateTime.Now.ToString("yyyyMMddHHmmss") + ".xls"; var strPath = Path.Combine(AppDomain.CurrentDomain.BaseDirectory, @"Data\" + fileName); using (FileStream fs = new FileStream(strPath, FileMode.Create)) { workbook.Write(fs); using (MemoryStream ms = new MemoryStream()) { workbook.Write(ms); } }
//输出到浏览器 try { var stream = new FileStream(strPath, FileMode.Open); HttpResponseMessage response = new HttpResponseMessage(HttpStatusCode.OK); response.Content = new StreamContent(stream); response.Content.Headers.ContentType = new MediaTypeHeaderValue("application/octet-stream"); response.Content.Headers.ContentDisposition = new ContentDispositionHeaderValue("attachment") { FileName = fileName };
return response; } catch { return new HttpResponseMessage(HttpStatusCode.NoContent); } } |
将文件流保存在StreamContent对象里面，然后输出到浏览器。在浏览器端即可将Excel输出。
3.1.4 自定义类型
以上几种返回值类型能解决我们大部分返回值的问题，当然，你也可以将webapi的接口和普通方法一样，返回任意的类型，WebApi会自动序列化你自定义任何返回类型，然后将序列化的值写到响应正文里，状态码统一返回200。比如：
[HttpGet] public object GetOther() { var lstRes = new List<ORDER>(); lstRes.Add(new ORDER() { ID = "aaaa", NO = "111", NAME = "111"}); lstRes.Add(new ORDER() { ID = "bbbb", NO = "222", NAME = "222"});
return lstRes; } |
和上面的Json、Ok等用法在效果上面没有太大区别。
以上详细分析了下WebApi里面返回值的常见用法，不能说哪种方式最好，因为每种方式都有其特定的使用场景。为了规范WebApi接口，对于一般接口的返回值，尽量使用IHttpActionResult类型作为返回值，毕竟是微软内置的东西，可能为我们考虑了很多我们考虑不到的东西。
3.2 内容协商
HTTP规范（RFC 2616）将内容协商定义为"在有多个表现可用时，为一个给定的响应选择最佳表现的过程"。在HTTP中内容协商的主要机制是以下请求报头：
Accept：响应可接收的媒体类型，如"application/json"、"application/xml"，或者自定义媒体类型，如"application/vnd.example+xml"。
Accept-Charset：可接收的字符集，如"UTF-8"或"ISO 8859-1"。
Accept-Encoding：可接收的内容编码，如"gzip"。
Accept-Language：优先选用的自然语言，如"en-us"。
服务器也可以查看HTTP请求的其它选项。例如，如果该请求含有一个X-Requested-With报头，它指示这是一个AJAX请求，在没有Accept报头的情况下，服务器可能会默认使用JSON。
3.2.1 序列化
如果Web API控制器返回一个CLR类型的响应，（请求处理）管线会对返回值进行序列化，并将其写入HTTP响应体。
例如，下面控制器动作：
public Product GetProduct(int id)
{
var item = _products.FirstOrDefault(p => p.ID == id);
if (item == null)
{
throw new HttpResponseException(HttpStatusCode.NotFound);
}
return item;
}
客户端可能会发送这样的HTTP请求：
GET http://localhost.:21069/api/products/1 HTTP/1.1 Host: localhost.:21069 Accept: application/json, text/javascript, */*; q=0.01 |
服务器可能会发送以下响应：
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 Content-Length: 57 Connection: Close {"Id":1,"Name":"Gizmo","Category":"Widgets","Price":1.99} |
在这个例子中，客户端请求（指定）了JSON、Javascript、或"任意格式（*/*）"。服务器以一个Product对象的JSON表示作出了响应。注意，响应中的Content-Type报头已被设置成"application/json"。
控制器也可以返回一个HttpResponseMessage对象。为了指定响应体的CLR对象，要调用CreateResponse扩展方法：
public HttpResponseMessage GetProduct(int id)
{
var item = _products.FirstOrDefault(p => p.ID == id);
if (item == null)
{
throw new HttpResponseException(HttpStatusCode.NotFound);
}
return Request.CreateResponse(HttpStatusCode.OK, product);
}
该选项让你能够对响应细节进行更多的控制。你可以设置状态码、添加HTTP报头等等。
对资源进行序列化的对象叫做媒体格式化器。媒体格式化器派生于MediaTypeFormatter类。Web API提供了XML和JSON的媒体格式化器，你也可以创建自定义的格式化器，以支持其它媒体类型。
3.2.2 内容协商的工作机制
内容协商的工作过程可以分为三步：
第一步： 管道从HttpConfiguration对象获取IContentNegotiator服务 。
第二步： 从HttpConfiguration.Formatters集合中获取媒体格式化器列表 。
第三步： 管道调用IContentNegotiatior.Negotiate（type,request,famatters）
参数是：要序列化的对象类型，Request对象，媒体格式化器的集合
返回结果：选用的格式化器，相应的媒体类型
Web API检测Request中Accept,Accept中有多种类型，从左到右，品质因子从高到低（默认q=1.0）并且同时尝试通过从格式化器列表中去找到一个匹配并且支持的媒体类。
Accept: text/html,application/xhtml+xml,application/xml;q=0.9, image/apng,*/*;q=0.8
很多情况下Request的Accept如上所示，如果Xml Formmatter存在，application/xml与Xml Formatter匹配上了，所以会以XML格式进行输出并返回。如果未找到格式化器，则Negotiate方法返回null，并且客户端接收HTTP错误406（不可接受）。
以下代码展示了控制器如何才能够直接调用内容协商：
public HttpResponseMessage GetProduct(int id) { var product = new Product() { Id = id, Name = "Gizmo", Category = "Widgets", Price = 1.99M };
//获取IContentNegotiator的服务实例 IContentNegotiator negotiator = this.Configuration.Services.GetContentNegotiator();
//Negotiate返会媒体类型和选择的formatter ContentNegotiationResult result = negotiator.Negotiate(typeof(Product), this.Request, this.Configuration.Formatters); if (result == null) { var response = new HttpResponseMessage(HttpStatusCode.NotAcceptable); throw new HttpResponseException(response)); }
return new HttpResponseMessage() { Content = new ObjectContent<Product>( product, // 序列化的对象 result.Formatter, // 采用的formmter result.MediaType.MediaType // 媒体类型 ) }; } |
上述代码等价于管线的自动完成。
