【ASP.NET Core】MVC模型绑定——实现同一个API方法兼容JSON和Form-data输入

在上一篇文章中，老周给大伙伴们大致说了下 MVC 下的模型绑定，今天咱们进行一下细化，先聊聊模型绑定中涉及到的一些组件对象。

------------------------------------------------------------------------------

一、ValueProvider——提取绑定源的值

首先登场的小帅哥是 ValueProvider，即实现 IValueProvider 接口。

public interface IValueProvider
{ 
    bool ContainsPrefix(string prefix);
    ValueProviderResult GetValue(string key);
}

提取绑定源的值在操作上类似字典对象的访问，通过一个指定的 key 来检索。这个主要针对数据结构类似字典的数据源，比如

1、HTTP Header，它的结构就是 name: value；

2、Form 对象，比如 HTML 页上的

元素，或者客户端直接提交的 form-data，当然包括用 JQuery 等方式提交的 form；

3、Route Value，也就是路由参数。比如咱们在写MVC时很熟悉的那个 {controller}/{action}，若访问的是 Home/Index，那么这里面就是两个数据项。第一个 key 是 controller，value 是 Home；第二个 key 是 action，value 是 Index。

于是，.net core 中很自然地会内置一些已实现的 provider。

FormValueProvider 
FormFileValueProvider
JQueryFormValueProvider 
RouteValueProvider 
HeaderValueProvider

看着它们的大名，估计你也能猜到它们的作用。你会问：咦，HeaderValueProvider 在哪，我咋没看到？这厮藏得比大 Boss 还深！它是在 HeaderModelBinder 文件中定义的私有类，所以我们根本访问不到它。

    private class HeaderValueProvider : IValueProvider

许多 ValueProvider 类型还有专配的 ValueProviderFactory，实现 IValueProviderFactory 接口。该接口只需实现一个方法：CreateValueProviderAsync。

public Task CreateValueProviderAsync(ValueProviderFactoryContext context)

返回值只是个 Task？那创建的 ValueProvider 实例放到哪？注意它有个参数是个上下文对象（ValueProviderFactoryContext），此对象有个属性叫 ValueProviders。创建的 ValueProvider 实例被添加到这个列表中。

也就是说，可以调用各个 Factory 对象创建多种 ValueProvider，然后都添加进 ValueProviders  列表中。当我们自己编写 ModelBinder 时，就可以从这个列表中的 N 个 ValueProvider 对象中提取值。这个 ValueProvider 的值会自动被合并，我们不需要关心它来自哪个 ValueProvider 对象。

比如，列表中有 QueryString 和 RouteValue 两个值来源，其中 key1 来自 QueryString，key2 来自 RouteValue，我在自定义 binder 时，不必管它从哪里来，我只要知道有两个键叫 key1、key2 就行。

    public Task BindModelAsync(ModelBindingContext bindingContext)
    {
        ……

        var modelName = bindingContext.ModelName;
        var valueProviderResult = bindingContext.ValueProvider.GetValue(modelName);
        if (valueProviderResult == ValueProviderResult.None)
        {
            ……
            return Task.CompletedTask;
        }

        var modelState = bindingContext.ModelState;
        modelState.SetModelValue(modelName, valueProviderResult);

        var metadata = bindingContext.ModelMetadata;
        var type = metadata.UnderlyingOrModelType;
        try
        {
            var value = valueProviderResult.FirstValue;

            object? model;
            if (string.IsNullOrWhiteSpace(value))
            {
                // Parse() method trims the value (with common NumberStyles) then throws if the result is empty.
                model = null;
            }
            else if (type == typeof(float))
            {
                model = float.Parse(value, _supportedStyles, valueProviderResult.Culture);
            }
            else
            {
                // unreachable
                throw new NotSupportedException();
            }

            // When converting value, a null model may indicate a failed conversion for an otherwise required
            // model (can't set a ValueType to null). This detects if a null model value is acceptable given the
            // current bindingContext. If not, an error is logged.
            if (model == null && !metadata.IsReferenceOrNullableType)
            {
                modelState.TryAddModelError(
                    modelName,
                    metadata.ModelBindingMessageProvider.ValueMustNotBeNullAccessor(
                        valueProviderResult.ToString()));
            }
            else
            {
                bindingContext.Result = ModelBindingResult.Success(model);
            }
        }
        catch (Exception exception)
        {
            ……
            
        }

        _logger.DoneAttemptingToBindModel(bindingContext);
        return Task.CompletedTask;
    }

