JSON数组转枚举列表时控制器DTO绑定为null的问题排查

核心原因 #

你遇到的问题根源在于：

• 请求载荷中SubscriptionSystems传递的是字符串形式的数字（如"1"、"3"），但DTO中对应的是枚举类型列表。
• 默认的JsonStringEnumConverter（无论System.Text.Json还是Newtonsoft.Json实现），仅支持两种枚举反序列化逻辑：要么是枚举的字符串名称（如"SYS_1"），要么是纯数字类型（如1、3），并不直接支持「字符串转数字再匹配枚举值」的场景。
• 当模型反序列化失败时，ASP.NET Core默认会将整个DTO置为null。

分场景解决方案 #

场景1：使用ASP.NET Core默认的System.Text.Json

需要同时启用「字符串枚举转换」和「允许从字符串读取数字」的配置：

方案A：局部属性配置

直接在DTO的枚举列表属性上添加特性：

using System.Text.Json.Serialization;

public class OperationSystemDTO
{
    public bool Status { get; set; }
    
    [JsonConverter(typeof(JsonStringEnumConverter))]
    [JsonNumberHandling(JsonNumberHandling.AllowReadingFromString)]
    public List<SubscriptionSystem> SubscriptionSystems { get; set; }
}

方案B：全局配置（推荐，避免重复加特性）

在Program.cs中全局配置JSON序列化规则：

builder.Services.AddControllers()
    .AddJsonOptions(options =>
    {
        // 启用字符串与枚举的转换
        options.JsonSerializerOptions.Converters.Add(new JsonStringEnumConverter());
        // 允许从字符串读取数字类型（包括枚举的数字值）
        options.JsonSerializerOptions.NumberHandling = JsonNumberHandling.AllowReadingFromString;
    });

场景2：使用Newtonsoft.Json（项目手动引用该库时）

若项目使用Newtonsoft.Json而非默认的System.Text.Json，需配置对应转换器并开启允许整数值的选项：

方案A：局部枚举配置

直接在枚举类型上添加特性：

using Newtonsoft.Json.Converters;

[Newtonsoft.Json.JsonConverter(typeof(StringEnumConverter), true)]
public enum SubscriptionSystem
{
    SYS_1 = 1,
    SYS_2 = 2,
    SYS_3 = 3
}

这里的true参数对应AllowIntegerValues，开启后转换器会识别字符串形式的数字并转换为对应枚举值。

方案B：全局配置

在Program.cs中全局配置Newtonsoft.Json的序列化规则：

builder.Services.AddControllers()
    .AddNewtonsoftJson(options =>
    {
        options.SerializerSettings.Converters.Add(new StringEnumConverter 
        { 
            AllowIntegerValues = true 
        });
    });

额外说明 #

如果不想修改序列化配置，也可以直接调整请求载荷：

• 将SubscriptionSystems改为纯数字数组：[1,3]
• 或改为枚举的字符串名称数组：["SYS_1","SYS_3"]
  两种调整都能让默认转换器正常工作。

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