FastEndpoints项目中请求DTO设计规范解析

背景概述

在FastEndpoints框架中，请求数据传输对象（Request DTO）的设计需要遵循特定规范。最新版本框架明确要求请求DTO必须包含至少一个公开可访问的属性，这一变更使得之前可能存在的隐性设计问题显性化。

问题本质

当开发者定义不包含任何公开属性的请求DTO时，框架会在运行时抛出NotSupportedException异常。这种设计限制源于框架底层对请求数据绑定的实现机制：

1. 数据绑定依赖公共属性作为映射目标
2. 开放API文档生成需要可描述的属性结构
3. 请求验证系统需要明确的验证目标

解决方案

标准解决方案

对于不需要接收任何请求参数的端点，框架提供了两种标准实现方式：

// 方案1：使用EmptyRequest占位符
sealed class MyEndpoint : Endpoint<EmptyRequest, ResponseDto>

// 方案2：使用无请求专用基类
sealed class MyEndpoint : EndpointWithoutRequest<ResponseDto>

设计建议

1. 最小属性原则：即使只需要单个参数，也应封装为DTO
2. 显式设计：避免使用无属性DTO这种隐式约定
3. 版本兼容：升级框架时注意检查DTO设计是否符合新规范

技术原理

框架实施这一限制的深层原因包括：

1. Swagger/OpenAPI兼容性：API文档生成需要可描述的schema
2. 序列化需求：JSON反序列化器需要明确的绑定目标
3. 验证管道：属性级验证需要明确的验证目标
4. 代码可维护性：显式设计优于隐式约定

最佳实践

1. 对于空请求体，始终使用框架提供的标准方案
2. 保持DTO设计的明确性和自描述性
3. 在项目早期建立DTO设计规范
4. 利用框架特性而非绕过框架约束

升级注意事项

从旧版本迁移时需特别注意：

1. 扫描项目中所有继承Endpoint<TRequest>的类
2. 检查TRequest是否包含至少一个公共属性
3. 将无属性请求转换为EmptyRequest或EndpointWithoutRequest方案
4. 更新相关单元测试和文档

通过遵循这些规范，可以确保代码的健壮性和框架特性的完整利用。