Web API-如何將Controller的返回值轉換成HTTP response消息

一個Web API 控制器方法能夠返回如下類型的值

1.void

2.HttpResponseMessage

3.IHttpActionResult

4.其它一些類型

根據action不一樣的返回類型，Web API 使用不一樣的處理方法去建立一個http響應信息。

Action返回類型	Web API 如何生成響應消息
void	返回空 204（No Content）
HttpResponseMessage	直接轉換成HTTP響應消息
IHttpActionResult	調用ExecuteAsync方法去建立一個HttpResponseMessage 對象，讓後將這個對象轉換成Http響應消息
其餘類型	將序列化的值寫到響應消息的內容中，返回200（OK）

下面對每一種返回類型作詳細說明

void

若是action返回void類型，Web API返回一個空HTTP響應消息，狀態碼爲：204（No Content）

例如：

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

執行此Action時，響應消息爲：

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響應消息，使用HttpResponseMessage對象的屬性值去填充響應消息。

返回HttpResponseMessage類型的方式給了咱們更多的控制響應消息的能力，例以下面的控制器 action實現了設置響應消息頭Cache-Control 的值

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

若是你傳遞一個model 對象（domain model）給CreateResponse方法，Web API將使用媒體格式（media formatter）序列化對象並將序列化後的內容寫入到響應主體內容中。

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 指定的格式選擇響應消息內容的格式，（內容協商的實現）

IHttpActionResult

IHttpActionResult 接口在Web API2中引入，本質上，它是一個HttpResponseMessage工廠（好比使用NotFound()能夠返回404響應，Ok(products)能夠返回一個 200響應並返回內容，這兩個方法返回的類型均實現了IHttpActionResult接口）。

使用IHttpActionResult 接口有如下幾個優點：

--簡化控制器的單元測試

--將建立HTTP響應的主要邏輯分離到不一樣的類中

--經過隱藏建立響應消息的底層細節，使控制器動做的意圖更加清晰。

IHttpActionResult 只包含一個方法，ExecuteAsync，這個方法可以異步的建立一個HttpResponseMessage對象。

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

若是一個控制器方法返回一個IHttpActionResult類型對象，Web API調用ExecuteAsync方法去建立一個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接口的實現類定義在System.Web.Http.Results命名空間下，The ApiContoller class defines helper methods that return these built-in action results.（APIController 類定義了返回（這些內建的action返回類型）幫助信息的方法。

在下面的例子中：若是找不到請求的id所對應的產品，控制器則調用APIController.NotFound 去建立一個404（Not Found）響應消息，不然控制器調用APIController.OK，建立一個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
}

其餘的返回類型

對應其餘的action返回類型，Web API使用媒體格式（media formatter）序列化返回值，Web API將序列化的值寫入肖響應消息的主體中，響應狀態代碼爲200（OK）

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

上面Action返回一個列表類型，若是請求消息中沒有指定 Accept頭部信息（要求響應消息內容的類型），則會將列表對象序列化成json（默認）返回給瀏覽器。

返回其餘類型的方式，一個缺點就是不能直接返回一個響應錯誤代碼，好比404，固然，能夠經過拋出一個HttpResponseException異常來返回響應錯誤代碼，更多信息可查看（Exception Handling in ASP.NET Web API.）

Web API 使用請求消息中 Accept 頭部值指定的格式來決定響應消息返回的內容格式（即內容協商方式）

好比：使用Chrome的postman插件

指定請求頭部 Accept 值 爲：application/xml 則返回xml類型數據。

指定請求頭部 Accept 值 爲：application/json 則返回json類型數據。