当前C# Web API版本中ModelState是否必要？请求参数错误如何统一返回格式

一、统一错误响应格式为{ error: { message: "text" } } #

要替换默认的复杂验证错误响应，推荐使用全局Action过滤器实现，步骤如下：

1. 创建自定义验证过滤器 #

using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Filters;

public class ValidateModelStateAttribute : ActionFilterAttribute
{
    public override void OnActionExecuting(ActionExecutingContext context)
    {
        if (!context.ModelState.IsValid)
        {
            // 收集所有验证错误并拼接成单条消息
            var errorMessages = context.ModelState.Values
                .SelectMany(v => v.Errors)
                .Select(e => string.IsNullOrEmpty(e.ErrorMessage) ? e.Exception?.Message : e.ErrorMessage)
                .ToList();

            var combinedMessage = string.Join("; ", errorMessages);

            // 返回自定义格式的响应
            var customResponse = new
            {
                error = new
                {
                    message = combinedMessage
                }
            };

            context.Result = new BadRequestObjectResult(customResponse);
        }
    }
}

2. 全局注册过滤器 #

在Program.cs中添加以下代码，让所有控制器生效：

builder.Services.AddControllers(options =>
{
    options.Filters.Add<ValidateModelStateAttribute>();
});

3. 优化DateTime格式验证（可选） #

为了让日期格式错误的提示更清晰，可以在DTO的Vencimento字段上指定统一的日期格式：

using System.Text.Json.Serialization;
using System.Globalization;

public class DespesaDTO
{
    // 其他字段...

    [Column(TypeName="Date")]
    [JsonConverter(typeof(CustomDateTimeConverter))]
    public DateTime Vencimento { get; set; }

    // 其他字段...
}

// 自定义日期转换器
public class CustomDateTimeConverter : JsonConverter<DateTime>
{
    private const string DateFormat = "yyyy-MM-dd";

    public override DateTime Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
    {
        if (!DateTime.TryParseExact(reader.GetString(), DateFormat, CultureInfo.InvariantCulture, DateTimeStyles.None, out var date))
        {
            throw new JsonException($"日期格式错误，需遵循{DateFormat}格式");
        }
        return date;
    }

    public override void Write(Utf8JsonWriter writer, DateTime value, JsonSerializerOptions options)
    {
        writer.WriteStringValue(value.ToString(DateFormat, CultureInfo.InvariantCulture));
    }
}

二、ModelState的必要性 #

在ASP.NET Core Web API中，ModelState是必要的，核心原因：

• 它是框架内置的模型验证容器，自动处理参数绑定、类型转换、数据注解验证（如必填、格式校验等），比如你遇到的DateTime格式错误就是由ModelState捕获的。
• 它提供了统一的错误收集机制，无需手动逐个校验参数，减少重复代码。
• [ApiController]特性默认依赖ModelState，会自动触发400错误响应；若禁用该特性，仍需通过ModelState获取验证结果。
• 即使自定义验证逻辑，ModelState也能作为验证结果的统一载体，保持代码一致性。

你无需直接暴露默认的ModelState错误格式，通过上述过滤器即可将其转换为你需要的简洁格式。

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