以上是从源代码中抄来的一段，用于绑定 float 类型的 binder。

内部已经提供基础类型和复合类型的 Binder，所以一般情况下我们不需要自己花时间去写 Binder。

 

二、Binder 对象

binder 对象必须实现 IModelBinder 接口。这个接口只要求实现一个方法。

    Task BindModelAsync(ModelBindingContext bindingContext);

在这个方法的实现在，你要完成从数据源中提取值，然后产生绑定目标对象的过程。

例如，你的控制器类中有这么个方法（API方法）：

public Task UpdateStudent(Student stu)
{
    ……
}

假设这个 Student 类有 Name、Age、Email 三个属性，不管数据是通过 URL 查询字符串传递还是 form 提交，都需要提供这些值：

name=小明

age=21

[email protected]

于是，你的自定义 Binder 可以这样写

public class StudentBinder : IModelBinder
{
    public Task BindModelAsync(ModelBindingContext bindingContext)
    {
        // 提取值
        var valname = bindingContext.ValueProvider.GetValue("name");
        var valemail = bindingContext.ValueProvider.GetValue("email");
        var valage = bindingContext.ValueProvider.GetValue("age");
        // 剥出真实的值
        string? name;
        if(valname != ValueProviderResult.None)
        {
            name = valname.FirstValue;
        }
        int age;
        if(valage != ValueProviderResult.None)
        {
            _ = int.TryParse(valage.FirstValue, out age);
        }
        string? email;
        if(valemail != ValueProviderResult.None)
        {
            email = valemail.FirstValue;
        }
        // 实例化目标对象
        Student s = new()
        {
            Name = name,
            Age = age,
            Email = email
        };
        // 如果绑定成功，必须设置 Result
        bindingContext.Result = ModelBindingResult.Success(s);
    }
}

绑定的过程可以很简单，也可以弄得很复杂，主要看你的需求。bindingContext 对象的 Result 属性一定要设置，默认是绑定失败。传递给 ModelBindingResult.Success(s) 方法的参数就是目标对象。比如上面的，通过模型绑定的目标是给 Student 对象的属性赋值，所以传递的就是 Student 实例的引用。控制器方法 UpdateStudent 的参数就会引用这个 Student 实例，绑定完成。

其实上面的 Binder 我只是写着玩的，而且它只局限在 Student 类上，不能通用于所有类型。实际上咱们也不需写，我只是做演示。内置的 ComplexObjectModelBinder 类就能完成这项工作，而且它是通用于所有复合类型。

 

binder 写好了怎么用呢？这分为全局和局部。像上面例子这种特定于 Student 类型的 binder，最好还是局部应用——在 Student 类上通过特性类来关联。

[ModelBinder(typeof(StudentBinder))]
public class Student
{
    ……
}

不想写在类，也可以写在控制器方法的参数上。

public Task UpdateStudent([ModelBinder(typeof(StudentBinder))] Student stu)

 

三、ModelBinderProvider

如果你希望自定义的 binder 可以应用于全局，那你得实现 IModelBinderProvider 接口。这个接口只有一个方法：

IModelBinder? GetBinder(ModelBinderProviderContext context);

通过这个方法你会发现，ModelBinderProvider 的作用就是获取 binder 对象。

所以咱们上面那个例子，可以写一个 StudentBinderProvider 类，实现 GetBinder 方法，返回一个 binder 实例。

    return new StudentBinder();

既然是全局的，当然要在应用程序初始化时完成。在 Program.cs 文件中，通过 MvcOptions 对象来配置。

var builder = WebApplication.CreateBuilder();
builder.Services.AddControllers(opt =>
{
    opt.ModelBinderProviders.Insert(0, new StudentBinderProvider());
});
var app = builder.Build();

