ASP.NET Web API如何复用参数类同时支持Query与Form绑定？

方案一：基类复用+派生类绑定特性 #

核心思路是将共享的属性和Swagger注释放在抽象基类，派生类仅添加对应的绑定特性，避免重复维护参数描述。

1. 定义抽象基类（仅保留属性和Swagger注释）

using Swashbuckle.AspNetCore.Annotations;

public abstract class BaseDetailsParameters
{
    [SwaggerParameter("NameParameterDescription")]
    public virtual string Name { get; set; }

    [SwaggerParameter("DescriptionParameterDescription")]
    public virtual string Description { get; set; }

    // 其他共享属性...
}

2. 创建两个派生类分别适配Query和Form绑定

using Microsoft.AspNetCore.Mvc;

// 适配GET查询参数
public class DetailsQueryParameters : BaseDetailsParameters
{
    [FromQuery(Name = "name")]
    public override string Name { get; set; }

    [FromQuery(Name = "description")]
    public override string Description { get; set; }

    // 重写其他属性并添加[FromQuery]...
}

// 适配POST表单参数
public class DetailsFormParameters : BaseDetailsParameters
{
    [FromForm(Name = "name")]
    public override string Name { get; set; }

    [FromForm(Name = "description")]
    public override string Description { get; set; }

    // 重写其他属性并添加[FromForm]...
}

3. 控制器中使用对应派生类

public class DetailsController : ControllerBase
{
    [HttpGet]
    public IActionResult GetDetails([FromQuery] DetailsQueryParameters detailsParameters)
    {
        // 业务逻辑
    }

    [HttpPost]
    public IActionResult AddDetails([FromForm] DetailsFormParameters detailsParameters)
    {
        // 业务逻辑
    }
}

方案二：自定义模型绑定器+Swagger过滤器 #

通过自定义绑定逻辑让同一个参数类自动适配GET/POST的参数来源，同时修改Swagger的参数显示规则。

1. 自定义模型绑定器

using Microsoft.AspNetCore.Mvc.ModelBinding;

public class QueryOrFormModelBinder : IModelBinder
{
    public Task BindModelAsync(ModelBindingContext bindingContext)
    {
        if (bindingContext == null)
            throw new ArgumentNullException(nameof(bindingContext));

        var httpContext = bindingContext.HttpContext;
        var modelType = bindingContext.ModelType;
        var model = Activator.CreateInstance(modelType);

        if (httpContext.Request.Method.Equals("GET", StringComparison.OrdinalIgnoreCase))
        {
            // 绑定查询参数
            foreach (var property in modelType.GetProperties())
            {
                var queryValue = httpContext.Request.Query[property.Name].FirstOrDefault();
                if (!string.IsNullOrEmpty(queryValue))
                {
                    property.SetValue(model, Convert.ChangeType(queryValue, property.PropertyType));
                }
            }
        }
        else if (httpContext.Request.Method.Equals("POST", StringComparison.OrdinalIgnoreCase) && httpContext.Request.HasFormContentType)
        {
            // 绑定表单参数
            foreach (var property in modelType.GetProperties())
            {
                var formValue = httpContext.Request.Form[property.Name].FirstOrDefault();
                if (!string.IsNullOrEmpty(formValue))
                {
                    property.SetValue(model, Convert.ChangeType(formValue, property.PropertyType));
                }
            }
        }

        bindingContext.Result = ModelBindingResult.Success(model);
        return Task.CompletedTask;
    }
}

2. 注册模型绑定提供器

// Program.cs/Startup.cs
builder.Services.AddControllers(options =>
{
    options.ModelBinderProviders.Insert(0, new QueryOrFormModelBinderProvider());
});

// 绑定提供器实现
public class QueryOrFormModelBinderProvider : IModelBinderProvider
{
    public IModelBinder GetBinder(ModelBinderProviderContext context)
    {
        if (context == null)
            throw new ArgumentNullException(nameof(context));

        if (context.Metadata.ModelType == typeof(DetailsParameters))
        {
            return new QueryOrFormModelBinder();
        }

        return null;
    }
}

3. 自定义Swagger操作过滤器修正参数显示

using Swashbuckle.AspNetCore.SwaggerGen;
using Microsoft.OpenApi.Models;

public class QueryOrFormSwaggerFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        if (operation.Parameters == null) return;

        var httpMethod = context.ApiDescription.HttpMethod;
        foreach (var param in operation.Parameters)
        {
            param.In = httpMethod.Equals("GET", StringComparison.OrdinalIgnoreCase) 
                ? ParameterLocation.Query 
                : ParameterLocation.FormData;
        }
    }
}

// 注册Swagger过滤器
builder.Services.AddSwaggerGen(c =>
{
    c.OperationFilter<QueryOrFormSwaggerFilter>();
    // 其他Swagger配置
});

4. 简化参数类（移除绑定特性）

using Swashbuckle.AspNetCore.Annotations;

public class DetailsParameters
{
    [SwaggerParameter("NameParameterDescription")]
    public string Name { get; set; }

    [SwaggerParameter("DescriptionParameterDescription")]
    public string Description { get; set; }

    // 其他属性...
}

5. 控制器直接使用参数类

public class DetailsController : ControllerBase
{
    [HttpGet]
    public IActionResult GetDetails(DetailsParameters detailsParameters)
    {
        // 业务逻辑
    }

    [HttpPost]
    public IActionResult AddDetails(DetailsParameters detailsParameters)
    {
        // 业务逻辑
    }
}

方案三：控制器方法级Swagger参数指定 #

适合参数数量较少的场景，直接在POST方法上通过Swagger特性强制指定参数来源。

1. 简化参数类（移除绑定特性）

using Swashbuckle.AspNetCore.Annotations;

public class DetailsParameters
{
    [SwaggerParameter("NameParameterDescription")]
    public string Name { get; set; }

    [SwaggerParameter("DescriptionParameterDescription")]
    public string Description { get; set; }

    // 其他属性...
}

2. 控制器方法中指定绑定和Swagger参数

using Swashbuckle.AspNetCore.Annotations;
using Microsoft.OpenApi.Models;

public class DetailsController : ControllerBase
{
    [HttpGet]
    public IActionResult GetDetails([FromQuery] DetailsParameters detailsParameters)
    {
        // 业务逻辑
    }

    [HttpPost]
    [SwaggerOperation(Parameters = new[] { 
        new OpenApiParameter { Name = "name", In = ParameterLocation.FormData, Description = "NameParameterDescription" },
        new OpenApiParameter { Name = "description", In = ParameterLocation.FormData, Description = "DescriptionParameterDescription" }
        // 其他参数依次添加
    })]
    public IActionResult AddDetails([FromForm] DetailsParameters detailsParameters)
    {
        // 业务逻辑
    }
}

内容的提问来源于stack exchange，提问作者Teddy G.