C#进阶系列——WebApi 接口返回值不困惑：返回值类型详解

时间 2019-12-08

标签 c# 进阶系列 webapi 接口返回困惑类型详解栏目 C# 繁體版

原文原文链接

使用过Webapi的园友应该都知道，Webapi的接口返回值主要有四种类型前端

void无返回值
IHttpActionResult
HttpResponseMessage
自定义类型

此篇就围绕这四块分别来看看它们的使用。web

1、void无返回值

void关键字咱们都不陌生，它申明方法没有返回值。它的使用也很简单，咱们来看一个示例就能明白。ajax

　　 public class ORDER
    {
        public string ID { get; set; }

        public string NO { get; set; }

        public string NAME { get; set; }

        public string DESC { get; set; }
    }

　　 public class OrderController : ApiController
    {
        [HttpPost]
        public void SaveOrder(ORDER name)
        { 
            //处理业务逻辑

        }
    }

在Web里面调用bootstrap

按 Ctrl+C 复制代码

获得结果api

能够看到，使用void申明的方法，在success方法里面得不到返回值，而且会返回http状态码204，告诉客户端此请求没有返回值。浏览器

2、IHttpActionResult

IHttpActionResult类型是WebApi里面很是重要的一种返回值类型。下面博主就根据平时在项目里面使用最多的几种方式来说解下这种类型的返回值的一些用法。app

一、Json<T>(T content)

使用MVC开发过的朋友必定记得，在MVC里面，请求数据的接口的返回值类型大部分使用的是JsonResult，在MVC里面你必定也写过相似这样的接口：异步

　　　　 public JsonResult GetResult()
        {
            return Json(new { }, JsonRequestBehavior.AllowGet);
        }

那么，在WebAPI里面是否也存在相似的用法呢。呵呵，在这点上面，微软老是贴心的。在WebApi的ApiController这个抽象类里面，为咱们封装了Json<T>(T content)这个方法，它的用法和MVC里面的JsonResult基本相似。咱们经过一个例子来讲明它的用法：async

　　　　 [HttpGet]
        public IHttpActionResult GetOrder()
        {
            var lstRes = new List<ORDER>(); 

            //实际项目中，经过后台取到集合赋值给lstRes变量。这里只是测试。
            lstRes.Add(new ORDER() { ID = "aaaa", NO = "111", NAME = "111", DESC = "1111" });
            lstRes.Add(new ORDER() { ID = "bbbb", NO = "222", NAME = "222", DESC = "2222" });

            return Json<List<ORDER>>(lstRes);
        }

看到这个代码，有人就疑惑了，咱们定义的返回值类型是IHttpActionResult类型，直接返回Json<T>(T content)这样可行么？咱们将Json转到定义看看：学习

        protected internal JsonResult<T> Json<T>(T content);

咱们继续将JsonResult<T>转到定义

原来JsonResult<T>是实现了IHttpActionResult接口的，难怪能够直接返回呢。

知道了这个，咱们直接在Web里面经过ajax请求来调用：

$(function () {
    $.ajax({
        type: 'get',
        url: 'http://localhost:21528/api/Order/GetOrder',
        data: {},
        success: function (data, status) {
            alert(data);
        }
    });
});

来看结果：

既然实体类能够直接这样传递，那么若是咱们想要传递一些匿名类型呢，由于不少状况下，咱们须要返回到前端的对象都没有对应的实体来对应，若是咱们想要返回匿名对象怎么办呢？咱们知道，这里的Json<T>(T content)必需要传一个对应的泛型类型，若是是匿名类型这里确定很差传。还好有咱们的object类型，固然你可使用dynamic，咱们来试一把。

        [HttpGet]
        public IHttpActionResult GetOrder()
        {
          
            return Json<dynamic>(new { AA = "", BB = "cc" });
        }

一样的来看测试结果：

二、Ok()、 Ok<T>(T content)

除了Json<T>(T content)，在ApiController里面还有另一个比较经常使用的方法：Ok()。一样，咱们将Ok()转到定义

protected internal virtual OkResult Ok();

OkResult转到定义

有了这个做为基础，咱们就能够放心大胆的使用了。

        [HttpGet]
        public IHttpActionResult GetOKResult()
        {
            return Ok();
        }

获得结果

若是返回Ok()，就表示不向客户端返回任何信息，只告诉客户端请求成功。

除了Ok()以外，还有另一个重载Ok<T>(T content)。

        [HttpGet]
        public IHttpActionResult GetOKResult(string name)
        {
            return Ok<string>(name);
        }

这种用法和Json<T>(T content)比较相似，若是你非要问这二者有什么区别，或者说怎么选择二者。那么个人理解是若是是返回实体或者实体集合，建议使用Json<T>(T content)，若是是返回基础类型（如int、string等），使用Ok<T>(T content)。

