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