【译】ASP.NET Core Web APIs（二）：使用ASP.NET Core创建Web APIs 【中篇】
原文链接：传送门。
特性路由需求
[ApiConroller]特性使得特性路由成为一个需求。举个例子：
[ApiController] [Route("[controller]")] public class WeatherForecastController : ControllerBase
通过由 Startup.Configure中的UseEndpoints, UseMvc,或者r UseMvcWithDefaultRoute方法定义的常规路由是不能访问Action方法的。
自动HTTP 400 响应
[ApiController] 特性使得模型验证错误自动触发一个HTTP 400 响应。因此，在一个Action方法中，如下代码是不必要的：
if (!ModelState.IsValid) { return BadRequest(ModelState); }
ASP.NET Core MVC使用ModelStateInvalidFilter 这个动作过滤器来进行上述检查。
默认的BadRequest响应
使用兼容性版本2.1，对于一个HTTP 400响应的默认响应类型是SerializableError。如下的请求体是一个序列化类型的示例：
{ "": [ "A non-empty request body is required." ] }
使用兼容性版本2.2及以后，那么对于一个HTTP 400响应，默认的响应类型是 ValidationProblemDetails。如下的请求体是一个序列化类型的示例：
{ "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 specification 进行编译。
记录自动的HTTP 400 响应
请参考How to log automatic 400 responses on model validation errors (aspnet/AspNetCore.Docs #12157)。
禁用自动的HTTP 400响应
为了禁用自动HTTP 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"; });
绑定源参数引用
一个绑定源特性定义了一个Action 参数的值被找到的位置。绑定源特性具有如下种类：
| 特性 | 对应的绑定源 |
|---|---|
[FromBody] |
请求体 |
[FromForm] |
请求体中的表单数据 |
[FromHeader] |
请求头 |
[FromQuery] |
请求查询字符串参数 |
[FromRoute] |
来自于当前请求的路由数据 |
[FromServices] |
作为一个Action参数而注入的请求服务 |
原文链接：传送门。
注意：当值可能包含%2f（也就是/）时，请不要使用[FromRouter]，%2f不会被转义为 /。如果值可能包含%2f时，请使用[FromQuery]。
如果没有[ApiController] 特性或者像是[FromQuery]这样的绑定源特性，那么ASP.NET Core运行时会试图复杂对象模型绑定器。复杂对象模型绑定i会以定义好的顺序从值提供器中拉取数据。
在如下的示例中，[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]特性为Action参数的默认数据源应用推断规则。这些规则可以节省你的时间，使得你不必通过给Action参数应用绑定特性以手动的指定其绑定源。绑定源推断规则行为如下：
- [FromBody]推断为复杂类型参数。一个[FromBody]推断规则的例外是具有一个特定意义（比如IFormCollection 或者CancellationToken.）的任何复杂类型，内置类型。绑定源推断代码将会忽略那些指定的类型。
- [FromForm]被推断为类型为 IFormFile 和 IFormFileCollection的Action参数。其不会被推断为任何简单类型或者用户自定义类型。
- [FromRouter]被推断为任何Action参数名称匹配于路由模板中的参数的情况。当超过一个的路由匹配到Action参数时，任何一个路由值都会被认为是[FromRouter]。
- [FromQuery]被推断为任何其他的Action参数。
[FromBody]推断注意
[FromBody]不会被推断为任何简单类型，比如string 或者 int。因此，当确实需要那个功能的时候，[FromBody]特性需要被用于简单类型。
当一个Action具有多个方法参数是从请求体中进行绑定，则会抛出一个异常。举个例子，所有如下的Action方法前面会引起一个异常。
- [FromBody]推断在两者上因为其都是复杂类型。
[HttpPost] public IActionResult Action1(Product product, Order order)
- 在一个参数上使用[FromBody]，而另一个推断为[FromBody]，因为其是复杂类型。
[HttpPost] public IActionResult Action2(Product product, [FromBody] Order order)
- 两者都有[FromBody]特性。
[HttpPost] public IActionResult Action3([FromBody] Product product, [FromBody] Order order)
禁用推断规则
为了禁用绑定源推断，将 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 请求推断
当一个Action参数被 [FromForm] 特性标记时，[ApiController]特性会应用另一个推断规则。multipart/form-data请求content-type会被推断。
为了禁用默认的行为，在 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"; });
