.Net 5 API配置JsonProperty类属性后请求模型绑定为null的问题咨询

问题本质 #

你遇到的绑定失效现象，核心原因是使用的序列化标注和ASP.NET Core请求管道实际使用的序列化器不匹配，或是序列化服务的配置方式错误，并不是标注本身失效。
从你描述的「仅当请求体字段名和类属性名完全一致时才能正常解析」的症状可以判断：当前管道走的是默认的System.Text.Json序列化逻辑，你之前混用的跨序列化器标注、错误的Newtonsoft.Json配置都没有真正生效，导致自定义字段名匹配规则根本没有被加载。

分场景配置方法 #

.NET 5 的请求体反序列化有两种可选的序列化器，标注和配置完全独立，不能交叉混用：

场景1：使用内置默认的System.Text.Json（框架推荐，性能最优） #

这是.NET 5的默认序列化逻辑，不需要额外安装NuGet包，只要按规则配置即可：

• 标注规范：给类属性加System.Text.Json.Serialization命名空间下的[JsonPropertyName("自定义字段名")]，不能混用Newtonsoft.Json的[JsonProperty]标注，这个标注默认管道完全不识别
• 正确的类定义示例：

using System.Text.Json.Serialization;

public class TestData
{
    // 匹配请求体中的custom_field_1字段，而非属性名本身的Field1
    [JsonPropertyName("custom_field_1")]
    public string Field1 { get; set; }

    // 匹配请求体中的custom_field_2字段
    [JsonPropertyName("custom_field_2")]
    public int Field2 { get; set; }
}

• 全局自定义配置：如果需要调整序列化规则（比如大小写不敏感匹配、null值处理），可以在服务注册阶段配置JsonOptions：

// Startup.cs 中的ConfigureServices方法
services.AddControllersWithViews()
    .AddJsonOptions(options =>
    {
        // 示例：开启请求体字段大小写不敏感匹配
        options.JsonSerializerOptions.PropertyNameCaseInsensitive = true;
    });

场景2：使用Newtonsoft.Json做序列化（兼容老项目场景） #

如果有老项目依赖Newtonsoft的特殊序列化规则，需要按以下步骤配置，否则你之前加的AddNewtonsoftJson()是完全不生效的：

• 第一步：安装对应NuGet包Microsoft.AspNetCore.Mvc.NewtonsoftJson，只引用基础Newtonsoft.Json包是无法替换管道默认序列化器的
• 标注规范：给类属性加Newtonsoft.Json命名空间下的[JsonProperty("自定义字段名")]，不能混加System.Text.Json的标注
• 服务配置：必须把AddNewtonsoftJson()作为AddControllersWithViews()的链式调用方法，单独写一行服务注册是无法替换默认格式化程序的：

// Startup.cs 中的ConfigureServices方法
services.AddControllersWithViews()
    .AddNewtonsoftJson(options =>
    {
        // 这里可以配置Newtonsoft的全局序列化规则
        options.SerializerSettings.ContractResolver = new DefaultContractResolver();
    });

常见排查点 #

• 标注跨序列化器混用：用Newtonsoft的[JsonProperty]配System.Text.Json管道，或反过来用System.Text.Json的[JsonPropertyName]配Newtonsoft管道，都会导致标注完全失效
• Newtonsoft适配包缺失：想用Newtonsoft序列化却没安装Mvc层的适配包，仅安装核心Newtonsoft.Json库
• 配置方式错误：把AddNewtonsoftJson()作为独立的服务注册语句，没有挂载在控制器服务的配置链上，导致默认格式化程序没有被替换
• 基础类定义问题：TestData类没有无参构造函数，或属性缺少get/set访问器，这种情况哪怕字段名完全匹配，绑定结果也会是null
• 标注位置错误：把自定义名标注加在了私有字段上，而非公开属性上，默认序列化逻辑只会匹配带get/set访问器的公开属性

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