【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>元素，或者客户端直接提交的 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=abc@163.com
于是，你的自定义 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<IHttpContextAccessor>()?.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<MvcOptions>(opt =>
{
BodyModelBinderProvider bp = opt.ModelBinderProviders.OfType<BodyModelBinderProvider>().FirstOrDefault()!;
ComplexObjectModelBinderProvider cp = opt.ModelBinderProviders.OfType<ComplexObjectModelBinderProvider>().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<BodyModelBinderProvider>().FirstOrDefault()!;
ComplexObjectModelBinderProvider objprvd = options.ModelBinderProviders.OfType<ComplexObjectModelBinderProvider>().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<MvcOptions>(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 写两个版本了。