FreeSql 实体属性与 SQL 查询字段不匹配问题解析

问题背景

在使用 FreeSql 进行数据库操作时，开发者可能会遇到实体类属性与 SQL 查询返回字段不匹配的情况。具体表现为：实体类中定义了某个属性并标记了 Column 特性，但实际执行的 SQL 查询并未返回该字段，导致系统抛出异常。

问题复现

考虑以下场景：

public class Blogger
{
    [Column(Name = "id", IsIdentity = true)] 
    public int Id { get; set; }
    
    [Column(Name = "name")]
    public string Name { get; set; }
    
    [Column(Name = "fans_count")] 
    public int FansCount { get; set; }
    
    [Column(Name = "head_url")] 
    public string HeadUrl { get; set; }
}

// 执行查询
var cmd = "select id,name,fans_count from Blogger";
var result = fsql.Select<Blogger>().WithSql(cmd).ToList();

在这个例子中，Blogger 实体类定义了 HeadUrl 属性，但 SQL 查询只返回了 id、name 和 fans_count 三个字段。这种情况下，FreeSql 会尝试映射 HeadUrl 字段，但由于 SQL 查询结果中不存在该字段，导致映射失败。

问题原因分析

FreeSql 在执行 WithSql 方法时，会生成如下 SQL 语句：

SELECT a."id", a."name", a."fans_count", a."head_url" 
FROM (select id,name,fans_count from Blogger) a

可以看到，FreeSql 从实体类中获取了所有标记了 Column 特性的属性，并将它们包含在最终的 SELECT 语句中。然而，子查询并没有返回 head_url 字段，这就导致了字段不匹配的错误。

解决方案

方案一：使用 ToList("*") 方法

var result = fsql.Select<Blogger>().WithSql(cmd).ToList("*");

这种方法告诉 FreeSql 直接使用 SQL 查询返回的所有字段，而不尝试从实体类中获取所有字段。

方案二：使用 ADO.NET 直接查询

var result = fsql.Ado.Query<Blogger>(cmd);

对于简单的查询，直接使用 ADO.NET 接口可能更为合适，特别是当查询结果与实体类不完全匹配时。

方案三：创建专用 DTO

public class BloggerSimpleDto
{
    public int Id { get; set; }
    public string Name { get; set; }
    public int FansCount { get; set; }
}

var result = fsql.Select<BloggerSimpleDto>().WithSql(cmd).ToList();

为特定查询创建专用的 DTO 类，确保 DTO 属性与查询返回字段完全匹配。

最佳实践建议

1. 查询与实体分离：对于复杂查询，建议创建专门的 DTO 类，而不是直接使用实体类。

2. 明确字段映射：使用 WithSql 时，确保查询返回的字段与实体类中标记的字段完全匹配。

3. 谨慎使用 WithSql：除非需要进行复杂的 SQL 操作（如嵌套查询用于分页），否则考虑使用 FreeSql 的标准查询方法或直接使用 ADO.NET。

4. PostgreSQL 特殊注意事项：在 PostgreSQL 中，避免使用系统保留字（如 "user"）作为表名，必要时使用 Table 特性指定表名。

总结

FreeSql 提供了灵活的 SQL 查询方式，但在使用 WithSql 方法时需要特别注意实体类属性与查询返回字段的匹配问题。通过合理选择解决方案和遵循最佳实践，可以避免这类问题并提高代码的健壮性。对于简单的查询，直接使用 FreeSql 的标准查询方法通常是更好的选择；对于复杂查询，则可以考虑使用专用 DTO 或直接使用 ADO.NET 接口。