app.MapControllers();

app.Run();

不过，上面写的那个例子，应用到全局后容易翻车。因为所有 MVC 请求都会调用，而上面代码中咱们是把 StudentBinderProvider 对象放在列表的首位，只要有 MVC 请求，都会调用它来获取 binder，结果所有类型的绑定目标都会用 StudentBinder 来做绑定，不是 Student 类型的对象就无法绑定，获取不到数据源的值。

当然你可以做一下类型判断，不是 Student 的值接返回 null。这样运行时会转而尝试其他 ModelBinderProvider。

    public IModelBinder? GetBinder(ModelBinderProviderContext context)
    {

         if(context.Metadata.ModelType == typeof(Student))
         {
                 return new .....     
          }

          return null;
    }        

ModelBinderProvider 不需要放到依赖注入容器中，在配置 MVC 功能时会默认添加，自定义的可以用上面的方法通过 MvcOptions 添加。

        // Set up ModelBinding
        options.ModelBinderProviders.Add(new BinderTypeModelBinderProvider());
        options.ModelBinderProviders.Add(new ServicesModelBinderProvider());
        options.ModelBinderProviders.Add(new BodyModelBinderProvider(options.InputFormatters, _readerFactory, _loggerFactory, options));
        options.ModelBinderProviders.Add(new HeaderModelBinderProvider());
        options.ModelBinderProviders.Add(new FloatingPointTypeModelBinderProvider());
        options.ModelBinderProviders.Add(new EnumTypeModelBinderProvider(options));
        options.ModelBinderProviders.Add(new DateTimeModelBinderProvider());
        options.ModelBinderProviders.Add(new TryParseModelBinderProvider());
        options.ModelBinderProviders.Add(new SimpleTypeModelBinderProvider());
        options.ModelBinderProviders.Add(new CancellationTokenModelBinderProvider());
        options.ModelBinderProviders.Add(new ByteArrayModelBinderProvider());
        options.ModelBinderProviders.Add(new FormFileModelBinderProvider());
        options.ModelBinderProviders.Add(new FormCollectionModelBinderProvider());
        options.ModelBinderProviders.Add(new KeyValuePairModelBinderProvider());
        options.ModelBinderProviders.Add(new DictionaryModelBinderProvider());
        options.ModelBinderProviders.Add(new ArrayModelBinderProvider());
        options.ModelBinderProviders.Add(new CollectionModelBinderProvider());
        options.ModelBinderProviders.Add(new ComplexObjectModelBinderProvider());

        // Set up ValueProviders
        options.ValueProviderFactories.Add(new FormValueProviderFactory());
        options.ValueProviderFactories.Add(new RouteValueProviderFactory());
        options.ValueProviderFactories.Add(new QueryStringValueProviderFactory());
        options.ValueProviderFactories.Add(new JQueryFormValueProviderFactory());
        options.ValueProviderFactories.Add(new FormFileValueProviderFactory());

 

四、ModelBinderFactory

这个主要是实现  IModelBinderFactory 接口，此接口也要实现一个方法来创建 binder。

    IModelBinder CreateBinder(ModelBinderFactoryContext context);

内部默认的实现类为 ModelBinderFactory。这个 factory 是注册到依赖注入容器中的（单实例模式），它创建 binder 的依据是我们上面提到的各种 ModelBinderProvider，它就是调用了它们的 GetBinder 方法来获得 binder 的实例引用。

它会循环访问所有 provider，只要有一个 GetBinder 方法不返回 null，就算完成，然后就用这个 binder 来完成模型绑定。

        for (var i = 0; i < _providers.Length; i++)
        {
            var provider = _providers[i];
            result = provider.GetBinder(providerContext);
            if (result != null)
            {
                break;
            }
        }

这个类在获取 binder 实例后会把 binder 缓存，当下一次再用到时就直接从缓存里面获取，免去了多次 new 的时间消耗。请大伙伴们记住它的缓存功能，因为后文咱们在实现 API 同时支持 JSON 和 Form 提交时会因为它导致问题。

 

