asp.net core系列 38 WebAPI 返回类型与响应格式--必备

.NET Core 2020-08-07

一.返回类型

　　ASP.NET Core 提供以下 Web API Action方法返回类型选项，以及说明每种返回类型的最佳适用情况：

　　(1) 固定类型

　　(2) IActionResult

　　(3) ActionResult<T>

　　

　　1.1 固定类型

　　　　最简单的操作是返回基元或复杂数据类型（如 string 或自定义对象类型）。 请参考以下Action，该Action返回自定义 Product 对象的集合：

[HttpGet]
public IEnumerable<Product> Get()
{
    return _repository.GetProducts();
}

 　　　　适用场景：在执行Action期间，无需要根据条件判断返回不同类型，只返回固定类型即可满足要求。 上述操作不接受任何参数，因此不需要参数约束验证。

 

　　1.2  IActionResult类型

　　　　当Action方法中可能有多个 ActionResult 返回类型时，适合使用 IActionResult 返回类型。ActionResult 类型可以表示多种 HTTP 状态代码。 属于此类别的一些常见返回类型包括：BadRequestResult (400)、NotFoundResult (404) 和 OkObjectResult (200)。

　　　　由于Action方法中有多个返回类型和路径，因此必须使用 [ProducesResponseType] 特性。 此特性可针对 Swagger 等工具生成的 API 帮助页生成更多描述性响应详细信息(上篇有介绍)。 [ProducesResponseType] 指示Action将返回的已知类型和 HTTP 状态代码。

　　　　下面是一个同步Action，该Action方法中可能有两种返回类型：

