FreeSql 中自定义类型处理器的高级应用指南

引言

在使用 ORM 框架进行开发时，经常会遇到需要特殊处理某些数据类型的情况。FreeSql 作为一款功能强大的 .NET ORM 框架，提供了 TypeHandler 机制来实现自定义类型处理。本文将深入探讨如何在 FreeSql 中实现基于属性的自定义类型映射，以及处理过程中可能遇到的各种技术挑战。

基础概念：FreeSql 的 TypeHandler

TypeHandler 是 FreeSql 提供的一种扩展机制，允许开发者自定义特定类型的数据库映射行为。通过实现 TypeHandler<T> 抽象类，开发者可以完全控制类型在数据库和应用程序之间的转换过程。

典型应用场景

1. 敏感数据加密存储（如密码、身份证号等）
2. 特殊格式数据的序列化/反序列化（如 JSON、XML）
3. 业务特定格式的转换（如金额单位转换）
4. 复杂对象的存储处理

问题背景与解决方案

在实际开发中，我们可能会遇到这样的需求：当某个属性标记了特定特性（如 [Hashed]）时，自动对该属性值进行哈希处理后再存储到数据库。这种基于属性的条件处理在 FreeSql 中不能直接通过全局 TypeHandler 实现。

推荐解决方案

FreeSql 官方推荐使用包装类型而非基础类型来实现自定义处理。例如，对于需要哈希处理的字符串，可以定义一个专门的 HashedString 类型：

public class HashedString
{
    public HashedString(string value) => this.Value = value;
    public string Value { get; set; }
}

然后注册对应的 TypeHandler：

FreeSql.Internal.Utils.TypeHandlers.TryAdd(
    typeof(HashedString), 
    new HashedHandler()
);

class HashedHandler : TypeHandler<HashedString>
{
    public override object Serialize(HashedString value) 
        => /* 哈希处理逻辑 */;
        
    public override HashedString Deserialize(object value) 
        => /* 反哈希处理逻辑 */;
        
    public override void FluentApi(ColumnFluent col) 
        => col.MapType(typeof(string)).StringLength(-1);
}

高级技巧与问题解决

1. API 序列化问题

当 HashedString 类型出现在 Web API 响应中时，默认会被序列化为对象结构。为了保持 API 的简洁性，可以采取以下方案：

方案一：自定义 JsonConverter

public class HashedStringConverter : JsonConverter<HashedString>
{
    public override HashedString Read(...) 
        => new HashedString(/* 从JSON读取 */);
        
    public override void Write(...) 
        => writer.WriteValue(value.Value);
}

方案二：重写 ToString 方法

在 HashedString 类中重写 ToString() 方法，返回原始值，这样在简单序列化场景下也能正常工作。

2. 查询表达式中的类型处理

在 LINQ 查询表达式中直接使用 new HashedString() 时，可能会遇到 TypeHandler 不触发的问题。可以通过以下 AOP 方式解决：

fsql.Aop.ParseExpression += (_, e) =>
{
    if (e.Expression.Type == typeof(HashedString) && 
        e.Expression.NodeType == ExpressionType.New)
    {
        var hashString = Expression.Lambda(e.Expression)
            .Compile().DynamicInvoke() as HashedString;
        e.Result = e.FreeParse(Expression.Constant(hashString, typeof(HashedString)));
    }
};

这段代码会在解析表达式树时，对新建的 HashedString 对象进行特殊处理，确保 TypeHandler 能够正确介入。

最佳实践建议

1. 避免使用基础类型作为 TypeHandler 的目标：如 string、int 等，这会影响全局处理，可能导致意想不到的副作用。

2. 保持包装类型的轻量级：自定义包装类型应尽可能简单，只包含必要的属性和转换逻辑。

3. 考虑序列化需求：如果类型会出现在 API 响应中，提前规划好序列化方案。

4. 文档化自定义类型：为团队编写清晰的文档，说明这些特殊类型的用途和使用方式。

5. 单元测试覆盖：确保自定义类型的各种使用场景（存储、查询、序列化等）都有充分的测试覆盖。

性能考量

使用包装类型和自定义 TypeHandler 会带来一定的性能开销，主要体现在：

1. 对象创建和销毁的成本
2. 序列化/反序列化的处理时间
3. 表达式树解析的额外处理

在性能敏感的场景下，建议进行基准测试，评估这种设计是否满足性能要求。对于高频访问的简单数据类型，有时直接在业务逻辑中进行处理可能是更高效的选择。

结论

FreeSql 的 TypeHandler 机制为开发者提供了强大的类型自定义能力，通过合理的包装类型设计和表达式处理，可以实现各种复杂的业务需求。虽然在某些特定场景下需要额外的工作（如 API 序列化），但这种设计保持了框架的灵活性和类型安全性。理解这些高级用法后，开发者可以更加自如地应对各种数据持久化场景中的特殊需求。