如何在C# WebAPI中捕获验证错误并排查客户端报错问题

一、客户端侧快速验证 #

• 用Postman/Swagger直接调用接口，传入和RestSharp完全一致的参数，查看原始响应。RestSharp可能会包装或截断服务器返回的错误，原生工具能拿到更准确的错误详情。
• 对齐序列化配置：确保RestSharp使用的JSON序列化器（如System.Text.Json或Newtonsoft.Json）和Web API端的配置完全匹配，比如字段大小写策略、枚举处理方式、空值序列化规则等，不匹配会导致序列化失败。
• 打印原始请求体：在RestSharp请求中添加代码，输出实际发送的JSON内容，对比模型类结构检查问题：

  request.OnBeforeRequest = req => 
  {
      if (req.Body != null) Console.WriteLine(req.Body);
      return Task.CompletedTask;
  };
  

  重点检查是否有字段缺失、类型不匹配（如字符串传给数字字段）、数组格式错误等问题。

二、服务器端添加拦截器捕获前置错误 #

断点未进入控制器方法，说明错误发生在模型绑定/验证、JSON序列化等前置阶段，可通过以下两种方式捕获详细错误：

方法1：自定义模型验证过滤器 #

创建继承自ActionFilterAttribute的过滤器，专门捕获模型验证错误：

public class ValidationFilter : ActionFilterAttribute
{
    public override void OnActionExecuting(ActionExecutingContext context)
    {
        if (!context.ModelState.IsValid)
        {
            var errors = context.ModelState
                .Where(kv => kv.Value.Errors.Any())
                .SelectMany(kv => kv.Value.Errors)
                .Select(e => e.ErrorMessage)
                .ToList();

            context.Result = new BadRequestObjectResult(new
            {
                Message = "参数验证失败",
                DetailedErrors = errors
            });
        }
    }
}

在Program.cs中注册全局过滤器：

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

此时模型验证失败时，客户端会收到包含具体错误（如字段必填、长度超限）的响应。

方法2：全局错误捕获中间件 #

针对JSON序列化失败等更底层的前置错误，用中间件捕获：

public class ErrorHandlingMiddleware
{
    private readonly RequestDelegate _next;
    private readonly ILogger<ErrorHandlingMiddleware> _logger;

    public ErrorHandlingMiddleware(RequestDelegate next, ILogger<ErrorHandlingMiddleware> logger)
    {
        _next = next;
        _logger = logger;
    }

    public async Task InvokeAsync(HttpContext context)
    {
        try
        {
            await _next(context);
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "前置处理阶段发生错误");
            await HandleExceptionAsync(context, ex);
        }
    }

    private static Task HandleExceptionAsync(HttpContext context, Exception ex)
    {
        context.Response.ContentType = "application/json";
        context.Response.StatusCode = StatusCodes.Status400BadRequest;

        if (ex is JsonException jsonEx)
        {
            return context.Response.WriteAsJsonAsync(new
            {
                Message = "JSON格式错误",
                DetailedError = jsonEx.Message
            });
        }

        return context.Response.WriteAsJsonAsync(new
        {
            Message = "请求处理失败",
            DetailedError = ex.Message
        });
    }
}

注册中间件（需放在UseRouting之后、UseEndpoints之前）：

app.UseMiddleware<ErrorHandlingMiddleware>();

该中间件能捕获JSON序列化、请求格式错误等前置异常，返回具体错误信息。

三、检查Web API错误配置 #

开发环境下确保开启详细错误：

1. 在appsettings.Development.json中添加：

   {
     "DetailedErrors": true
   }
   

2. 在Program.cs中保留开发环境错误页面：

   if (app.Environment.IsDevelopment())
   {
       app.UseDeveloperExceptionPage();
   }
   

四、额外排查点 #

• 检查ErrorCode类型：如果是枚举，确认客户端传入的是正确的枚举值（字符串或数字）；如果是自定义类，确保有无参构造函数、所有属性都可序列化。
• 确认控制器方法参数是否加了[FromBody]修饰：缺少该特性会导致模型绑定失败，触发前置错误。

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