Web API 2中的Action Results

[译]Action Results in Web API 2

单击此处查看原文

本文阐述了ASP.NET Web API是如何将controller action的返回值转换为HTTP response message的。

一个Web API controller action可以有以下几种返回值：

1. void
2. HttpResponseMessage
3. IHttpActionResult
4. Some other type（其他）

根据以上四种返回类型的不同，Web API会使用不同的机制创建HTTP response。

返回类型	创建方式
void	无内容
HttpResponseMessage	直接转换为Http response message
IHttpActionResult	调用ExecuteAsync来创建一个HttpResponseMessage，然后转换为Http response message
Other Type	将序列化的返回值写入response body；返回 状态码200（OK）

本文的其余部分将阐述以上四种情况的详细内容。

void

如果返回类型是void，Web API会直接返回一个空的HTTP response，状态码：200，表示无内容。

示例controller:

public class ValuesController : ApiController
{
    public void Post()
    {
    }
}

HTTP response:

HTTP/1.1 204 No Content
Server: Microsoft-IIS/8.0
Date: Mon, 27 Jan 2014 02:13:26 GMT

HttpResponseMessage

如果action返回了一个HttpResponseMessage，Web API会将该返回值转换为一个HTTP response message，使用HttpResponseMessage对象的属性来填充这个HTTP response message。

下面的示例代码中对一个response message 进行了大量的控制。比如：它设置了Cache-Control header。

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

如果你通过使用一个domain model（领域模型）来使用CreateResponse方法，Web API使用media formatter来将序列化的模型写入response body。

public HttpResponseMessage Get()
{
    // Get a list of products from a database.
    IEnumerable<Product> products = GetProductsFromDB();

    // Write the list to the response body.
    HttpResponseMessage response = Request.CreateResponse(HttpStatusCode.OK, products);
    return response;
}

Web API在请求中使用Accept header来选择formatter。更多详情，参见Content Negotiation。

IHttpActionResult

IHttpActionResult接口在Web API 2中有过相关介绍。它主要定义了一个**HttpResponseMessage **factory。使用此接口有以下的几点优势：

• 简化了你对controllers进行的unit test
• 将创建Http responses的通用逻辑分离到独立的类中
• 通过隐藏构建response的底层实现细节，使得controller action的功能简介明了

IHttpActionResult声明了一个方法：ExecuteAsync，用于异步创建HttpResponseMessage实例。

public interface IHttpActionResult
{
    Task<HttpResponseMessage> ExecuteAsync(CancellationToken cancellationToken);
}

如果一个controller action返回一个IHttpActionResult，Web API 将调用ExecuteAsync方法来创建一个HttpResponseMessage。然后它再将HttpResponseMessage转换为一个HTTP response message。
以下是一个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);
    }
}

controller action:

public class ValuesController : ApiController
{
    public IHttpActionResult Get()
    {
        return new TextResult("hello", Request);
    }
}

response:

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的实现写在System.Web.Http.Results命名空间下。因为ApiController定义的helper method会返回这些内置的action results。

下面的示例中，如果一个请求没有匹配到现有的product ID，这个controller将调用ApiController.NotFound来创建一个404（Not Found） response。否则，controller将调用ApiController.OK，来创建一个200（OK） response，它包含了product信息。

public IHttpActionResult Get (int id)
{
    Product product = _repository.Get (id);
    if (product == null)
    {
        return NotFound(); // Returns a NotFoundResult
    }
    return Ok(product);  // Returns an OkNegotiatedContentResult
}

Other Return Type

如果返回类型是其他任何的一种形式，Web API使用了一个media formatter来序列化这些返回值，然后将这些序列化的值写入response body。这个response status code是200（ok）。

public class ProductsController : ApiController
{
    public IEnumerable<Product> Get()
    {
        return GetAllProductsFromDB();
    }
}

使用这种方法的缺点是，你无法直接返回一个error code，比如404。不过你可以抛出一个HttpResponseException异常来替代error code。更多详情，参见Exception Handling in ASP.NET Web API。

Web API在请求中使用Accept header来选择formatter。更多详情，参见Content Negotiation。

示例请求：

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}]