webapi--参考文档

webapi

就是使用asp.net core使用c#创建Restful服务,就是webapi,如果要使用webapi控制器

webapi中的控制器是派生自ControllerBase的类,

ControllerBase类

不要通过从 Controller 类派生来创建 Web API 控制器。 Controller 派生自 ControllerBase,并添加对视图的支持,因此它用于处理 Web 页面,而不是 Web API 请求。 此规则有一个例外:如果打算为视图和 Web API 使用相同的控制器,则从 Controller 派生控制器。

ControllerBase 类提供了很多用于处理 HTTP 请求的属性和方法。

例如,ControllerBase.CreatedAtAction 返回 201 状态代码:

下面是 ControllerBase 提供的方法的更多示例。

方法说明
BadRequest 返回 400 状态代码。
NotFound 返回 404 状态代码。
PhysicalFile 返回文件。
TryUpdateModelAsync 调用模型绑定
TryValidateModel 调用模型验证

特性

Microsoft.AspNetCore.Mvc 命名空间提供可用于配置 Web API 控制器的行为和操作方法的属性。 下述示例使用属性来指定受支持的 HTTP 操作动作和所有可返回的已知 HTTP 状态代码:

HttpPost [ProducesResponseType(StatusCodes.Status400BadRequest)] public ActionResult<Pet> Create(Pet pet) { pet.Id = _petsInMemoryStore.Any() ? _petsInMemoryStore.Max(p => p.Id) + 1 : 1; _petsInMemoryStore.Add(pet); return CreatedAtAction(nameof(GetById), new { id = pet.Id }, pet); }

特性说明
[[Route\]] 指定控制器或操作的 URL 模式。
[[Bind\]] 指定要包含的前缀和属性,以进行模型绑定。
[[HttpGet\]] 标识支持 HTTP GET 操作谓词的操作。
[[Consumes\]] 指定某个操作接受的数据类型。
[[Produces\]] 指定某个操作返回的数据类型。

ApiController特性

特定控制器上特性

[[ApiController\]]属性可应用于控制器类,以启用下述 API 特定的固定行为:

必须有兼容性版本 2.2 或更高版本,才能使用“错误状态代码的问题详细信息” 功能。 必须有兼容性版本 2.1 或更高版本,才能使用其他功能。

多个控制器上的特性

在多个控制器上使用该属性的一种方法是创建通过 [ApiController] 属性批注的自定义基控制器类。 下述示例展示了自定义基类以及从其派生的控制器:

[ApiController]
public class MyControllerBase : ControllerBase
{
}
[Produces(MediaTypeNames.Application.Json)]
[Route("[controller]")]
public class PetsController : MyControllerBase

程序集上特性

如果将兼容性版本设置为 2.2 或更高版本,则 [ApiController] 属性可应用于程序集。 以这种方式进行注释,会将 web API 行为应用到程序集中的所有控制器。 无法针对单个控制器执行选择退出操作。 将程序集级别的属性应用于 Startup 类两侧的命名空间声明:

[assembly: ApiController]
namespace WebApiSample
{
   public class Startup
  {
      ...
  }
}

特性路由要求

[ApiController] 属性使属性路由成为要求。 例如:

