FreeSql 中虚谷数据库 Date 类型字段映射问题解析

在使用 FreeSql ORM 框架连接虚谷数据库(Xugu)时，开发者可能会遇到 Date 类型字段映射不正确的问题。本文将深入分析这一问题，并提供多种解决方案。

问题现象

当实体类中使用 DateTime 类型映射数据库的 date 类型字段时，查询结果会显示为当前时间而非数据库中存储的实际日期值。例如：

[Column(Name = "CSRQ", DbType = "date")]
public DateTime Csrq { get; set; }

这种情况下，查询返回的 Csrq 属性值总是当前时间，而不是数据库中的出生日期数据。

问题根源

经过分析，这个问题源于虚谷数据库驱动对 date 类型的处理方式与 FreeSql 的预期不一致。具体表现为：

1. 数据库驱动返回的日期数据格式可能不符合 .NET 的解析标准
2. 类型转换过程中存在信息丢失或格式不匹配
3. 虚谷数据库对 date 类型的实现可能有特殊之处

解决方案

方案一：使用字符串类型接收

最简单的解决方案是将实体类中的属性类型改为 string：

[Column(Name = "CSRQ", DbType = "date")]
public string Csrq { get; set; }

然后在业务逻辑层进行必要的格式转换。这种方式虽然简单，但会失去类型安全性。

方案二：使用自定义类型处理器

FreeSql 提供了 TypeHandler 机制，允许开发者自定义类型转换逻辑。我们可以创建一个专门处理虚谷数据库 date 类型的处理器：

public class XuguDateTypeHandler : TypeHandler<DateTime>
{
    public override DateTime Deserialize(object value)
    {
        if (value is string strValue)
        {
            return DateTime.ParseExact(strValue, "yyyy-MM-dd", CultureInfo.InvariantCulture);
        }
        return (DateTime)value;
    }

    public override object Serialize(DateTime value)
    {
        return value.ToString("yyyy-MM-dd");
    }
}

注册处理器：

FreeSql.Internal.Utils.TypeHandlers.TryAdd(typeof(DateTime), new XuguDateTypeHandler());

方案三：使用 DateOnly 类型

.NET 6+ 引入了 DateOnly 类型，更适合表示纯日期数据：

public class DateOnlyTypeHandler : TypeHandler<DateOnly>
{
    public override object Serialize(DateOnly value) => value.ToString("yyyy-MM-dd");
    
    public override DateOnly Deserialize(object value) => 
        DateOnly.TryParse(string.Concat(value), out var trydo) ? trydo : DateOnly.MinValue;
    
    public override void FluentApi(ColumnFluent col) => 
        col.MapType(typeof(string)).StringLength(12);
}

// 注册处理器
FreeSql.Internal.Utils.TypeHandlers.TryAdd(typeof(DateOnly), new DateOnlyTypeHandler());

// 实体类
public class Student
{
    [Column(Name = "CSRQ", DbType = "date")]
    public DateOnly Csrq { get; set; }
}

最佳实践建议

1. 优先使用 DateOnly：如果项目使用 .NET 6+，DateOnly 是最适合表示纯日期的类型
2. 统一格式处理：确保数据库、ORM 和业务层使用一致的日期格式
3. 添加日志记录：在类型处理器中添加日志记录，便于调试转换问题
4. 测试覆盖：为日期字段添加单元测试，验证各种边界情况

总结

虚谷数据库的 date 类型字段映射问题可以通过多种方式解决。开发者应根据项目需求和 .NET 版本选择最适合的方案。对于新项目，推荐使用 DateOnly 类型配合自定义类型处理器的方案，这既能保证类型安全，又能正确处理日期数据。