.NET 8 Minimal API如何捕获强类型ID参数绑定错误？

当使用强类型ID作为.NET 8 Minimal API的参数时，若客户端传入格式无效的值，默认会触发转换异常并返回500内部服务器错误。这类属于客户端输入错误，应返回400 Bad Request，可通过以下几种方式处理：

方法一：为强类型ID自定义模型绑定器 #

为PatientProfileId实现自定义模型绑定逻辑，在转换失败时主动标记模型验证错误，让框架自动返回400响应：

public class PatientProfileIdModelBinder : IModelBinder
{
    public Task BindModelAsync(ModelBindingContext bindingContext)
    {
        var valueProviderResult = bindingContext.ValueProvider.GetValue(bindingContext.ModelName);
        if (valueProviderResult == ValueProviderResult.None)
        {
            return Task.CompletedTask;
        }

        bindingContext.ModelState.SetModelValue(bindingContext.ModelName, valueProviderResult);
        var value = valueProviderResult.FirstValue;

        if (string.IsNullOrEmpty(value))
        {
            bindingContext.Result = ModelBindingResult.Success(null);
            return Task.CompletedTask;
        }

        // 尝试解析强类型ID（依赖StronglyTypedId生成的TryParse方法）
        if (PatientProfileId.TryParse(value, out var patientId))
        {
            bindingContext.Result = ModelBindingResult.Success(patientId);
        }
        else
        {
            bindingContext.ModelState.TryAddModelError(
                bindingContext.ModelName,
                $"无效的{nameof(PatientProfileId)}格式，需提供有效的Guid字符串");
            bindingContext.Result = ModelBindingResult.Failed();
        }

        return Task.CompletedTask;
    }
}

注册绑定器的两种方式 #

1. 属性标记强类型ID：

[StronglyTypedId]
[ModelBinder(typeof(PatientProfileIdModelBinder))]
public readonly partial struct PatientProfileId;

2. 全局注册绑定器（在Program.cs中）：

builder.Services.AddControllers(options =>
{
    options.ModelBinderProviders.Insert(0, new BinderTypeModelBinderProvider(typeof(PatientProfileIdModelBinder)));
});

方法二：全局异常处理中间件捕获转换异常 #

如果不想为每个强类型ID单独写绑定器，可通过全局中间件捕获参数转换时的异常，统一返回400响应：

app.Use(async (context, next) =>
{
    try
    {
        await next();
    }
    catch (FormatException ex)
    {
        // 判断是否为强类型ID的转换异常
        if (ex.Message.Contains(nameof(PatientProfileId)) || ex.TargetSite?.DeclaringType == typeof(PatientProfileId))
        {
            context.Response.StatusCode = StatusCodes.Status400BadRequest;
            context.Response.ContentType = "application/json";
            var errorResponse = new
            {
                type = "https://www.rfc-editor.org/rfc/rfc9110.html#name-400-bad-request",
                title = "Bad Request",
                status = 400,
                detail = $"无效的参数格式：{ex.Message}"
            };
            await context.Response.WriteAsJsonAsync(errorResponse);
        }
        else
        {
            // 其他FormatException按原有逻辑抛出
            throw;
        }
    }
});

注意：此中间件需放在app.MapControllers()或app.MapMinimalApi()之前，确保能捕获路由绑定阶段的异常。

方法三：单个端点手动处理参数验证 #

针对特定端点，手动从查询参数获取值并验证格式：

app.MapGet("/v1/test_results", async (
    HttpContext context,
    IValidator<GetTestResultsRequest> validator) =>
{
    var patientIdStr = context.Request.Query["PatientProfileId"].FirstOrDefault();
    PatientProfileId? patientId = null;
    
    if (!string.IsNullOrEmpty(patientIdStr))
    {
        if (!PatientProfileId.TryParse(patientIdStr, out var parsedId))
        {
            return Results.BadRequest($"无效的{nameof(PatientProfileId)}格式");
        }
        patientId = parsedId;
    }

    var request = new GetTestResultsRequest(patientId);
    var validationResult = await validator.ValidateAsync(request);
    
    if (!validationResult.IsValid)
    {
        return Results.BadRequest(validationResult.Errors.Select(e => e.ErrorMessage));
    }

    return await Handle(request, validator);
})
.WithName("GetTestResults");

关键说明 #

• 若StronglyTypedId未生成TryParse方法，需自行实现解析逻辑：判断输入是否为有效Guid，再转换为强类型ID。
• 优先使用自定义模型绑定器，它符合ASP.NET Core模型验证流程，能自动整合到框架的ModelState体系中，返回统一的400响应格式。

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