FastEndpoints中路由参数类型定义的最佳实践

在使用FastEndpoints框架开发API时，正确设置路由参数的数据类型对于生成准确的客户端代码至关重要。本文将详细介绍如何确保路由参数在Swagger文档和生成的客户端代码中保持正确的数据类型。

问题背景

开发者在FastEndpoints框架中定义了一个接收Guid类型路由参数的端点，但在使用GenerateClientsAndExitAsync方法生成客户端代码时，发现路由参数被生成为string?类型，而非期望的Guid类型。这会导致客户端调用时需要额外的类型转换，影响开发体验。

解决方案

使用请求DTO定义路由参数类型

FastEndpoints框架的客户端代码生成依赖于Swagger文档的准确描述。为了确保路由参数在Swagger文档中被正确识别为Guid类型，最佳实践是使用请求DTO来明确定义参数类型：

sealed class RequestDto
{
    public Guid SomeId { get; set; }  // 明确指定参数为Guid类型
}

sealed class ResponseDto
{
    public string Id { get; set; }
}

sealed class GetSomeEndpoint : Endpoint<RequestDto, ResponseDto>
{
    public override void Configure()
    {
        Get("something/{SomeId}");
        AllowAnonymous();
    }

    public override async Task HandleAsync(RequestDto r, CancellationToken ct)
    {
        await SendAsync(new() { Id = r.SomeId.ToString() });
    }
}

工作原理

1. Swagger文档生成：当使用请求DTO时，FastEndpoints框架会根据DTO属性类型在Swagger文档中正确标注参数类型。对于Guid类型的属性，Swagger会生成相应的schema定义。

2. 客户端代码生成：基于正确的Swagger文档，客户端生成工具(如NSwag)能够识别参数应为Guid类型而非字符串类型，从而生成类型正确的客户端方法签名。

替代方案比较

虽然可以通过Route()方法在端点处理程序中获取Guid类型的路由参数，但这种方法不会影响Swagger文档的生成。因此，对于需要生成客户端代码的场景，使用请求DTO是更可靠的方法。

额外建议

1. 考虑使用Kiota客户端生成：FastEndpoints现在支持基于Kiota的客户端生成方案，它提供了更现代化的客户端生成体验，值得开发者评估使用。

2. 保持一致性：建议在整个项目中统一使用请求DTO来定义所有路由参数，以确保Swagger文档和客户端代码的一致性。

3. 文档注释：为DTO属性添加XML注释，这些注释会被包含在Swagger文档中，进一步提升API文档的质量。

通过遵循这些最佳实践，开发者可以确保FastEndpoints应用生成的路由参数类型在客户端代码中保持准确，提高开发效率和代码质量。