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

 

　　参考文献：