[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase

不能通过由 Startup.Configure 中的 UseEndpointsUseMvcUseMvcWithDefaultRoute 定义的传统路由访问操作。

自动http 400响应

[ApiController] 属性使模型验证错误自动触发 HTTP 400 响应。 因此,操作方法中不需要以下代码:

if (!ModelState.IsValid)
{
   return BadRequest(ModelState);
}

ASP.NET Core MVC 使用 ModelStateInvalidFilter 操作筛选器来执行上述检查。

默认 BadRequest 响应

使用 2.1 的兼容性版本时,HTTP 400 响应的默认响应类型为 SerializableError。 下述请求正文是序列化类型的示例:

JSON

{
 "": [
   "A non-empty request body is required."
]
}

使用 2.2 或更高版本的兼容性版本时,HTTP 400 响应的默认响应类型为 ValidationProblemDetails。 下述请求正文是序列化类型的示例:

JSON

{
 "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
 "title": "One or more validation errors occurred.",
 "status": 400,
 "traceId": "|7fb5e16a-4c8f23bbfc974667.",
 "errors": {
   "": [
     "A non-empty request body is required."
  ]
}
}

ValidationProblemDetails 类型:

  • 提供计算机可读的格式来指定 Web API 响应中的错误。

  • 符合 RFC 7807 规范

记录自动 400 响应

请参阅如何对模型验证错误记录自动 400 响应 (aspnet/AspNetCore.Docs #12157)

禁用自动 400 响应

若要禁用自动 400 行为,请将 SuppressModelStateInvalidFilter 属性设置为 true。 将以下突出显示的代码添加到 Startup.ConfigureServices

services.AddControllers()
  .ConfigureApiBehaviorOptions(options =>
  {
       options.SuppressConsumesConstraintForFormFileParameters = true;
       options.SuppressInferBindingSourcesForParameters = true;
       options.SuppressModelStateInvalidFilter = true;
       options.SuppressMapClientErrors = true;
       options.ClientErrorMapping[404].Link =
           "https://httpstatuses.com/404";
  });

绑定源参数推理

绑定源特性定义可找到操作参数值的位置。 存在以下绑定源特性:

特性绑定源
[[FromBody\]] 请求正文
[[FromForm\]] 请求正文中的表单数据
[[FromHeader\]] 请求标头
[[FromQuery\]] 请求查询字符串参数
[[FromRoute\]] 当前请求中的路由数据
[[FromServices\]] 作为操作参数插入的请求服务

如果没有 [ApiController] 属性或诸如 [FromQuery] 的绑定源属性,ASP.NET Core 运行时会尝试使用复杂对象模型绑定器。 复杂对象模型绑定器按已定义顺序从值提供程序拉取数据。

在下面的示例中,[FromQuery] 特性指示 discontinuedOnly 参数值在请求 URL 的查询字符串中提供:

[HttpGet]
public ActionResult<List<Product>> Get(
    [FromQuery] bool discontinuedOnly = false)
{
    List<Product> products = null;

    if (discontinuedOnly)
    {
        products = _productsInMemoryStore.Where(p => p.IsDiscontinued).ToList();
    }
    else
    {
        products = _productsInMemoryStore;
    }

    return products;
}

[ApiController] 属性将推理规则应用于操作参数的默认数据源。 借助这些规则,无需通过将属性应用于操作参数来手动识别绑定源。 绑定源推理规则的行为如下:

  • [FromBody] 针对复杂类型参数进行推断。 [FromBody] 不适用于具有特殊含义的任何复杂的内置类型,如 IFormCollectionCancellationToken。 绑定源推理代码将忽略这些特殊类型。

  • [FromForm] 针对 IFormFileIFormFileCollection 类型的操作参数进行推断。 该特性不针对任何简单类型或用户定义类型进行推断。

  • [FromRoute] 针对与路由模板中的参数相匹配的任何操作参数名称进行推断。 当多个路由与一个操作参数匹配时,任何路由值都视为 [FromRoute]

  • [FromQuery] 针对任何其他操作参数进行推断。

FromBody 推理说明

对于简单类型(例如 stringint),推断不出 [FromBody]。 因此,如果需要该功能,对于简单类型,应使用 [FromBody] 属性。

当操作拥有多个从请求正文中绑定的参数时,将会引发异常。 例如,以下所有操作方法签名都会导致异常:

  • [FromBody] 对两者进行推断,因为它们是复杂类型。

    [HttpPost]
    public IActionResult Action1(Product product, Order order)
  • [FromBody] 对一个进行归属,对另一个进行推断,因为它是复杂类型。

    [HttpPost]
    public IActionResult Action2(Product product, [FromBody] Order order)
  • [FromBody] 对两者进行归属。

    [HttpPost]
    public IActionResult Action3([FromBody] Product product, [FromBody] Order o

禁用推理规则

若要禁用绑定源推理,请将 SuppressInferBindingSourcesForParameters 设置为 true。在 Startup.ConfigureServices 中添加下列代码:

services.AddControllers()
    .ConfigureApiBehaviorOptions(options =>
    {
        options.SuppressConsumesConstraintForFormFileParameters = true;
        options.SuppressInferBindingSourcesForParameters = true;
        options.SuppressModelStateInvalidFilter = true;
        options.SuppressMapClientErrors = true;
        options.ClientErrorMapping[404].Link =
            "https://httpstatuses.com/404";
    });

Multipart/form-data 请求推理

使用 [[FromForm\]](https://docs.microsoft.com/zh-cn/dotnet/api/microsoft.aspnetcore.mvc.fromformattribute) 属性批注操作参数时,[ApiController] 属性应用推理规则。 将推断 multipart/form-data 请求内容类型。

要禁用默认行为,请在 Startup.ConfigureServices 中将 SuppressConsumesConstraintForFormFileParameters 属性设置为 true

services.AddControllers()
    .ConfigureApiBehaviorOptions(options =>
    {
        options.SuppressConsumesConstraintForFormFileParameters = true;
        options.SuppressInferBindingSourcesForParameters = true;
        options.SuppressModelStateInvalidFilter = true;
        options.SuppressMapClientErrors = true;
        options.ClientErrorMapping[404].Link =
            "https://httpstatuses.com/404";
    });

错误状态代码的问题详细信息

禁用 ProblemDetails 响应

SuppressMapClientErrors 属性设置为 true 时,会禁止自动创建错误状态代码的 ProblemDetails。 在 Startup.ConfigureServices 中添加下列代码:

services.AddControllers()
    .ConfigureApiBehaviorOptions(options =>
    {
        options.SuppressConsumesConstraintForFormFileParameters = true;
        options.SuppressInferBindingSourcesForParameters = true;
        options.SuppressModelStateInvalidFilter = true;
        options.SuppressMapClientErrors = true;
        options.ClientErrorMapping[404].Link =
            "https://httpstatuses.com/404";
    });

使用 [Consumes] 属性定义支持的请求内容类型

默认情况下,操作支持所有可用的请求内容类型。 例如,如果应用配置为同时支持 JSON 和 XML 输入格式化程序,那么操作支持多种内容类型,其中包括 application/jsonapplication/xml

使用 [Consumes] 属性,操作可以限制支持的请求内容类型。 将 [Consumes] 属性应用于操作或控制器,同时指定一个或多个内容类型:

[HttpPost]
[Consumes("application/xml")]
public IActionResult CreateProduct(Product product)

在上面的代码中,CreateProduct 操作指定内容类型 application/xml。 路由到此操作的请求必须指定 application/xmlContent-Type 头。 如果请求未指定 application/xmlContent-Type 头,会生成 415 不支持的媒体类型响应。

使用 [Consumes] 属性,操作可以通过应用类型约束,根据传入请求的内容类型来影响它的选择。 请看下面的示例:

[ApiController]
[Route("api/[controller]")]
public class ConsumesController : ControllerBase
{
    [HttpPost]
    [Consumes("application/json")]
    public IActionResult PostJson(IEnumerable<int> values) =>
        Ok(new { Consumes = "application/json", Values = values });

    [HttpPost]
    [Consumes("application/x-www-form-urlencoded")]
    public IActionResult PostForm([FromForm] IEnumerable<int> values) =>
        Ok(new { Consumes = "application/x-www-form-urlencoded", Values = values });
}

在上面的代码中,ConsumesController 配置为处理发送到 https://localhost:5001/api/Consumes URL 的请求。 控制器的两个操作(PostJsonPostForm)都使用相同的 URL 处理 POST 请求。 如果 [Consumes] 属性不应用类型约束,则会抛出不明确匹配异常。

[Consumes] 属性应用于两个操作。 PostJson 操作处理使用 application/jsonContent-Type 头发送的请求。 PostForm 操作处理使用 application/x-www-form-urlencodedContent-Type 头发送的请求。

posted @ 2020-05-17 11:04  日积月累码农  阅读(623)  评论(0编辑  收藏  举报