ASP.NET Core控制器返回List派生类时仅序列化基类内容的问题分析与解决

我之前碰到过一模一样的问题！当你的类继承自List<T>这类集合类型时，JSON序列化器（不管是ASP.NET Core默认的System.Text.Json，还是Newtonsoft.Json）都会优先把它当作集合来处理——只会序列化列表里的元素，完全忽略你添加的额外属性。

为什么会这样？ #

序列化器的逻辑是先检查对象是否实现了IEnumerable接口，一旦识别出来，就会走集合序列化的分支：遍历所有元素并输出，不会去扫描对象本身的其他属性。你的Derived<T>继承了List<T>，自然实现了IEnumerable<T>，所以序列化器直接把它当成普通列表处理了。

解决方案1：重构类结构（最推荐） #

其实从面向对象设计的角度来说，继承集合类并不是最佳实践（很容易违反里氏替换原则）。更好的方式是让你的类持有一个List<T>属性，而不是继承它：

class Derived<T> 
{
    public int AdditionalProperty { get; set; }
    // 用独立的属性保存列表元素
    public List<T> Items { get; set; } = new List<T>();
}

修改你的Action方法：

[HttpGet]
public Derived<string> MyActionMethod() {
    var results = new Derived<string> { AdditionalProperty = 123 };
    results.Items.Add("ABCD");
    results.Items.Add("EFGH");
    return results;
}

这样序列化后的结果就会完整包含所有属性：

{
  "AdditionalProperty": 123,
  "Items": ["ABCD", "EFGH"]
}

解决方案2：强制序列化器把对象当作普通类处理（针对System.Text.Json） #

如果你因为某些原因必须保留继承List<T>的结构，可以通过以下方式让System.Text.Json按普通对象序列化：

方法A：使用自定义类型解析器（.NET 6+） #

在Program.cs里全局配置Json选项，让序列化器把你的Derived<T>当作对象处理：

builder.Services.AddControllers()
    .AddJsonOptions(options =>
    {
        options.JsonSerializerOptions.TypeInfoResolverChain.Insert(0, new DefaultJsonTypeInfoResolver
        {
            Modifiers =
            {
                typeInfo =>
                {
                    // 匹配你的Derived<T>泛型类
                    if (typeInfo.Type.IsGenericType && 
                        typeInfo.Type.GetGenericTypeDefinition() == typeof(Derived<>))
                    {
                        // 强制标记为对象类型，而非集合
                        typeInfo.Kind = JsonTypeInfoKind.Object;
                    }
                }
            }
        });
    });

方法B：自定义JsonConverter #

写一个专门的转换器来手动控制序列化过程：

public class DerivedConverter<T> : JsonConverter<Derived<T>>
{
    public override Derived<T>? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
    {
        // 如果你需要反序列化，这里实现对应的逻辑
        throw new NotImplementedException("反序列化逻辑需按需实现");
    }

    public override void Write(Utf8JsonWriter writer, Derived<T> value, JsonSerializerOptions options)
    {
        // 先写入额外属性
        writer.WriteStartObject();
        writer.WriteNumber("AdditionalProperty", value.AdditionalProperty);
        // 再写入列表元素
        writer.WriteStartArray("Items");
        foreach (var item in value)
        {
            JsonSerializer.Serialize(writer, item, options);
        }
        writer.WriteEndArray();
        writer.WriteEndObject();
    }
}

然后在你的派生类上标记使用这个转换器：

[JsonConverter(typeof(DerivedConverter<string>))]
class Derived<string> : List<string> { public int AdditionalProperty { get; set; } }

解决方案3：针对Newtonsoft.Json（Json.NET） #

如果你项目用的是Newtonsoft.Json（比如ASP.NET Core 3.1及更早版本默认，或者手动配置的），只需给类添加[JsonObject]特性，就能强制序列化器把它当作普通对象处理：

[JsonObject]
class Derived<T> : List<T> { public int AdditionalProperty { get; set; } }

序列化后的结果会包含所有属性（包括List自带的Capacity、Count等）：

{
  "AdditionalProperty": 123,
  "Capacity": 4,
  "Count": 2,
  "Items": ["ABCD", "EFGH"]
}

如果不想序列化List自带的属性，可以用[JsonObject(MemberSerialization.OptIn)]，只标记需要序列化的属性：

[JsonObject(MemberSerialization.OptIn)]
class Derived<T> : List<T> 
{
    [JsonProperty]
    public int AdditionalProperty { get; set; }
    
    [JsonProperty]
    // 把当前集合转为列表输出
    public new List<T> Items => this.ToList();
}

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