排坑日记：ASP.NET Core 中 “Required field is not provided“ 验证错误全记录

问题出现

在开发一个基于 ASP.NET Core 10.0 的 Web API 项目时，遇到了一个令人困惑的验证错误。

库存扣减接口的原始代码如下：

[HttpPost("{drugId}/decrement/{quantity}")]
public async Task<string?> DecInventoryAsync(
    [FromRoute] string drugId,
    [FromRoute] int quantity)
{
   
    var inventory = await _inventoryService.DeductInventoryAsync(drugId, quantity);
    return inventory;
}

通过 Swagger UI 调用接口：

POST /api/inventories/drug001/decrement/10

返回的却是 400 错误：

{
   
    "errors": {
   
        "quantity": ["Required field is not provided."]
    }
}

这就很奇怪了——URL 路径里明明写着 decrement/10，quantity 的值 10 就在那里，怎么说没提供？

问题排查

既然路由拼写和参数绑定看起来都没问题，那就一步步缩小范围。

第一步：排除 [FromRoute] 显式标记的影响

假设：[FromRoute] 显式标注与 [ApiController] 的自动推断产生了冲突。

验证：去掉 [FromRoute]，让框架自动推断绑定来源：

[HttpPost("{drugId}/decrement/{quantity}")]
public async Task<string?> DecInventoryAsync(string drugId, int quantity)

结果：依然报错 "Required field is not provided." → 假设不成立，问题不在 [FromRoute]。

第二步：排查参数类型的影响

假设：非可空值类型 int 被 [ApiController] 隐式标记为 [Required]，导致验证管道的误判。

验证：将 int quantity 改为可空值类型 int?：

public async Task<string?> DecInventoryAsync(
    [FromRoute] string drugId,
    [FromRoute] int? quantity)

结果：错误消失了！→ 假设成立。

关键发现：问题出在 int 这个非可空值类型上。[ApiController] 对非可空值类型会自动添加 [Required] 验证，而在多参数 [FromRoute] 绑定场景下，验证管道无法正确识别该参数已被路由提供，于是报了误判错误。

第三步：确认根因

翻阅官方文档，[ApiController] 的隐式规则总结如下：

1. 对非可空值类型自动添加 [Required] 验证
2. 对所有参数进行自动模型验证
3. 当存在多个 [FromRoute] 参数时，原生 AddOpenApi() 生成的 OpenAPI schema 和模型验证管道之间可能存在判断不一致

根因确诊：[ApiController] 自动验证 + int 非可空类型 + 多 [FromRoute] 参数 + AddOpenApi() 四者叠加，触发了验证管道的兼容性边界 bug。

可选修复方案

确定了根因，接下来评估修复方案。核心思路是打破触发条件中的任意一环：

选择方案 ⑤ 的理由：

• 从根源上消除了"多 [FromRoute] 参数"这个触发条件
• POST 请求将业务参数放在 Body 中更符合 RESTful 设计规范
• [FromBody] 的验证管道非常成熟，不会再出现此类边界问题
• 可以配合 [Required]、[Range] 等特性提供友好的中文错误提示

最终修复：使用 InventoryDecrementDto 请求体

新增 DTO 对象

// Models/Dto/InventoryDecrementDto.cs
using System.ComponentModel.DataAnnotations;

namespace MyWebApp.Models.Dto;

public class InventoryDecrementDto
{
   
    [Required(ErrorMessage = "药品ID不能为空")]
    public string DrugId {
    get; set; }

    [Required(ErrorMessage = "库存数量不能为空")]
    [Range(1, int.MaxValue, ErrorMessage = "库存数量必须大于0")]
    public int Quantity {
    get; set; }
}

修改控制器

// 修改前
[HttpPost("{drugId}/decrement/{quantity}")]
public async Task<string?> DecInventoryAsync(
    [FromRoute] string drugId,
    [FromRoute] int quantity)

// 修改后
[HttpPost("decrement")]
public async Task<string?> DecInventoryAsync(InventoryDecrementDto decrementDto)
{
   
    var inventory = await _inventoryService.DeductInventoryAsync(
        decrementDto.DrugId,
        decrementDto.Quantity);
    return inventory;
}

新的接口签名

POST /api/inventories/decrement
Content-Type: application/json

{
    "drugId": "drug001",
    "quantity": 10
}

修复效果对比

问题根因

[ApiController] 自动验证
       +
非可空值类型 int → 隐式添加 [Required]
       +
多个 [FromRoute] 参数
       +
.NET 原生 AddOpenApi() 的 schema 生成逻辑
       ↓
验证管道无法正确识别路由参数的绑定来源
       ↓
"Required field is not provided."（误报）

核心矛盾：[ApiController] 对 int 自动加了 [Required]，但 AddOpenApi() 在处理多 [FromRoute] 参数时，生成的 OpenAPI schema 与验证管道的判断逻辑不一致，导致验证管道认为 quantity 没有被提供。

经验总结

1. "Required field is not provided" 不一定是真的没传参数——遇到这个错误，先检查是不是非可空值类型 + 多来源绑定的组合触发了框架的边界 bug。

2. 排查这类问题最快的切入点是改类型：把 int 改成 int? 试一下，如果错误消失，问题就在非可空类型的隐式 [Required] 上。

3. POST 请求的参数放 Body 是最稳妥的做法：[FromBody] 的模型绑定和验证管道是 ASP.NET Core 中最成熟、踩坑最少的路径，能避免大量路由参数绑定的边界问题。

4. DTO 模式一举两得：既解决了验证问题，又让 API 设计更规范，还方便了参数校验和 OpenAPI 文档生成。