FastEndpoints中FromClaims属性与自定义类型转换器的冲突问题解析

在使用FastEndpoints框架时，开发者可能会遇到一个特殊场景：当请求模型属性同时标记了[FromClaims]特性并使用自定义类型转换器时，会出现转换失败的问题。本文将深入分析这一现象的原因，并提供几种可行的解决方案。

问题现象分析

当开发者尝试在FastEndpoints中使用自定义类型（如强类型ID）作为请求模型的属性时，可能会观察到以下三种不同行为：

1. 普通属性：能够正常通过JSON反序列化工作
2. 标记FromClaims的属性（基础类型）：能够从声明中正确获取值
3. 标记FromClaims的属性（自定义类型）：抛出NullReferenceException异常

核心问题在于，FastEndpoints的声明绑定机制与STJ（System.Text.Json）的自定义转换器机制存在不兼容的情况。

根本原因

FastEndpoints的[FromClaims]特性绑定流程与标准的JSON反序列化流程是分离的。当框架从声明中提取值时：

1. 它不会走完整的STJ反序列化管道
2. 自定义的JsonConverter虽然被创建，但Read方法从未被调用
3. 框架尝试直接将声明中的字符串值赋给目标属性，导致类型不匹配

解决方案

方案一：实现TryParse方法

对于自定义类型，可以实现静态的TryParse方法，这是FastEndpoints原生支持的方式：

public record MyTypedId
{
    public Guid Value { get; init; }
    
    public static bool TryParse(string input, out MyTypedId result)
    {
        if(Guid.TryParse(input, out var guid))
        {
            result = new MyTypedId { Value = guid };
            return true;
        }
        result = null;
        return false;
    }
}

方案二：自定义值解析器

创建专门用于声明绑定的值解析器：

public class MyTypedIdParser : IValueParser<MyTypedId>
{
    public MyTypedId Parse(string input)
    {
        return new MyTypedId { Value = Guid.Parse(input) };
    }
}

然后在启动时注册：

app.UseFastEndpoints(c =>
{
    c.ParserFor<MyTypedId>(new MyTypedIdParser());
});

方案三：中间层转换

如果上述方案都不适用，可以在请求模型中保留原始类型，然后在业务逻辑层进行转换：

public record MyRequest
{
    [FromClaim("MyClaim")]
    public Guid RawId { get; init; }
    
    public MyTypedId TypedId => new() { Value = RawId };
}

最佳实践建议

1. 简单类型优先：对于直接从声明中获取的值，尽量使用基础类型
2. 业务逻辑转换：在业务层进行类型转换，保持请求模型的简洁性
3. 一致性原则：如果项目中大量使用强类型ID，统一采用TryParse方案

总结

FastEndpoints框架为了提高性能，对声明绑定采用了特殊处理流程，这导致其与STJ的自定义转换器机制不完全兼容。开发者需要根据具体场景选择合适的解决方案，在框架约束与类型安全之间找到平衡点。理解这一机制有助于更好地设计API契约和类型系统。