ASP.NET Web API 2：Action的返回类型

Web API控制器中的Action方法有如下几种返回类型：

1. void
2. HttpResponseMessage
3. IHttpActionResult
4. 其它类型

基于上面几种不同的返回类型，Web API创建HTTP响应消息的机制也不同。

返回类型	Web API创建HTTP响应消息的机制
void	返回HTTP状态码204(无内容)
HttpResponseMessage	直接转换成HTTP响应消息
IHttpActionResult	调用接口的ExecuteAsync方法创建一个HttpResponseMessage对象，然后转换成HTTP响应消息
其它类型	把序列化后的返回值写入响应正文，并且返回HTTP状态码200(OK)

下面详细介绍几种返回类型

void

如果返回类型是void， Web API 会返回一个HTTP状态码204(无内容)的空HTTP响应消息

示例代码：

    public class ReturnValueDemoController : ApiController
    {
          //返回类型为void
          public void Get()
        {
        }
    }

HTTP响应消息：

HTTP/1.1  No Content
Cache-Control: no-cache
Pragma: no-cache
Expires: -
Server: Microsoft-IIS/8.0
X-AspNet-Version: 4.0.
X-SourceFiles: =?UTF-?B?RTpcV29ya1NwYWNlXERvdE5ldFxNdmNEZW1vXE12Y0RlbW8uV2ViVUlcYXBpXFJldHVyblZhbHVlRGVtbw==?=
X-Powered-By: ASP.NET
Date: Wed,  Mar  :: GMT

HttpResponseMessage

如果返回类型是HttpResponseMessage ，Web API直接把返回值转换成HTTP响应消息，HttpResponseMessage对象的属性对应响应消息的属性。你可以灵活的设置响应标头和响应正文，这就给了你对响应消息的更大的控制权。如下例：

 public class ReturnValueDemoController : ApiController
    {
        //返回类型为HttpResponseMessage
        public HttpResponseMessage Get()
        {
            HttpResponseMessage response = Request.CreateResponse(HttpStatusCode .OK, "hello");
            response.Content = new StringContent ( "hello wep api", Encoding .Unicode);
            response.Headers.CacheControl = new CacheControlHeaderValue
            {
                MaxAge = TimeSpan .FromSeconds()
            };
            return response;
        }
    } 

响应：

HTTP/1.1  OK
Cache-Control: max-age=
Content-Type: text/plain; charset=utf-
Vary: Accept-Encoding
Server: Microsoft-IIS/8.0
X-AspNet-Version: 4.0.
X-SourceFiles: =?UTF-?B?RTpcV29ya1NwYWNlXERvdE5ldFxNdmNEZW1vXE12Y0RlbW8uV2ViVUlcYXBpXFJldHVyblZhbHVlRGVtbw==?=
X-Powered-By: ASP.NET
Date: Wed,  Mar  :: GMT
Content-Length: 

hello wep api

如果你给CreateResponse方法传入了一个领域模型， Web API就会把序列化后的领域模型写入响应正文。

示例：

    public HttpResponseMessage Get()
        {
            IQueryable <Product > products = repository.GetProducts();
            HttpResponseMessage response = Request.CreateResponse(HttpStatusCode .OK, products);
            return response;
        }

响应：

HTTP/1.1  OK
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json; charset=utf-
Expires: -
Server: Microsoft-IIS/8.0
X-AspNet-Version: 4.0.
X-SourceFiles: =?UTF-?B?RTpcV29ya1NwYWNlXERvdE5ldFxNdmNEZW1vXE12Y0RlbW8uV2ViVUlcYXBpXFJldHVyblZhbHVlRGVtbw==?=
X-Powered-By: ASP.NET
Date: Wed,  Mar  :: GMT
Content-Length: 

[{"ProductId":,"Name":" 苹果","Description":null,"Price":1.0,"Category":"水果"},{"ProductId":,"Name":"鼠标","Description":null,"Price":50.0,"Category":"电脑配件"},{"ProductId":,"Name":"洗发水","Description":null,"Price":20.0,"Category":"日用品"}]

IHttpActionResult

IHttpActionResult接口是在Web API 2才引入进来的，本质上，它定义了一个HttpResponseMessage工厂类。IHttpActionResult接口只定义了一个ExecuteAsync方法，该方法异步方式创建一个HttpResponseMessage实例。

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

如果控制器的Action返回类型是IHttpActionResult，Web API就会调用接口的ExecuteAsync方法创建一个HttpResponseMessage对象，然后转换成HTTP响应消息。以下是一个IHttpActionResult接口的实现，它创建了一个普通文本响应消息。

