ASP.NET Core WebAPI如何捕获处理验证异常并返回前端友好错误信息

问题原因 #

该错误是ASP.NET Core中[ApiController]特性自带的自动模型验证逻辑导致的：请求进入Action方法前会先执行模型绑定与验证，绑定/验证失败时会直接返回400响应，不会进入Action的代码逻辑。字段名带$.前缀是JSON序列化过程中默认的JSON Path标识格式。

推荐解决方案：全局自定义模型验证响应 #

直接在Program.cs（.NET 6及以上版本）中配置ApiBehaviorOptions，统一处理所有模型验证错误，同时格式化错误字段和提示信息：

builder.Services.Configure<ApiBehaviorOptions>(options =>
{
    options.InvalidModelStateResponseFactory = context =>
    {
        var formattedErrors = new Dictionary<string, string[]>();
        foreach (var (rawKey, errorEntry) in context.ModelState)
        {
            // 去除JSON Path前缀$.，提取实际字段名
            var fieldName = rawKey.StartsWith("$.") ? rawKey[2..] : rawKey;
            // 格式化错误提示为易懂内容
            var errorMsgs = errorEntry.Errors.Select(e => 
            {
                if (e.ErrorMessage.Contains("The JSON value could not be converted"))
                {
                    return $"字段{fieldName}数据类型错误，请传入符合要求的参数值";
                }
                return e.ErrorMessage;
            }).ToArray();
            formattedErrors.Add(fieldName, errorMsgs);
        }

        // 返回自定义格式的响应
        return new BadRequestObjectResult(new
        {
            Code = 400,
            Message = "请求参数验证失败",
            Errors = formattedErrors
        });
    };
});

可选方案：自定义类型转换器（兼容特殊传值场景） #

如果希望自动兼容布尔值、数字转字符串的场景，无需抛出错误，可自定义JSON字符串转换器：

public class AutoStringConverter : JsonConverter<string>
{
    public override string Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
    {
        // 自动将布尔、数字类型转为字符串
        return reader.TokenType switch
        {
            JsonTokenType.True or JsonTokenType.False => reader.GetBoolean().ToString(),
            JsonTokenType.Number => reader.GetDecimal().ToString(),
            _ => reader.GetString() ?? string.Empty
        };
    }

    public override void Write(Utf8JsonWriter writer, string value, JsonSerializerOptions options)
    {
        writer.WriteStringValue(value);
    }
}

在Program.cs中注册转换器即可全局生效：

builder.Services.AddControllers().AddJsonOptions(options =>
{
    options.JsonSerializerOptions.Converters.Add(new AutoStringConverter());
});

效果说明 #

• 所有模型验证错误（包括类型转换错误、必填项缺失错误等）都会统一返回自定义格式
• 自动去除字段名前的$.前缀，直接返回实际字段名给前端
• 不需要修改现有Controller和Model的代码，全局生效

内容的提问来源于stack exchange，提问作者Amrit