[HttpGet("{id}")]
[ProducesResponseType(typeof(Product),StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public IActionResult GetById(int id)
{
    if (!_repository.TryGetProduct(id,out var product))
    {
        return NotFound();
    }

    return Ok(product);
}

 　　　　下面是一个异步Action，该Action方法中可能有两种返回类型：

[HttpPost]
[ProducesResponseType(typeof(Product),StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public async Task<IActionResult> CreateAsync([FromBody] Product product)
{
    if (product.Description.Contains("XYZ Widget"))
    {
        return BadRequest();
    }

    await _repository.AddProductAsync(product);

    return CreatedAtAction(nameof(GetById),new { id = product.Id },product);
}

 　　　　适用场景：当Action方法中可能有多个 ActionResult 返回类型时，适合使用 IActionResult 返回类型。

 

　　1.3 ActionResult<T>

 　　　　ASP.NET Core 2.1 引入了 ActionResult<T> 返回类型。 它支持返回从 ActionResult 派生的类型或返回固定类型。ActionResult<T> 提供以下优势：

 　　　　(1) 简化ProducesResponseType  例如：[ProducesResponseType(200,Type = typeof(Product))] 可简化为 [ProducesResponseType(200)]

　　　　 (2) 隐式强制转换运算符，将 T 转换为 ObjectResult，也就是将 return new ObjectResult(T); 简化为 return T;

　　　　下面是同步示例，(1)简化ProducesResponseType，(2)返回隐式转换。

[HttpGet("{id}")]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public ActionResult<Product> GetById(int id)
{
    if (!_repository.TryGetProduct(id,out var product))
    {
        return NotFound();
    }
   // return new ObjectResult(product);
    return product;
}

 　　　　下面是异步示例：

[HttpPost]
[ProducesResponseType(StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public async Task<ActionResult<Product>> CreateAsync(Product product)
{
    if (product.Description.Contains("XYZ Widget"))
    {
        return BadRequest();
    }

    await _repository.AddProductAsync(product);

    return CreatedAtAction(nameof(GetById),product);
}

 　　　　适用场景：对比IActionResult类型适用场景，它提供了二种优势。

　　　　最后建议：不要用特定类型返回。 对于有返回类型的使用ActionResult<T>,相反对于没有返回类型的使用IActionResult。 二者使用在“ asp.net core系列 36 WebAPI 搭建详细示例”中有介绍。

 

二.响应数据的格式化

　　响应数据是：response返回到客户端的数据。在ASP.NET Core MVC 中，包含对固定格式(json,xml,string..)或根据客户端规范(Accept)来设置响应数据格式的内置支持。默认返回json数据格式。

 

　　2.1 设置固定格式的action结果

　　　　对于返回固定格式，例如返回JsonResult 和 ContentResult。这样api向客户端始终返回固定的格式，不考虑客户端的Accept选项设置。JsonResult 始终返回josn数据格式,ContentResult始终返回纯文本数据格式。如果不需要Action返回固定数据格式，可以返回IActionResult ，这样可以有多种选择的数据格式。默认是json数据格式。

　　　　(1) 返回json格式的数据,使用fiddler请求url，返回客户端json格式数据，如下图：

        /// <summary>
        /// 返回固定的json格式字符串
        /// </summary>
        /// <returns></returns>
        [HttpGet("Get")]
        public JsonResult Get()
        {
            return Json(_context.TodoItems.ToList());
        }

分享图片

　　　　(2) 返回纯文本格式数据，使用fiddler请求url，返回客户端字符串，如下图

        /// <summary>
        /// 返回固定的字符串格式
        /// </summary>
        /// <returns></returns>
        [HttpGet("Message")]
        public ContentResult Message()
        {
            return Content("hello");
        }

分享图片

 

　　2.2 返回格式协商

 　　　　在公开的api的场景，请求方(客户端)在获取数据时，他们可能要求返回自己想要的数据格式。这样就不能使用固定的数据格式(一般也不推荐)。当客户端指定 Accept 标头时，就可以实现内容协商，对于内容协商返回数据格式由 ObjectResult 实现 。

 　　　　下面的案例中，返回IActionResult，返回的数据格式，由ObjectResult 来确定，默认是json数据格式。

        [HttpGet("{id}",Name = "GetTodoItem")]
        public async Task<ActionResult<TodoItem>> GetTodoItem(long id)
        {
            var todoItem = await _context.TodoItems.FindAsync(id);
            if (todoItem == null)
            {
                //返回状态码404，打包到了ObjectResult中
                return NotFound();
            }

            //返回实体，打包到了ObjectResult中
            return todoItem;
        }

　　　　客户端通过指定Accept: application/xml，希望返回xml数据格式，但还是json数据格式(见下图)。这是因为：

　　　　(1) 默认情况下，当框架检测到请求来自浏览器时，它将忽略 Accept 标头转而以应用程序的配置默认格式。

　　　　(2) 如果请求指定 XML，但是未配置 XML 格式化程序，那么将使用 JSON 格式化程序。

分享图片

　　　　如果应用程序要服从浏览器 accept 标头，可以将此配置为 MVC 配置的一部分，方法是在 Startup.cs 中以 ConfigureServices 方法将 RespectBrowserAcceptHeader 设置为 true，并设置以客户端格式优先。

            services.AddMvc(options =>
            {
                //优先客户端指定数据格式
                options.RespectBrowserAcceptHeader = true;
                //添加xml数据格式的输出
                options.OutputFormatters.Add(new XmlSerializerOutputFormatter());
            });

　　　　如下图所示，客户端指定Accept: application/xml，服务端就返回了xml数据格式，同样指定Accept: application/json ，服务端就返回json数据格式。

分享图片

　　　　

　　2.3 强制执行固定格式

　　　　如果需要限制固定Action的响应格式，那么可以应用 [Produces] 筛选器。 [Produces] 筛选器指定特定action（或控制器）的响应格式。 如同大多筛选器，这可以在action层面、控制器层面或全局范围内应用。 这样格式协商就失败，始终返回json数据格式。

       //控制器层面强制使用json格式
      [Produces("application/json")]
      [ApiController]//添加特性，代表是一个Web API控制器
      public class TodoController : Controller

      //action层面强制返回json格式
       [Produces("application/json")]
       [HttpGet]
       public async Task<ActionResult<IEnumerable<TodoItem>>> GetTodoItems()
       {
            //using Microsoft.EntityFrameworkCore;
            return await _context.TodoItems.ToListAsync();
       }

　　　　

       2.4 特殊情况格式化程序

　　　　如果要过滤客户端Accept请求的某些类型，例如过滤text/plain。string 默认是text/plain类型，如果删除TextOutputFormatter，则string返回类型 是406 Not Acceptable。

　　//下面对返回string字符串或返回http 204的进行过滤,代码对应如下：
　　services.AddMvc(options =>
　　{
    　　options.OutputFormatters.RemoveType<TextOutputFormatter>();
    　　options.OutputFormatters.RemoveType<HttpNoContentOutputFormatter>();
　　});

 

　　2.5 响应格式URL映射

　　　　当格式协商配置好了以后，客户端可以请求特定格式作为URL的一部分。下面是Url映射的配置示例。

　　[FormatFilter]
　　public class ProductsController
　　{
  　　  [Route("[controller]/[action]/{id}.{format?}")]
  　　  public Product GetById(int id)

 　　　　当客户端访问该url，返回默认数据格式:

　　　　/products/GetById/5

 

　　　　当客户端访问该url，返回json数据格式：

　　　　/products/GetById/5.json

 

　　　　当客户端访问该url，返回xml数据格式：

　　　　/products/GetById/5.xml

 

　　参考文献：　　　　

　　　　操作返回类型

　　　　响应格式化

相关文章

ASP.NET Core Web API下事件驱动型架构的实现（二）：事件处理器中对象生命周期的管理
在上文中，我介绍了事件驱动型架构的一种简单的实现，并演示...
Angular SPA基于Ocelot API网关与IdentityServer4的身份认证与授权（二）
上文已经介绍了Identity Service的实现过程。今天我们继续，...
使用Angular 4、Bootstrap 4、TypeScript和ASP.NET Core开发的Apworks框架案例应用：Task List
最近我为我自己的应用开发框架Apworks设计了一套案例应用程序...
在ASP.NET Core Web API中为RESTful服务增加对HAL的支持
HAL（Hypertext Application Language，超文本应用语言）是一...
ASP.NET Core Web API下事件驱动型架构的实现（四）：CQRS架构中聚合与聚合根的实现
在前面两篇文章中，我详细介绍了基本事件系统的实现，包括事...
在ASP.NET Core中使用Apworks开发数据服务：对HAL的支持
HAL，全称为Hypertext Application Language，它是一种简单的...