FastEndpoints 项目中关于波浪符(~)路由问题的分析与修复

在 FastEndpoints 项目中，开发者最近发现了一个与 URL 路由相关的有趣问题。当尝试在路由路径中使用波浪符(~)时，虽然直接通过浏览器访问能够正常工作，但在 SwaggerUI 中执行请求时却会返回 404 错误。

问题背景

在 FastEndpoints 框架中，开发者通常会定义端点类来创建 API 路由。一个典型的端点类实现如下：

internal sealed class JWKSEndpoint : EndpointWithoutRequest<JWKSResponse>
{
    public override void Configure()
    {
        Get("~/.well-known/jwks");
        AllowAnonymous();
    }
    
    public override async Task HandleAsync(CancellationToken ct)
    {
        await SendAsync(new JWKSResponse(), cancellation: ct);
    }
}

这段代码定义了一个获取 JSON Web Key Set (JWKS) 的标准端点，按照规范使用了 ~/.well-known/jwks 路径。波浪符(~)在这个上下文中是一个有效的路径字符，常用于表示用户主目录或作为特殊前缀。

问题现象

开发者发现，虽然通过浏览器直接访问这个路由能够正常返回响应，但在 SwaggerUI 界面中执行相同的请求时却会返回 404 错误。这种不一致的行为表明框架在处理路由时存在特殊情况。

技术分析

经过深入调查，发现问题出在 SwaggerUI 集成部分。当 FastEndpoints 生成 OpenAPI/Swagger 文档时，对于包含波浪符(~)的路由路径处理不够完善。具体来说：

1. 路由系统本身能够正确处理波浪符，因此直接访问可以工作
2. 但 Swagger 文档生成器在解析和呈现这些特殊字符路径时存在缺陷
3. 这导致 SwaggerUI 生成的请求 URL 格式不正确，从而引发 404 错误

解决方案

FastEndpoints 团队在 v5.29.0.5-beta 版本中修复了这个问题。修复的核心在于：

1. 增强 Swagger 文档生成器对特殊字符路径的处理能力
2. 确保波浪符(~)在路由路径中被正确编码和传递
3. 保持与直接访问行为的一致性

最佳实践

对于开发者在使用 FastEndpoints 时的建议：

1. 当需要在路径中使用特殊字符时，考虑进行适当的编码
2. 更新到最新版本以获得最稳定的路由处理能力
3. 如果遇到类似问题，可以尝试在 SwaggerUI 和直接访问之间进行对比测试

总结

这个案例展示了 Web 框架在处理特殊字符路由时可能遇到的边缘情况。FastEndpoints 团队通过快速响应和修复，确保了框架在处理标准 JWKS 端点路径时的正确性，这对于实现 OAuth2/OpenID Connect 等安全协议非常重要。开发者现在可以放心地在路径中使用波浪符(~)等特殊字符，而不用担心 SwaggerUI 集成问题。