Web API 2 的操作结果
这是msdn原文文档!明天用,留存。
Web API 控制器操作可以返回以下任何内容:
- void
- HttpResponseMessage
- IHttpActionResult
- 其他类型
根据返回的这种情况,Web API 将使用不同的机制来创建 HTTP 响应。
返回类型
Web API 如何创建响应
void | 返回空的204(无内容) |
HttpResponseMessage | 直接转换为 HTTP 响应消息。 |
IHttpActionResult | 调用ExecuteAsync创建HttpResponseMessage,然后将其转换为 HTTP 响应消息。 |
其他类型 | 将序列化的返回值写入响应正文;返回200(OK)。 |
void
如果返回类型为void
,Web API 只会返回一个空 HTTP 响应,状态代码为204(无内容)。
public class ValuesController : ApiController { public void Post() { } }
Http相应:
HTTP/1.1 204 No Content Server: Microsoft-IIS/8.0 Date: Mon, 27 Jan 2014 02:13:26 GMT
HttpResponseMessage
如果操作返回HttpResponseMessage,Web API 会将返回值直接转换为 HTTP 响应消息,并使用HttpResponseMessage对象的属性来填充响应。
此选项提供了对响应消息的大量控制。 例如,以下控制器操作设置缓存控制标头。
public class ValuesController : ApiController { public HttpResponseMessage Get() { HttpResponseMessage response = Request.CreateResponse(HttpStatusCode.OK, "value"); response.Content = new StringContent("hello", Encoding.Unicode); response.Headers.CacheControl = new CacheControlHeaderValue() { MaxAge = TimeSpan.FromMinutes(20) }; return response; } }
响应:
HTTP/1.1 200 OK Cache-Control: max-age=1200 Content-Length: 10 Content-Type: text/plain; charset=utf-16 Server: Microsoft-IIS/8.0 Date: Mon, 27 Jan 2014 08:53:35 GMT hello
IHttpActionResult
Web API 2 中引入了IHttpActionResult接口。 实质上,它定义了HttpResponseMessage工厂。 下面是使用IHttpActionResult接口的一些优点:
- 简化控制器的单元测试。
- 将用于创建 HTTP 响应的公共逻辑移到单独的类中。
- 通过隐藏构造响应的低级别细节,使控制器操作的意图更清晰。
IHttpActionResult包含单一方法ExecuteAsync,它以异步方式创建HttpResponseMessage实例。
public interface IHttpActionResult { Task<HttpResponseMessage> ExecuteAsync(CancellationToken cancellationToken); }
如果控制器操作返回IHttpActionResult,Web API 将调用ExecuteAsync方法来创建HttpResponseMessage。 然后,将HttpResponseMessage转换为 HTTP 响应消息。
下面是创建纯文本响应的IHttpActionResult的简单实现:
public class TextResult : IHttpActionResult { string _value; HttpRequestMessage _request; public TextResult(string value, HttpRequestMessage request) { _value = value; _request = request; } public Task<HttpResponseMessage> ExecuteAsync(CancellationToken cancellationToken) { var response = new HttpResponseMessage() { Content = new StringContent(_value), RequestMessage = _request }; return Task.FromResult(response); } }
示例控制器操作:
public class ValuesController : ApiController { public IHttpActionResult Get() { return new TextResult("hello", Request); } }
响应:
HTTP/1.1 200 OK Content-Length: 5 Content-Type: text/plain; charset=utf-8 Server: Microsoft-IIS/8.0 Date: Mon, 27 Jan 2014 08:53:35 GMT hello
更频繁地使用在 IHttpActionResult 命名空间中定义的 实现。 ApiController类定义返回这些内置操作结果的帮助器方法。
在以下示例中,如果请求与现有产品 ID 不匹配,则控制器将调用ApiController来创建404(未找到)响应。 否则,控制器将调用ApiController,这将创建一个包含该产品的200(OK)响应。
public IHttpActionResult Get (int id) { Product product = _repository.Get (id); if (product == null) { return NotFound(); // Returns a NotFoundResult } return Ok(product); // Returns an OkNegotiatedContentResult }
其他返回类型
对于所有其他返回类型,Web API 使用媒体格式化程序来序列化返回值。 Web API 将序列化的值写入响应正文。 响应状态代码为200(正常)。
public class ProductsController : ApiController { public IEnumerable<Product> Get() { return GetAllProductsFromDB(); } }
这种方法的缺点是,您不能直接返回错误代码,如404。 但是,可以针对错误代码引发带有 httpresponseexception 。 有关详细信息,请参阅中的异常处理 ASP.NET Web API。
Web API 使用请求中的 Accept 标头来选择格式化程序。 有关详细信息,请参阅内容协商。
示例请求:
GET http://localhost/api/products HTTP/1.1 User-Agent: Fiddler Host: localhost:24127 Accept: application/json
示例响应:
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 Server: Microsoft-IIS/8.0 Date: Mon, 27 Jan 2014 08:53:35 GMT Content-Length: 56 [{"Id":1,"Name":"Yo-yo","Category":"Toys","Price":6.95}]
临时保存,这是msdn的文档原文!