public class PlainTextResult : IHttpActionResult
    {
        private string text;
        private HttpRequestMessage request;

        public PlainTextResult(string text, HttpRequestMessage request)
        {
            this .text = text;
            this .request = request;
        }
        public Task < HttpResponseMessage> ExecuteAsync(CancellationToken cancellationToken)
        {
            HttpResponseMessage response=new HttpResponseMessage
            {
                Content = new StringContent (text, Encoding.Unicode),
                RequestMessage = request
            };
            return Task .FromResult(response);
        }
    }

控制器Action代码：

//返回类型是IHttpActionResult
        public IHttpActionResult Get()
        {
            return new PlainTextResult( "plain text result" ,Request);
        }

响应：

HTTP/1.1  OK
Cache-Control: no-cache
Pragma: no-cache
Content-Type: text/plain; charset=utf-
Expires: -
Vary: Accept-Encoding
Server: Microsoft-IIS/8.0
X-AspNet-Version: 4.0.
X-SourceFiles: =?UTF-?B?RTpcV29ya1NwYWNlXERvdE5ldFxNdmNEZW1vXE12Y0RlbW8uV2ViVUlcYXBpXFJldHVyblZhbHVlRGVtbw==?=
X-Powered-By: ASP.NET
Date: Wed,  Mar  :: GMT
Content-Length: 

plain text result

通常情况下，你无须自己去实现IHttpActionResult接口， 在System.Web.Http.Results命名空间下已经包含了很多实现该接口的Action返回类型。ApiContoller类也定义了很多方法获取这些内置的Action返回类型。

在下面的例子里，如果没有找到某个产品，控制器调用ApiController.NotFound方法创建一个404 (Not Found)的响应消息。

HTTP/1.1  Not Found
Cache-Control: no-cache
Pragma: no-cache
Expires: -
Server: Microsoft-IIS/8.0
X-AspNet-Version: 4.0.
X-SourceFiles: =?UTF-?B?RTpcV29ya1NwYWNlXERvdE5ldFxNdmNEZW1vXE12Y0RlbW8uV2ViVUlcYXBpXFJldHVyblZhbHVlRGVtb1w1?=
X-Powered-By: ASP.NET
Date: Wed,  Mar  :: GMT
Content-Length: 

如果找到了，控制器调用ApiController.OK方法创建一个HTTP状态码200(OK)响应正文是产品信息的响应消息。

HTTP/1.1  OK
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json; charset=utf-
Expires: -
Server: Microsoft-IIS/8.0
X-AspNet-Version: 4.0.
X-SourceFiles: =?UTF-?B?RTpcV29ya1NwYWNlXERvdE5ldFxNdmNEZW1vXE12Y0RlbW8uV2ViVUlcYXBpXFJldHVyblZhbHVlRGVtb1wx?=
X-Powered-By: ASP.NET
Date: Wed,  Mar  :: GMT
Content-Length: 

{"ProductId":,"Name":" 苹果","Description":null,"Price":1.0,"Category":"水果"}

其它返回类型

对于其它的返回类型，Web API会对返回值序列化，然后把序列化后的返回值写入到响应正文里，并且响应状态码是200(OK)。   

public IQueryable < Product> GetpProducts()
        {
            return repository.GetProducts();
        } 

响应：

HTTP/1.1  OK
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json; charset=utf-
Expires: -
Server: Microsoft-IIS/8.0
X-AspNet-Version: 4.0.
X-SourceFiles: =?UTF-?B?RTpcV29ya1NwYWNlXERvdE5ldFxNdmNEZW1vXE12Y0RlbW8uV2ViVUlcYXBpXFJldHVyblZhbHVlRGVtb1w=?=
X-Powered-By: ASP.NET
Date: Wed,  Mar  :: GMT
Content-Length: 

[{"ProductId":,"Name":" 苹果","Description":null,"Price":1.0,"Category":"水果"},{"ProductId":,"Name":"鼠标","Description":null,"Price":50.0,"Category":"电脑配件"},{"ProductId":,"Name":"洗发水","Description":null,"Price":20.0,"Category":"日用品"}]

使用这种返回类型的一个缺点就是你不能直接返回一个错误代码，例如404。不过，你可以通过抛出HttpResponseException异常来解决这个问题。

public Product GetProductById( int id)
        {
            Product product = repository.GetProductById(id);
            if (product==null )
                throw new HttpResponseException ( HttpStatusCode.NotFound);

            return product;
        }