当前位置: 首页 > 工具软件 > Physical Web > 使用案例 >

一文带你Asp.Netcore webapi快速进阶【详细说明+使用案例】

冯良才
2023-12-01

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.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public ActionResult 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 特定的固定行为:

属性路由要求
自动 HTTP 400 响应
绑定源参数推理
Multipart/form-data 请求推理
错误状态代码的问题详细信息
必须有兼容性版本 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 中的 UseEndpoints、UseMvc 或 UseMvcWithDefaultRoute 定义的传统路由访问操作。

自动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] 不适用于具有特殊含义的任何复杂的内置类型,如 IFormCollection 和 CancellationToken。 绑定源推理代码将忽略这些特殊类型。
[FromForm] 针对 IFormFile 和 IFormFileCollection 类型的操作参数进行推断。 该特性不针对任何简单类型或用户定义类型进行推断。
[FromRoute] 针对与路由模板中的参数相匹配的任何操作参数名称进行推断。 当多个路由与一个操作参数匹配时,任何路由值都视为 [FromRoute]。
[FromQuery] 针对任何其他操作参数进行推断。
FromBody 推理说明
对于简单类型(例如 string 或 int),推断不出 [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\] 属性批注操作参数时,[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/json 和 application/xml。

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

[HttpPost]
[Consumes("application/xml")]
public IActionResult CreateProduct(Product product)
 
在上面的代码中,CreateProduct 操作指定内容类型 application/xml。 路由到此操作的请求必须指定 application/xml 的 Content-Type 头。 如果请求未指定 application/xml的 Content-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 的请求。 控制器的两个操作(PostJson 和 PostForm)都使用相同的 URL 处理 POST 请求。 如果 [Consumes] 属性不应用类型约束,则会抛出不明确匹配异常。

[Consumes] 属性应用于两个操作。 PostJson 操作处理使用 application/json 的 Content-Type 头发送的请求。 PostForm 操作处理使用 application/x-www-form-urlencoded 的 Content-Type 头发送的请求。
————————————————
版权声明:本文为CSDN博主「广海_小疯疯丶」的原创文章,遵循CC 4.0 BY-SA版权协议,转载请附上原文出处链接及本声明。
原文链接:https://blog.csdn.net/qq_34202873/article/details/106430152

 类似资料: