FreeSql 中处理 SQL 查询与实体属性不匹配的问题

在使用 FreeSql 进行数据库操作时，我们经常会遇到 SQL 查询返回的字段与实体类定义的属性不完全匹配的情况。本文将深入分析这个问题，并提供多种解决方案。

问题现象

当使用 FreeSql 的 WithSql 方法执行自定义 SQL 查询时，如果 SQL 返回的字段少于实体类中定义的属性（特别是那些标记了 [Column] 特性的属性），FreeSql 会抛出异常。

例如，我们有以下实体类：

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 = g.pgsql.Select<Blogger>().WithSql(cmd).ToList();

此时 FreeSql 会生成如下 SQL：

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

由于子查询中没有返回 head_url 字段，但外层查询却尝试选择它，导致数据库报错。

问题原因

FreeSql 的 WithSql 方法默认会尝试从实体类中获取所有标记了 [Column] 特性的属性，并将它们包含在最终的 SELECT 语句中。这种行为确保了实体对象能够被完整填充，但当 SQL 查询不返回某些字段时就会导致问题。

解决方案

方案一：指定查询字段

在调用 ToList 方法时显式指定要查询的字段：

var result = g.pgsql.Select<Blogger>()
    .WithSql(cmd)
    .ToList("*");  // 只查询SQL返回的字段

这种方法告诉 FreeSql 不要自动添加额外的字段，直接使用 SQL 查询返回的结果。

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

如果查询逻辑简单，不需要 FreeSql 的复杂功能，可以直接使用 ADO.NET：

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

这种方法更加灵活，完全按照 SQL 查询返回的结果映射到实体。

方案三：创建专用 DTO

为特定查询创建专用的数据传输对象（DTO），只包含查询返回的字段：

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

var result = g.pgsql.Ado.Query<BloggerDto>(cmd);

这种方法类型安全，且避免了不必要的字段映射。

方案四：修改实体类定义

如果某些字段在特定场景下可能不存在，可以将它们设为可空：

[Column(Name = "head_url")] 
public string? HeadUrl { get; set; }  // 注意问号表示可空

虽然这不能完全解决问题，但可以配合其他方案使用。

最佳实践建议

1. 明确查询需求：在设计查询时，明确知道需要哪些字段，避免查询过多不必要的数据。

2. 合理使用 WithSql：WithSql 最适合用于需要二次加工（如分页、复杂连接）的场景，简单查询直接使用 ADO.NET 可能更合适。

3. 实体类设计：为不同的查询场景设计不同的实体类或 DTO，避免一个实体类承担过多职责。

4. PostgreSQL 注意事项：在 PostgreSQL 中，避免使用 user 等保留字作为表名，可以使用 [Table(Name = "t_user")] 特性指定表名。

总结

FreeSql 提供了强大的 ORM 功能，但在处理自定义 SQL 查询时需要注意查询返回字段与实体属性的匹配问题。通过合理选择查询方法、设计专用 DTO 或调整实体定义，可以优雅地解决这类问题。理解 FreeSql 的内部机制有助于我们更好地利用其功能，同时避免常见的陷阱。