FastEndpoints项目中关于List子类作为响应DTO的实践指南

在FastEndpoints框架中，开发者有时会遇到将List子类作为响应DTO时集成测试失败的问题。本文将深入分析这一现象的原因，并提供最佳实践建议。

问题现象分析

当开发者尝试创建一个继承自List的自定义响应类时，例如：

internal class MyOperationResponse : List<SomeDTO>
{
    public MyOperationResponse(IEnumerable<SomeData> data) : base(data) { }
}

虽然在SwaggerUI中能正常返回JSON数组，但在集成测试中却会得到null结果。这种现象源于System.Text.Json(STJ)序列化器在反序列化时的行为特性。

根本原因

STJ序列化器在反序列化时需要找到目标类型的无参构造函数。当开发者提供的自定义响应类只包含带参数的构造函数时，STJ无法完成反序列化过程，导致测试中获取到null值。

解决方案比较

临时解决方案（不推荐）

如果确实需要继承List，可以添加无参构造函数：

internal class MyOperationResponse : List<SomeDTO>
{
    public MyOperationResponse() { }
    public MyOperationResponse(IEnumerable<SomeData> data) : base(data) { }
}

从FastEndpoints v5.21.2.19-beta版本开始，框架会明确抛出相关异常而非静默失败。

推荐解决方案（最佳实践）

更健壮的做法是采用组合而非继承的方式设计响应DTO：

internal class MyOperationResponse
{
    public List<SomeDTO> Items { get; set; } = new();
}

这种设计模式具有以下优势：

1. 扩展性强：可以轻松添加分页信息、时间戳等元数据
2. 语义明确：属性名称能更好地表达业务含义
3. 兼容性好：不会受序列化器特殊处理的影响
4. 类型安全：避免了List可能带来的意外方法暴露

框架设计考量

FastEndpoints作为现代化API框架，鼓励开发者遵循以下DTO设计原则：

1. 显式优于隐式：明确声明所有属性，避免继承带来的隐藏行为
2. 稳定接口：通过包装集合类型，为未来扩展预留空间
3. 序列化友好：确保DTO符合主流序列化器的基本要求

结论

虽然技术上可以通过添加无参构造函数解决List子类的序列化问题，但从API设计的长期可维护性考虑，建议开发者采用包装模式而非继承模式来设计集合类型的响应DTO。这种实践不仅解决了当前的技术问题，还为API的演进提供了更好的基础。

对于FastEndpoints用户，当遇到类似问题时，应当优先考虑重构DTO设计，而非依赖框架的特殊处理。良好的API设计习惯将显著降低后续维护成本，提高系统的整体质量。