五、实现同一个API支持 JSON 和 form-data 正文

前面四个标题都是准备理论，现在咱们才正式开始干活。

老周想要这样一个功能：假设某API是 /demo/product/edit，调用时要 POST 数据，然后被 Product 类型的参数接收。客户端使用 json 提交可以，使用 form-data 提交也可以。

要实现这个，可以用自定义 Binder 的方式。我们不需要自己编写复杂的 binder，因为内置的有现成的：

1、当调用 API 时提交的是 JSON，使用 BodyModelBinder 就可以读出内容；

2、当调用 API 时提交的是 form-data，使用 ComplexObjectModelBinder 就能读出。

综合上述两条，老周有个大胆的想法，于是付诸大胆的行动。咱们自己写个 ModelBinderProvider。

public class CustMtFmtBinderProvider : IModelBinderProvider
{
    private readonly IModelBinderProvider bodybinderProvd;
    private readonly IModelBinderProvider complexobjbinderProvd;

    public CustMtFmtBinderProvider(BodyModelBinderProvider bdp, ComplexObjectModelBinderProvider cmplxprd)
    {
        bodybinderProvd = bdp;
        complexobjbinderProvd = cmplxprd;
    }

    public IModelBinder? GetBinder(ModelBinderProviderContext context)
    {
        HttpContext httpctx = context.Services.GetRequiredService()?.HttpContext;
        var request = httpctx.Request;
        IModelBinder binder;
        if(request.ContentType.StartsWith("multipart/form-data"))
        {
            binder = complexobjbinderProvd.GetBinder(context);
        }
        else
        {
            binder = bodybinderProvd.GetBinder(context);
        }
        return binder;
    }
}

两个类型的 binder 可以通过构造函数来传，因为是用 MvcOptions 来添加的，不是依赖住入，所以我们可以自己传参。原理老周相信大伙能懂，就是判断 HTTP 请求的 Content-Type，如果是 multipart/form-data，就用复合类型的 binder，否则，用 Body binder，它默认支持JSON，不，是只支持JSON。

