WEB API Action Method 的返回类型应该是啥？

Posted 2023-03-31

【中文标题】WEB API Action Method 的返回类型应该是啥？

【英文标题】：What should be the return type of WEB API Action Method?WEB API Action Method 的返回类型应该是什么？

【发布时间】：2016-10-04 04:56:12

【问题描述】：

我正在使用 .NET Core 开发 ASP.NET Web API。此 Web API 将主要由 UI 应用程序访问（UI 将使用 ASP.NET Core MVC 开发），但未来 API 也可能由其他应用程序访问。

在我的 WEB API 中，所有方法都是异步的。

如果我想让客户端进行内容协商，那么 API 操作方法 Task<IActionresult> 或 Task<SomePOCO> 的返回类型应该是什么

如果我希望方法始终以 JSON 格式返回数据，那么 API 操作方法的返回类型应该是什么？应该是Task<IActionResult> 或Task<JsonResult> 还是Task<SomePOCO>，因为我认为这三个都可以，所以不确定哪个适合这里？

【问题讨论】：

请不要将标签强加到问题标题***.com/help/tagging

【参考方案1】：

如果我希望 [the] 客户端进行内容协商，那么 API 操作方法的返回类型应该是什么？

要进行内容协商，请返回 Task<ObjectResult> 或 Task<MyPoco>。

框架自动将 POCO 包装在 ObjectResult 中；因此，这两个选项是等效的，并且都将遵循 HTTP Accept 标头。您还将通过返回实现ObjectResult 的任何结果（例如OkObjectResult）来获得内容协商。

如果我希望 [the] 方法始终以 JSON 格式返回数据，那么 API 操作方法的 [the] 返回类型应该是什么？

要始终返回 JSON，请返回 Task<JsonResult>（或使用 [Produces] 过滤器）。

另请参阅：https://docs.asp.net/en/latest/mvc/models/formatting.html#content-negotiation

[S]o 我假设 IActionResult 仅用于 MVC 控制器？

IActionResult 是Controller 返回的所有结果的合同。如果您的操作签名具有IActionResult 返回类型，那么您的操作方法体可以return 任何结果类型，因为它们都实现了IActionResult 接口。这是继承层次结构。

IActionResult
  ActionResult
    ChallengeResult 
    ContentResult 
    EmptyResult 
    FileResult 
      FileContentResult 
      FileStreamResult 
      PhysicalFileResult 
      VirtualFileResult 
    ForbidResult 
    LocalRedirectResult 
    ObjectResult
      CreatedAtActionResult 
      CreatedAtRouteResult 
      CreatedResult 
      BadRequestObjectResult 
      NotFoundObjectResult 
      OkObjectResult 
    RedirectResult 
    RedirectToActionResult 
    RedirectToRouteResult 
    SignInResult 
    SignOutResult 
    StatusCodeResult 
      NoContentResult 
      NotFoundResult 
      OkResult 
      UnauthorizedResult 
      UnsupportedMediaTypeResult 
      BadRequestResult 

另见：https://github.com/aspnet/Mvc/tree/dev/src/Microsoft.AspNetCore.Mvc.Core

【讨论】：

所以我假设 IActionResult 仅用于 MVC 控制器？

@LP13 IActionResult 是***接口。大多数（如果不是全部）结果都实现了IActionResult。查看修改。

【参考方案2】：

看看swagger： https://docs.microsoft.com/en-us/aspnet/core/tutorials/web-api-help-pages-using-swagger 最好为方法指定 ProducesResponseType 属性：

[ProducesResponseType(typeof(TodoItem), 201)]
public IActionResult Create([FromBody, Required] TodoItem item)

这样会自动生成 swagger 文档来显示该方法的实际返回数据。