如何实现ASP.NET Minimal API可选参数，支持单独覆盖默认值

问题分析 #

你遇到的核心问题是：使用[AsParameters]绑定复杂类型时，值类型参数（如int）默认被标记为必填，且引用类型参数会被模型绑定的null覆盖初始化默认值，导致必须传递所有参数才能正常请求。

解决方案 #

通过修改模型类的参数标记和属性逻辑，让所有参数变为可选，同时保留自定义默认值：

1. 修改PaginationParams类

给值类型参数添加[FromQuery(Required = false)]标记为可选，确保默认值生效：

public class PaginationParams
{
    private const int MaxPageSize = 50;

    // 标记为可选查询参数，默认值1
    [FromQuery(Required = false)]
    public int PageNumber { get; set; } = 1;

    private int _pageSize = 6;

    // 标记为可选查询参数，保留最大值限制逻辑
    [FromQuery(Required = false)]
    public int PageSize
    {
        get => _pageSize;
        set => _pageSize = value > MaxPageSize ? MaxPageSize : value;
    }
}

2. 修改MediaParams类

通过setter处理string类型的null覆盖问题，确保默认值不丢失：

public class MediaParams : PaginationParams
{
    private string _orderBy = "title";
    [FromQuery(Required = false)]
    public string OrderBy
    {
        get => _orderBy;
        set => _orderBy = value ?? "title";
    }

    private string _searchTerm = string.Empty;
    [FromQuery(Required = false)]
    public string SearchTerm
    {
        get => _searchTerm;
        set => _searchTerm = value ?? string.Empty;
    }

    private string _genres = string.Empty;
    [FromQuery(Required = false)]
    public string Genres
    {
        get => _genres;
        set => _genres = value ?? string.Empty;
    }
}

3. 端点代码保持不变

原有的端点逻辑无需修改，[AsParameters]会自动绑定传递的查询参数，未传递的参数保留默认值：

app.MapGet("/media/getby", async (
    [AsParameters] MediaParams pa,
    IMediator mediator,
    HttpContext context) =>
{
    var mediaListDto = await mediator.Send(new GetMediaByParamsQuery(pa));

    if (mediaListDto is not { Count: > 0 })
    {
        return Results.NotFound("No media was found by these params.");
    }
    context.Response.Headers.Add("Pagination", JsonSerializer.Serialize(mediaListDto.MetaData));
    return Results.Ok(mediaListDto);
});

效果验证 #

现在你可以灵活请求端点：

• 完全不传参：serveraddress/media/getby，所有属性使用默认值
• 传递单个参数：serveraddress/media/getby?OrderBy=rating，仅覆盖OrderBy，其余保留默认值
• 传递多个参数：serveraddress/media/getby?SearchTerm=pal&PageSize=20，覆盖指定参数，其余用默认值

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