FastEndpoints中SnakeCaseLower序列化与查询参数绑定的问题解析

问题背景

在使用FastEndpoints框架时，开发者经常会遇到JSON序列化命名策略与模型绑定的兼容性问题。特别是当采用SnakeCaseLower命名策略时，查询参数在Swagger文档中的显示与实际请求处理时的绑定行为会出现不一致的情况。

核心问题表现

当开发者配置了以下设置时：

o.Serializer.Options.PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseLower;

会出现以下现象：

1. Swagger文档中显示的查询参数名称自动转换为蛇形命名（如comments_url）
2. 但实际请求时，框架无法正确绑定这些蛇形命名的参数到驼峰式属性（如CommentsUrl）
3. 必须使用[BindFrom("comments_url")]属性才能正常工作

技术原理分析

这一问题的根源在于ASP.NET Core的模型绑定机制与JSON序列化策略的差异：

1. JSON序列化策略：仅影响请求/响应体的序列化行为
2. 模型绑定机制：默认情况下，查询字符串参数的绑定不遵循JSON命名策略
3. Swagger集成：默认情况下会使用JSON命名策略生成文档

解决方案演进

FastEndpoints团队针对此问题提供了逐步完善的解决方案：

初始解决方案（v5.32.0.15-beta之前）

开发者需要手动为每个属性添加[BindFrom]特性，或者关闭Swagger文档中的命名策略转换：

.SwaggerDocument(o => o.UsePropertyNamingPolicy = false)

改进方案（v5.32.0.15-beta）

引入了新的配置选项，允许查询参数绑定也遵循JSON命名策略：

o.Binding.UsePropertyNamingPolicy = true;

最终稳定方案（v5.32.0.16-beta）

考虑到向后兼容性，该功能改为默认关闭，需要开发者显式启用：

o.Binding.UsePropertyNamingPolicy = true;

最佳实践建议

1. 统一命名策略：建议在整个项目中保持一致的命名策略（蛇形/驼峰）
2. 明确配置：根据项目需求显式设置UsePropertyNamingPolicy
3. 测试验证：在启用该功能后，全面测试所有端点以确保参数绑定正常
4. 文档一致性：确保Swagger文档与实际API行为保持一致

示例配置

以下是推荐的完整配置示例：

endpoints.MapFastEndpoints(o => {
    o.Serializer.Options.PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseLower;
    o.Binding.UsePropertyNamingPolicy = true; // 显式启用查询参数命名策略转换
    o.SwaggerDocument(o => o.UsePropertyNamingPolicy = true); // 保持文档一致性
});

总结

FastEndpoints框架通过灵活的配置选项，解决了JSON命名策略与查询参数绑定的兼容性问题。开发者现在可以根据项目需求，选择最适合的命名策略配置方式，既保持了代码的整洁性，又确保了API文档与实际行为的一致性。这一改进显著提升了开发体验，特别是在需要严格遵循特定命名规范的API项目中。