三、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", DESC = "1111" });
            lstRes.Add(new ORDER() { ID = "bbbb", NO = "222", NAME = "222", DESC = "2222" });
            var oFind = lstRes.FirstOrDefault(x => x.ID == id) ;
            if (oFind == null)
            {
                return NotFound();
            }
            else
            {
                return Json<ORDER>(oFind);
            }
        }

$(function () {
    $.ajax({
        type: 'get',
        url: 'http://localhost:21528/api/Order/GetNotFoundResult',
        data: { id :"cccc" },
        success: function (data, status) {
            alert(data);
        }
    });
});

获得结果

NotFound()方法会返回一个404的错误到客户端。

四、其余

其余还有一些方法，都有它特定的用途。在此贴出来。

4.一、Content<T>(HttpStatusCode statusCode, T value)

        [HttpGet]
        public IHttpActionResult GetContentResult()
        {
            return Content<string>(HttpStatusCode.OK, "OK");
        }

向客户端返回值和http状态码。

4.二、BadRequest()

        [HttpGet]
        public IHttpActionResult GetBadRequest(ORDER order)
        {
            if (string.IsNullOrEmpty(order.ID))
                return BadRequest();
            return Ok();
        }

向客户端返回400的http错误。

4.三、Redirect(string location)

        [HttpGet]
        public IHttpActionResult RedirectResult()
        {
            return Redirect("http://localhost:21528/api/Order/GetContentResult");
        }

将请求重定向到其余地方。

五、自定义IHttpActionResult接口的实现

上面介绍了一些系统内置的经常使用的实现IHttpActionResult接口的方法。若是咱们须要自定义IHttpActionResult的返回呢？

在介绍以前，咱们有必要先来看看IHttpActionResult类型的定义，将IHttpActionResult转到定义能够看到：

namespace System.Web.Http
{
    // 摘要: 
    //     Defines a command that asynchronously creates an System.Net.Http.HttpResponseMessage.
    public interface IHttpActionResult
    {
        // 摘要: 
        //     Creates an System.Net.Http.HttpResponseMessage asynchronously.
        //
        // 参数: 
        //   cancellationToken:
        //     The token to monitor for cancellation requests.
        //
        // 返回结果: 
        //     A task that, when completed, contains the System.Net.Http.HttpResponseMessage.
        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变量。这里只是测试。
            lstRes.Add(new ORDER() { ID = "aaaa", NO = "111", NAME = "111", DESC = "1111" });
            lstRes.Add(new ORDER() { ID = "bbbb", NO = "222", NAME = "222", DESC = "2222" });

            var oData = new { total = lstRes.Count, rows = lstRes.Skip(offset).Take(limit).ToList() };
            return new PageResult(oData, Request);
        }

最好，ajax调用

$(function () {
    $.ajax({
        type: 'get',
        url: 'http://localhost:21528/api/Order/GetPageRow',
        data: { limit:1,offset:1},
        success: function (data, status) {
            alert(data);
        }
    });
});

获得结果

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输出。

4、自定义类型

以上几种返回值类型能解决咱们大部分返回值的问题，固然，你也能够将webapi的接口和普通方法同样，返回任意的类型，WebApi会自动序列化你自定义任何返回类型，而后将序列化的值写到响应正文里，状态码统一返回200。好比：

        [HttpGet]
        public object GetOther()
        {
            var lstRes = new List<ORDER>();

            //实际项目中，经过后台取到集合赋值给lstRes变量。这里只是测试。
            lstRes.Add(new ORDER() { ID = "aaaa", NO = "111", NAME = "111", DESC = "1111" });
            lstRes.Add(new ORDER() { ID = "bbbb", NO = "222", NAME = "222", DESC = "2222" });

            return lstRes;
        }

获得结果

和上面的Json、Ok等用法在效果上面没有太大区别。

5、总结

以上经过四个方面详细分享了下WebApi里面返回值的常见用法，不能说哪一种方式最好，由于每种方式都有其特定的使用场景。博主以为为了规范WebApi接口，对于通常接口的返回值，尽可能使用IHttpActionResult类型做为返回值，毕竟是微软内置的东西，可能为咱们考虑了不少咱们考虑不到的东西。固然，你可能会以为麻烦，你可能会说直接和普通方法同样来使用不是更爽，博主当初也有这种想法，但是学习微软的东西多了以后发现不少东西仍是遵照必定的标准比较好，至少维护起来方便。这就像博主最近正在努力学习的WebApi+oData同样，为何要搞这么一套标准性的东西，还不是为了更加方便地规范Restful风格。若是本文能帮到你，不妨推荐下，您的推荐是博主继续总结的动力！