FastEndpoints中required属性在混合绑定源中的使用限制

在FastEndpoints框架中，使用C# 11引入的required修饰符与{ get; init; }组合来定义请求模型中的必填属性是一种常见的做法。然而，这种模式在混合绑定源(如同时从请求体和路由参数绑定)的情况下会出现预期之外的行为。

问题现象

当请求模型同时包含从不同来源绑定的属性时，例如：

• 从请求体JSON绑定的属性
• 从路由参数绑定的属性

如果这些属性都标记为required，框架会先尝试从请求体反序列化整个模型，此时会因缺少路由参数而报错，即使这些参数实际上会通过路由绑定提供。

技术原理分析

FastEndpoints的内部绑定机制会首先尝试通过JSON反序列化创建请求对象，然后再将路由参数等绑定到该对象上。System.Text.Json在反序列化时会严格检查required属性，如果请求体中缺少这些属性就会直接抛出异常，导致后续的路由参数绑定根本没有机会执行。

解决方案

方案一：忽略required关键字检查

可以通过自定义JsonSerializerOptions来全局忽略required关键字的检查：

app.UseFastEndpoints(c => c.Serializer.Options.IgnoreRequiredKeyword());

配合以下扩展方法实现：

static class StjExtensions
{
    internal static void IgnoreRequiredKeyword(this JsonSerializerOptions opts)
    {
        opts.TypeInfoResolver = opts.TypeInfoResolver?.WithAddedModifier(
            ti =>
            {
                if (ti.Kind != JsonTypeInfoKind.Object)
                    return;

                for (var i = 0; i < ti.Properties.Count; i++)
                {
                    var pi = ti.Properties[i];
                    if (pi.IsRequired)
                        pi.IsRequired = false;
                }
            });
    }
}

方案二：禁用nullable警告

对于不想使用required的情况，可以通过.editorconfig文件禁用特定文件的nullable警告：

[*.{Request,Response,Endpoint}.cs]
dotnet_diagnostic.CS8618.severity = none

最佳实践建议

1. 对于纯JSON绑定的模型，可以安全使用required修饰符
2. 对于混合绑定源的模型：
   • 如果坚持使用required，采用方案一的全局忽略方案
   • 或者不使用required，采用传统的非空初始化方式
3. 考虑将路由参数和请求体参数分离到不同的模型类中

框架设计思考

这个问题反映了现代C#特性与传统Web框架设计之间的微妙交互。required关键字的引入本意是提供编译时的空值安全，但在Web请求处理这种多阶段绑定的场景下，需要框架做出特殊处理才能完美配合。开发者需要理解这种底层机制才能写出符合预期的代码。