.NET 6 WebAPI模型验证疑问：ModelState.IsValid何时为false？能否进入Action？

我在VS 2022中创建了一个.NET 6 WebAPI项目，为模型Customer类的CustomerId属性添加了[MaxLength(5)]和[MinLength(5)]特性。

控制器代码片段如下：

[Route("api/[controller]")]
[ApiController]
public class CustomerController : ControllerBase
{
    private readonly NorthwindContext _ctx;
    // ...
    [HttpPost]
    public Customer Insert(Customer customer)
    {
        // 方法从未被调用，管道直接返回带正确错误信息的HTTP 400响应
        if (!ModelState.IsValid)
        {

        }
        // ... 其他代码
    }
}

当传入无效数据（如长度为4或6的CustomerId）调用API时，Insert方法从未执行，管道立即返回带正确验证错误信息的HTTP 400响应。

疑问 #

1. 不清楚何时ModelState.IsValid会为false？
2. 能否配置管道让该方法被调用？

关于ModelState.IsValid何时为false #

默认情况下，[ApiController]特性会触发模型验证自动响应机制：控制器方法执行前，ASP.NET Core管道会先完成模型验证，一旦验证失败（比如CustomerId长度不符合要求），会直接返回HTTP 400响应，不会进入控制器方法。这就是你看不到ModelState.IsValid为false的原因——方法根本没执行到判断的那一步。

只有在以下场景中，你才会在方法内看到ModelState.IsValid为false：

• 关闭了自动验证响应功能
• 手动向ModelState中添加了自定义验证错误
• 方法内部修改了ModelState的状态

如何配置让控制器方法被调用 #

要让模型验证失败时依然进入控制器方法，需要关闭[ApiController]的自动验证响应，有两种实现方式：

方式1：全局配置（Program.cs）

在服务配置阶段添加代码，对所有带[ApiController]的控制器生效：

builder.Services.Configure<ApiBehaviorOptions>(options =>
{
    options.SuppressModelStateInvalidFilter = true;
});

配置完成后，验证失败时会进入控制器方法，你可以自行通过ModelState.IsValid判断并处理逻辑。

方式2：局部配置（针对单个控制器/方法）

如果只想针对特定控制器或方法关闭自动验证，可以使用[SuppressModelStateInvalidFilter]特性标记：

[Route("api/[controller]")]
[ApiController]
[SuppressModelStateInvalidFilter] // 对整个控制器生效
public class CustomerController : ControllerBase
{
    // ...
    [HttpPost]
    // 或仅对当前方法生效：[SuppressModelStateInvalidFilter]
    public Customer Insert(Customer customer)
    {
        if (!ModelState.IsValid)
        {
            // 自定义错误处理逻辑，比如返回自定义格式的响应
            return BadRequest(ModelState);
        }
        // ... 正常业务逻辑
    }
}

关闭自动验证后，你就可以在方法内手动控制验证失败后的处理流程，比如返回自定义错误信息、执行额外业务操作等。

内容的提问来源于stack exchange，提问作者g.pickardou