asp.net core系列 38 WebAPI 返回类型与响应格式--必备
一.返回类型ASP.NET Core 提供以下 Web API Action方法返回类型选项,以及说明每种返回类型的最佳适用情况: (1) 固定类型 (2) IActionResult (3) ActionResult<T>
1.1 固定类型 最简单的操作是返回基元或复杂数据类型(如? [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??例如: ?(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 标头时,就可以实现内容协商,对于内容协商返回数据格式由? ? 下面的案例中,返回IActionResult,返回的数据格式,由 [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) 默认情况下,当框架检测到请求来自浏览器时,它将忽略? (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类型,如果删除 //下面对返回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 – 使用[FromBody]时获取原始POST数据
- asp.net-mvc-3 – MVC3剃须刀:是否可以渲染传统的ASCX?
- asp.net – 使用WebHandler的HTTPHandler和IsReusable
- asp.net-mvc-3 – 如何在带有剃刀的asp.net mvc3中使用Kend
- 如何在ASP.NET中将文本框的宽度设置为与MaxLength相同
- asp.net-mvc – 如何使用ASP.NET Razor语法应用bootstrap v
- 启用AllowSorting时,ASP.NET GridView标题行文本为空
- asp.net – 如何从另一个UserControl继承UserControl?
- asp.net – 使用逗号分隔值搜索列
- asp.net-mvc-3 – 如何调试AutoMapper“缺少类型映射配置或
- asp.net-mvc – 在DropDownList ASP.NET MVC中获
- entity-framework – ASP.NET动态数据:如何在下
- asp.net – 用于登录用户到网站的T-SQL AES加密与
- asp.net-mvc – 如何在Html.RenderAction(MVC3)中
- asp.net-mvc – 如何在asp mvc中阻止访问Interne
- 自动完成后的事件填写Asp.net C#或javascript /
- asp.net – 过程或函数“”需要参数“”,这是未提
- asp.net – MultipartFormDataStreamProvider清理
- asp.net – 仅限RadComboBox下拉列表
- 在ASP.net中为按钮应用皮肤文件