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

一.返回类型

　　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), new { id = product.Id }, 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

　　参考文献：　　　　

　　　　操作返回类型

　　　　响应格式化