FastEndpoints项目中Hashids集成方案解析

在FastEndpoints项目中集成Hashids时，开发者常常会遇到模型绑定和Swagger文档生成的挑战。本文将深入探讨如何优雅地解决这些问题，并提供一套完整的解决方案。

核心问题分析

Hashids是一种将数字ID转换为短哈希字符串的技术，主要应用于隐藏原始ID和防止枚举攻击。在FastEndpoints框架中集成时面临两大挑战：

1. 模型绑定问题：需要将请求中的哈希字符串转换为后端使用的整数ID
2. Swagger文档问题：需要正确显示这些字段为字符串类型而非数字类型

解决方案设计

自定义HashId结构体

最优雅的解决方案是创建一个专门的结构体来封装HashId逻辑：

public readonly struct HashId
{
    private static readonly Hashids _hid = new("your-salt-value");
    
    private readonly int _intValue;
    private readonly string _hashValue;

    public HashId(int value)
    {
        _intValue = value;
        _hashValue = _hid.Encode(value);
    }

    public HashId(string hash)
    {
        _hashValue = hash;
        _intValue = _hid.DecodeSingle(hash);
    }

    public static implicit operator int(HashId hashId) => hashId._intValue;
    public static implicit operator HashId(int value) => new(value);
    public static implicit operator HashId(string hash) => new(hash);
    public static implicit operator string(HashId hashId) => hashId._hashValue;
    
    public static bool TryParse(string input, out HashId result)
    {
        try
        {
            result = new HashId(input);
            return true;
        }
        catch
        {
            result = default;
            return false;
        }
    }
}

这个结构体提供了：

• 从整数到哈希字符串的转换
• 从哈希字符串到整数的转换
• 隐式转换操作符简化使用
• TryParse方法支持模型绑定

JSON转换器实现

为支持JSON序列化/反序列化，需要实现自定义JsonConverter：

public class HashIdConverter : JsonConverter<HashId>
{
    public override HashId Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
    {
        return new HashId(reader.GetString());
    }

    public override void Write(Utf8JsonWriter writer, HashId value, JsonSerializerOptions options)
    {
        writer.WriteStringValue((string)value);
    }
}

Swagger集成方案

FastEndpoints使用NSwag生成Swagger文档，可以通过操作处理器自定义文档生成：

public class HashIdOperationProcessor : IOperationProcessor
{
    public bool Process(OperationProcessorContext context)
    {
        foreach (var parameter in context.OperationDescription.Operation.Parameters)
        {
            if (IsHashIdType(parameter.Type))
            {
                parameter.Type = NJsonSchema.JsonObjectType.String;
                parameter.Format = null;
            }
        }
        
        return true;
    }

    private bool IsHashIdType(string typeName)
    {
        return typeName?.Contains("HashId") == true;
    }
}

注册到Swagger配置中：

services.AddSwaggerDocument(settings =>
{
    settings.OperationProcessors.Add(new HashIdOperationProcessor());
});

实际应用示例

在DTO中使用HashId类型：

public class GetProductRequest
{
    [JsonConverter(typeof(HashIdConverter))]
    public HashId ProductId { get; set; }
}

public class ProductEndpoint : Endpoint<GetProductRequest>
{
    public override void Configure()
    {
        Get("/products/{ProductId}");
        AllowAnonymous();
    }

    public override async Task HandleAsync(GetProductRequest req, CancellationToken ct)
    {
        int internalId = req.ProductId; // 隐式转换为int
        // 业务逻辑...
    }
}

最佳实践建议

1. 统一转换逻辑：所有HashId相关转换应集中在HashId结构体中
2. 错误处理：在TryParse和构造函数中添加适当的错误处理
3. 性能考虑：Hashids实例应静态化以避免重复初始化
4. 文档注释：为HashId结构体添加详细的XML注释
5. 测试覆盖：确保所有转换场景都有单元测试覆盖

总结

通过创建专门的HashId结构体并配合适当的转换器和Swagger处理器，可以在FastEndpoints项目中实现优雅的Hashids集成。这种方法不仅解决了模型绑定和文档生成的问题，还提供了类型安全和清晰的API设计。相比直接在属性上添加特性的方案，这种设计更加内聚且易于维护。