ASP.NET Core Web API 中控制器操作的返回类型

• 特定类型
• IActionResult
• ActionResult<T>

• 特定类型
• IActionResult

[HttpGet("{id}")]
[ProducesResponseType(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public IActionResult GetById(int id)
{
    if (!_repository.TryGetProduct(id, out var product))
    {
        return NotFound();
    }

    return Ok(product);
}

[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);
}

[HttpPost]
[Consumes(MediaTypeNames.Application.Json)]
[ProducesResponseType(StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public async Task<IActionResult> CreateAsync(Product product)
{
    if (product.Description.Contains("XYZ Widget"))
    {
        return BadRequest();
    }

    await _repository.AddProductAsync(product);

    return CreatedAtAction(nameof(GetById), new { id = product.Id }, product);
}

[HttpPost]
[Consumes("application/json")]
[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);
}

如果应用的是 ASP.NET Core 2.1 或更高版本中的 [ApiController] 属性，模型验证错误会导致生成 400 状态代码。 有关详细信息，请参阅自动 HTTP 400 响应。

ActionResult<T> 类型

ASP.NET Core 2.1 引入了面向 Web API 控制器操作的 ActionResult<T> 返回类型。 它支持返回从 ActionResult 派生的类型或返回特定类型。 ActionResult<T> 通过 IActionResult 类型可提供以下优势：

• 可排除 [ProducesResponseType] 特性的 Type 属性。 例如，[ProducesResponseType(200, Type = typeof(Product))] 可简化为 [ProducesResponseType(200)]。 此操作的预期返回类型改为根据 ActionResult<T> 中的 T 进行推断。
• 隐式强制转换运算符支持将 T 和 ActionResult 均转换为 ActionResult<T>。 将 T 转换为 ObjectResult，也就是将 return new ObjectResult(T); 简化为 return T;。

C# 不支持对接口使用隐式强制转换运算符。 因此，必须使用 ActionResult<T>，才能将接口转换为具体类型。 例如，在下面的示例中，使用 IEnumerable 不起作用：

[HttpGet]
public ActionResult<IEnumerable<Product>> Get() =>
    _repository.GetProducts();

上面代码的一种修复方法是返回 _repository.GetProducts().ToList();。

大多数操作具有特定返回类型。 执行操作期间可能出现意外情况，不返回特定类型就是其中之一。 例如，操作的输入参数可能无法通过模型验证。 在此情况下，通常会返回相应的 ActionResult 类型，而不是特定类型。

同步操作

请参考以下同步操作，其中有两种可能的返回类型：

[HttpGet("{id}")]
[ProducesResponseType(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public ActionResult<Product> GetById(int id)
{
    if (!_repository.TryGetProduct(id, out var product))
    {
        return NotFound();
    }

    return product;
}

在上述操作中：

• 当产品不在数据库中时返回状态代码 404。
• 如果产品确实存在，则返回状态代码 200 及相应的 Product 对象。 ASP.NET Core 2.1 之前，return product; 行必须是 return Ok(product);。

异步操作

请参考以下异步操作，其中有两种可能的返回类型：

[HttpPost]
[Consumes(MediaTypeNames.Application.Json)]
[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);
}

在上述操作中：

• 在以下情况下，ASP.NET Core 运行时返回 400 状态代码 (BadRequest)：
  • 已应用 [ApiController] 属性，且模型验证失败。
  • 产品说明包含“XYZ 小组件”。
• 在创建产品后，CreatedAtAction 方法生成 201 状态代码。 在此代码路径中，将在响应正文中提供 Product 对象。 提供了包含新建产品 URL 的 Location 响应标头。