上一段 BodyModelBinder 的源代码：

    public async Task BindModelAsync(ModelBindingContext bindingContext)
    {
        ……var formatter = (IInputFormatter?)null;
        for (var i = 0; i < _formatters.Count; i++)
        {
            if (_formatters[i].CanRead(formatterContext))
            {
                formatter = _formatters[i];
                ……
                break;
            }
            else
            {
                Log.InputFormatterRejected(_logger, _formatters[i], formatterContext);
            }
        }

        ……try
        {
            var result = await formatter.ReadAsync(formatterContext);

            if (result.HasError)
            {
                // Formatter encountered an error. Do not use the model it returned.
                _logger.DoneAttemptingToBindModel(bindingContext);
                return;
            }

            ……
    }

哟！这家伙并不是用 ValueProvider 来获取值的，而是使用 InputFormatter 读取的。上一篇水文中老周提过，当我们让控制器类用于 API 时，应用 [ApiController] 特性，它会把HTTP请求的整个 body 作为绑定源，并把模型绑定交给 InputFormatter 去处理。这里我们就看到真相了，就是 BodyModelBinder 搞的鬼，它调用了 Inputformatter。

Inputformatter 实现 IInputFormatter 接口，而运行库默认给应用注册的是 SystemTextJsonInputFormatter ，对于返回数据，则用的是 SystemTextJsonOutputFormatter 。关于返回的数据格式，老周前面也写过相关文章。

好了，回到主题，现在咱们的 BinderProvider 写好了，把它配置到 MvcOptions 对象中，成为全局的 binder 提供者。

var builder = WebApplication.CreateBuilder();
// 一定要注册这个
builder.Services.AddHttpContextAccessor();
builder.Services.AddControllers();
builder.Services.Configure(opt =>
{
    BodyModelBinderProvider bp = opt.ModelBinderProviders.OfType().FirstOrDefault()!;
    ComplexObjectModelBinderProvider cp = opt.ModelBinderProviders.OfType().FirstOrDefault()!;
    opt.ModelBinderProviders.Insert(0, new CustMtFmtBinderProvider(bp, cp));
});
var app = builder.Build();

我们那个 Provider 中用到 HttpContext ，要在服务容器上调用 AddHttpContextAccessor 方法注册一下，不然会报错（因为在 Provider 中默认没有引用 Httpcontext 相关的对象，但 ModelBinder 的上下文中可以访问）。

嗯，思路是没错的，这 Job 看起来很完美。下面咱们定义个模型类。

public class Cat
{
    public string Nickname { get; set; } = "";
    public string? Category { get; set; }
    public string Owner { get; set; } = "";
}

老周比较喜欢的两种动物：一种是喵喵，另一种是兔崽子。这里就定义个 Cat 类吧。

随后是 Controller。

[Route("cat")]
[ApiController]
public class CatController : Controller
{
    [HttpPost]
    [Route("new")]
    [Consumes("application/json", "multipart/form-data")]
public string NewCat(Cat cc)
    {
        if (cc.Nickname == "")
            return "你养了个寂寞";

        string m = $"你新养了一只猫，它叫 {cc.Nickname}";
        m += $"\n主人：{cc.Owner}\n品种：{cc.Category}";
        return m;
    }
}

Consumes 特性可以指定 API 方法支持哪些 content-type，当某个 action 有多个匹配方法时，还可以作为筛选方法的辅助依据。这里我就明确了两个类型—— application/json 和 multipart/form-data。

然而，但是，意外，没想到，运行之后就让人傻眼了。果然理想是花容月貌，现实是鬼妖当道。问题如下：

A、运行后，选用 form-data，测试成功；但改为 JSON 提交就不行了；

B、运行后，选用 JSON 测试，成功；但改为 form-data 提交就不行了。

总结一下，就是运行后，第一次调用是正确的，无论是 JSON 还是 FORM 都是可以的，但之后再调用 API 就不正确了。其实咱们这个示例的思路是没有错的，但这时候你怎么 debug 都无法解决。问题出在哪呢？

前文老周提示了一下，记得乎？在介绍 ModelBinderFactory 时强调了一下，这家伙在调用某个 ModelBinderProvider 成功获得 ModelBinder 后会将其缓存。本示例的问题就是出在这儿了。缓存对象是字典类型（ConcurrentDictionary），Key 的组成要素之一（另一个可能是 ControllerParameterDescriptor，描述方法的参数信息）就是模型绑定的元数据（ModelMetadata），而元数据是从模型类型产生的。在这个示例中，模型无论要使用 BodyModelBinder 还是 ComplexObjectModelBinder，它的模型都是 Cat 类（也是一样的参数），因此元数据是不变的。

假设使用 JSON 方式提交，当第一次调用后，自定义 ModelBinderProvider 返回的 binder （假设叫 X）会被缓存；然后改为用 form data 提交，调用时，会优先从缓存中查找，然后找到 X，最后又用了 X 来进行模型绑定，于是就错了（此次应该用 Y）。

幸好，这个问题是可以解决的。咱们调整一下思路，先自定义一个 binder，在这个 binder 里封装 BodyModelBinder 和 ComplexObjectModelBinder 对象，然后在执行绑定时，再动态选择用 body 还是用 complexobject。

于是，示例做以下调整：

先编写一个自定义的 binder。

public class CustBinder : IModelBinder
{
    private readonly BodyModelBinder _bodybinder;
    private readonly ComplexObjectModelBinder _objectbinder;

    public CustBinder(BodyModelBinder bodyb, ComplexObjectModelBinder objb)
    {
        _bodybinder = bodyb;
        _objectbinder = objb;
    }

    public async Task BindModelAsync(ModelBindingContext bindingContext)
    {
        // 通过 Content-Type 来区分
        var request = bindingContext.HttpContext.Request;
        if(request.ContentType!.StartsWith("multipart/form-data"))
        {
            await _objectbinder.BindModelAsync(bindingContext);
        }
        else
        {
            await _bodybinder.BindModelAsync(bindingContext);
        }
    }
}

这个自定义 Binder 中用到了另两个 Binder：Body 和 ComplexObject。通过构造函数两传递。在执行绑定时，通过请求的 ContentType 来判断，如果是 form-data，就用 ComplexObjectModelBinder，否则用 BodyModelBinder（直接调用它们的 BindModelAsync 方法就行了）。

补充：代码中在对象后面出现的“!”运算符，是告诉分析器“这个对象不会是null的，请放心”。在运行阶段无用处，只是在编译时不会有警告。

然后，再写一个 ModelBinderProvider。

public class CustFmtBinderProviderV2 : IModelBinderProvider
{
    private readonly MvcOptions options;
    public CustFmtBinderProviderV2(MvcOptions o)
    {
        options = o;
    }

    public IModelBinder? GetBinder(ModelBinderProviderContext context)
    {
        if (context == null)
            throw new ArgumentNullException(nameof(context));

        if (context.BindingInfo.BindingSource == null || context.BindingInfo.BindingSource.CanAcceptDataFrom(BindingSource.Body) == false)
            return null;

        BodyModelBinderProvider bodyprvd = options.ModelBinderProviders.OfType().FirstOrDefault()!;
        ComplexObjectModelBinderProvider objprvd = options.ModelBinderProviders.OfType().FirstOrDefault()!;
        // 创建 binder 实例
        IModelBinder? binder1 = bodyprvd.GetBinder(context);
        IModelBinder? binder2 = objprvd.GetBinder(context);
        // 两个 binder 都要用到，均不能为 null
        if(binder1 != null && binder2 != null)
        {
            return new CustBinder((BodyModelBinder)binder1, (ComplexObjectModelBinder)binder2);
        }

return null;
    }
}

BodyModelBinderProvider 和 ComplexObjectModelBinderProvider 从 MvcOptions 对象的 ModelBinderProviders 列表中获取。创建 CustBinder 实例时，把这两个 binder 传给它的构造函数。

经过这样处理之后，被 ModelBinderFactory 缓存的是 CustBinder 实例，哪怕在第二次以上调用时，都能正确进行 Content-Type 的分析，因为筛选的代码是写在 CustBinder 内部的，就算调用的是已缓存的实例也不影响其逻辑。

 

最后，Program.cs 文件那里也改一下。

var builder = WebApplication.CreateBuilder();
builder.Services.AddControllers();
builder.Services.Configure(opt =>
{
    opt.ModelBinderProviders.Insert(0, new CustFmtBinderProviderV2(opt));
});
var app = builder.Build();

 

测试一下，运行后，先以 form-data 输入。

POST /cat/new HTTP/1.1
User-Agent: PostmanRuntime/7.29.0
Accept: */*
Host: localhost:5168
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
Content-Type: multipart/form-data; boundary=--------------------------031532983200066969593455
Content-Length: 395
 
----------------------------031532983200066969593455
Content-Disposition: form-data; name="nickname"
豆豆
----------------------------031532983200066969593455
Content-Disposition: form-data; name="owner"
小王
----------------------------031532983200066969593455
Content-Disposition: form-data; name="category"
大狸花
----------------------------031532983200066969593455--
 
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Date: Thu, 24 Mar 2022 08:57:14 GMT
Server: Kestrel
Transfer-Encoding: chunked
 
你新养了一只猫，它叫 豆豆
主人：小王
品种：大狸花

通过，没问题。

接着，改为用 JSON 方式提交。

POST /cat/new HTTP/1.1
Content-Type: application/json
User-Agent: PostmanRuntime/7.29.0
Accept: */*
Host: localhost:5168
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
Content-Length: 84
 
{
"nickname": "豆豆",
"category": "大橘",
"owner": "赛冬瓜"
}
 
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Date: Thu, 24 Mar 2022 08:58:57 GMT
Server: Kestrel
Transfer-Encoding: chunked
 
你新养了一只猫，它叫 豆豆
主人：赛冬瓜
品种：大橘

嗯嗯嗯，效果不错吧。现在这个 API 既可以用 form-data 输入数据，也能用 JSON 输入数据了。咱们就不必把同一个 API 写两个版本了。