.NET Framework 4.8如何配置JsonPatchDocument解决接收参数为null问题

.NET Framework 4.8 搭载的ASP.NET Web API 2默认未内置JsonPatch请求的专用格式化器，即便安装了Newtonsoft.Json依赖包，也无法自动完成JsonPatchDocument的模型绑定，按以下步骤配置即可正常使用：

1. 校验已安装的NuGet包兼容性 #

确保项目安装的是适配.NET Framework的官方包，不要误装.NET Core/.NET 5+版本的同名包：

• 必须安装Microsoft.AspNet.WebApi.JsonPatch包，该包会自动安装匹配版本的Newtonsoft.Json依赖
• 确认项目中Microsoft.AspNet.WebApi.Core版本与JsonPatch包版本兼容，建议统一升级到最新稳定版
  注意：Microsoft.AspNetCore.JsonPatch是为ASP.NET Core设计的包，完全不兼容.NET Framework 4.8环境，安装后会出现各种绑定异常

2. 在Web API配置中注册专用格式化器 #

打开项目中的App_Start/WebApiConfig.cs文件，在Web API注册逻辑中添加JsonPatch格式化器配置，参考代码如下：

using System.Web.Http;
using System.Net.Http.Formatting;
using Newtonsoft.Json;
using Newtonsoft.Json.Serialization;
using Microsoft.AspNet.WebApi.JsonPatch.Formatting;

public static class WebApiConfig
{
    public static void Register(HttpConfiguration config)
    {
        // 保留原有路由、特性路由等配置
        config.MapHttpAttributeRoutes();
        config.Routes.MapHttpRoute(
            name: "DefaultApi",
            routeTemplate: "api/{controller}/{id}",
            defaults: new { id = RouteParameter.Optional }
        );

        // 替换默认JSON格式化器为Newtonsoft.Json实现
        config.Formatters.Remove(config.Formatters.JsonFormatter);
        var newtonsoftFormatter = new JsonMediaTypeFormatter
        {
            SerializerSettings = new JsonSerializerSettings
            {
                // 可根据自身业务需求调整序列化配置
                ContractResolver = new CamelCasePropertyNamesContractResolver(),
                DateFormatString = "yyyy-MM-dd HH:mm:ss",
                NullValueHandling = NullValueHandling.Ignore
            }
        };
        config.Formatters.Add(newtonsoftFormatter);

        // 核心配置：添加JsonPatch专用媒体类型格式化器
        // 该格式化器会自动识别Content-Type为application/json-patch+json的请求，完成JsonPatchDocument绑定
        config.Formatters.Add(new JsonPatchMediaTypeFormatter());
    }
}

3. 接口与请求的正确写法 #

• 接口Action需标记[HttpPatch]特性，JsonPatchDocument参数需标记[FromBody]，参考示例：

[HttpPatch]
public IHttpActionResult PatchUserInfo(int userId, [FromBody] JsonPatchDocument<UserUpdateDto> patchDoc)
{
    if (patchDoc == null) return BadRequest("无效的Patch文档");
    
    // 业务逻辑示例：查询原始数据、应用Patch、持久化
    var user = _userRepository.GetById(userId);
    patchDoc.ApplyTo(user, ModelState);
    // 可选：校验Patch应用后的模型状态
    if (!ModelState.IsValid) return BadRequest(ModelState);
    
    _userRepository.SaveChanges();
    return Ok(user);
}

• 发送Patch请求时必须携带正确的请求头：Content-Type: application/json-patch+json，若使用普通application/json头，专用格式化器不会触发解析，会直接导致参数为null
• 请求体需符合RFC 6902规范的Patch数组格式，示例：

[
  {"op": "replace", "path": "/nickname", "value": "新昵称"},
  {"op": "remove", "path": "/oldTag"},
  {"op": "add", "path": "/roles/-", "value": "admin"}
]

常见异常排查 #

• 如果配置后仍出现绑定null，先检查项目中是否有全局过滤器、自定义模型绑定器提前读取了Request.Body流：ASP.NET Web API中请求流默认只能读取一次，若前置逻辑读取后未将流位置重置到0，后续格式化器会读取到空内容导致绑定失败
• 检查Web.config中是否有自定义的JSON序列化模块覆盖了全局格式化器配置，若存在需调整模块加载顺序，保证JsonPatchMediaTypeFormatter被正确加载

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