.NET开源ORM FreeSql常见问题和解决方法

FreeSql 是一个功能强大的 .NET 开源 ORM（对象关系映射）工具，支持多种数据库类型并提供丰富的功能特性。以下是使用 FreeSql 过程中常见的问题及其解决方法：

1. 数据库连接问题

问题描述：无法连接数据库，报错提示 Unable to connect to the database。

配置字符串错误或数据库驱动未正确安装。

解决方法：

检查连接字符串。确保连接字符串的格式正确，尤其注意用户权限、端口号和数据库名称。

代码示例（MySQL）：

var fsql = new FreeSqlBuilder()
    .UseConnectionString(DataType.MySql, "Server=127.0.0.1;Port=3306;Database=testdb;Uid=root;Pwd=123456;")
    .Build();

安装正确的数据库驱动。FreeSql 需要对应数据库的驱动程序。确保项目中安装了正确的 NuGet 包，例如：

验证数据库服务是否运行。确保数据库服务已启动，可以通过数据库客户端连接测试。

2. 查询性能较低

问题描述：查询复杂数据时，性能低于预期。大量数据查询时出现延迟。

解决方法：

使用延迟加载或分页查询，避免一次性加载大量数据，分页查询可以显著提高性能：

var pageData = fsql.Select<User>()
    .Page(1, 20) // 第 1 页，每页 20 条
    .ToList();

优化查询语句，使用 Include 或自定义 SQL 提高查询效率：

var usersWithOrders = fsql.Select<User>()
    .Include(u => u.Orders) // 预加载关联表
    .ToList();

启用查询缓存，对不频繁变化的数据，使用 FreeSql 的缓存功能：

var cachedData = fsql.Select<User>()
    .Cache(60) // 缓存 60 秒
    .ToList();

3. 实体类映射错误

问题描述：数据库表字段与实体类属性不匹配。查询时字段缺失或映射失败。

解决方法：检查实体类与数据库表的映射关系。

使用 Table 和 Column 特性手动配置映射：

[Table(Name = "users")]
public class User
{
    [Column(Name = "user_id")]
    public int Id { get; set; }

    [Column(Name = "user_name")]
    public string Name { get; set; }
}

自动映射配置。使用 FreeSqlBuilder 的 UseAutoSyncStructure 方法自动同步结构：

var fsql = new FreeSqlBuilder()
    .UseConnectionString(DataType.Sqlite, "Data Source=test.db")
    .UseAutoSyncStructure(true) // 自动同步表结构
    .Build();

4. 多对多关联查询问题

问题描述：多对多表之间的查询关系难以处理。

解决方法：

定义中间表实体。创建一个表示多对多关系的中间实体类：

public class UserRole
{
    public int UserId { get; set; }
    public int RoleId { get; set; }
}

使用导航属性。在主表中配置导航属性：

public class User
{
    public int Id { get; set; }
    public string Name { get; set; }

    [Navigate(ManyToMany = typeof(UserRole))]
    public List<Role> Roles { get; set; }
}

执行多对多查询。

var usersWithRoles = fsql.Select<User>()
    .IncludeMany(u => u.Roles)
    .ToList();

5. 更新/插入失败

问题描述：数据更新或插入时失败，提示 Primary key is required 或其他约束错误。

解决方法：

检查实体类主键设置。确保实体类有正确的主键配置：

public class User
{
    [Column(IsPrimary = true, IsIdentity = true)]
    public int Id { get; set; }

    public string Name { get; set; }
}

批量插入时处理主键。如果批量插入数据且主键是自增列，确保主键字段值为 0 或未设置：

var users = new List<User>
{
    new User { Name = "Alice" },
    new User { Name = "Bob" }
};

fsql.Insert(users).ExecuteAffrows();

事务支持。如果更新或插入需要事务支持，使用 FreeSql 的事务方法：

using (var transaction = fsql.CreateUnitOfWork())
{
    fsql.Insert(new User { Name = "TransactionTest" }).ExecuteAffrows();
    transaction.Commit();
}

6. 动态表名/多租户支持

问题描述：在多租户场景下，不同租户需要动态切换表名。

解决方法：

动态表名配置。使用 FreeSql 的 AsTable 方法动态修改表名：

var userList = fsql.Select<User>()
    .AsTable((type, oldName) => $"{oldName}_2024") // 动态表名
    .ToList();

全局租户表名前缀。在 FreeSqlBuilder 中设置：

var fsql = new FreeSqlBuilder()
    .UseConnectionString(DataType.MySql, "Server=127.0.0.1;Database=test;User=root;Password=123456;")
    .UseGlobalFilter((type, args) => type == typeof(User), (type, name) => $"tenant_{name}")
    .Build();

7. 日志与调试问题

问题描述：查询语句或执行逻辑调试困难。

解决方法：

启用调试日志。设置 UseMonitorCommand 查看 SQL 查询：

var fsql = new FreeSqlBuilder()
    .UseConnectionString(DataType.Sqlite, "Data Source=test.db")
    .UseMonitorCommand(cmd => Console.WriteLine(cmd.CommandText))
    .Build();

调试 LINQ 表达式。使用 ToSql 方法查看 LINQ 转换后的 SQL：

var sql = fsql.Select<User>().Where(u => u.Id > 10).ToSql();
Console.WriteLine(sql); // 输出生成的 SQL

通过以上技巧，可以更高效地使用 FreeSql。