当前位置：首页 > news >正文

FreeSql 全面指南：从基础到高级实战，深入解析读写分离与导航属性

news 2026/2/8 22:57:26

FreeSql 使用详解：从入门到高级

FreeSql 是一个开源的、轻量级的 ORM 框架，它为 .NET 开发人员提供了丰富的功能，包括 CRUD 操作、读写分离、多租户、导航属性支持等。相比于 Entity Framework Core，FreeSql 在性能和特性上有一些独特的优势，特别是在复杂的数据库操作和分布式场景中。本文将详细介绍 FreeSql 的各个功能，从基本的 CRUD 操作开始，逐步深入到读写分离和导航属性等高级特性。

一、FreeSql 入门

1.1 FreeSql 的安装

首先，您需要在项目中安装 FreeSql。可以通过 NuGet 来安装 FreeSql 的包。

Install-Package FreeSql

或者使用 .NET CLI:

dotnet add package FreeSql

1.2 FreeSql 的初始化

初始化 FreeSql 通常需要通过 IFreeSql 接口来操作。最简单的初始化示例如下：

var fsql = new FreeSqlBuilder().UseConnectionString(DataType.MySql, "连接字符串").Build();

这里我们使用了 MySQL 数据库，你可以根据实际需求替换为其他数据库，例如：

DataType.SqlServer 用于 SQL Server
DataType.PostgreSQL 用于 PostgreSQL
DataType.Sqlite 用于 SQLite

1.3 基本的 CRUD 操作

FreeSql 提供了简洁的 API 来执行基本的增删改查操作。下面是简单的增删改查示例：

1.3.1 插入数据

var newUser = new User { Name = "张三", Age = 25 };
var insertedId = fsql.Insert(newUser).ExecuteIdentity();

1.3.2 查询数据

var user = fsql.Select<User>().Where(a => a.Id == 1).First();

1.3.3 更新数据

fsql.Update<User>().Set(a => a.Age, 26).Where(a => a.Id == 1).ExecuteAffrows();

1.3.4 删除数据

fsql.Delete<User>().Where(a => a.Id == 1).ExecuteAffrows();

二、FreeSql 进阶功能

2.1 查询优化

FreeSql 提供了丰富的查询功能和优化技巧，比如分页查询、多表查询等。

2.1.1 分页查询

分页查询在大多数应用中是必不可少的，FreeSql 提供了简单的 API 来执行分页查询：

var users = fsql.Select<User>().Page(1, 10).ToList();

2.1.2 多表查询

多表查询也是 ORM 框架中的重要特性。FreeSql 支持多种方式进行多表查询。

var query = fsql.Select<User, Order>().LeftJoin((u, o) => u.Id == o.UserId).Where((u, o) => u.Age > 18).ToList((u, o) => new { u.Name, o.OrderId });

2.2 事务管理

FreeSql 允许您在事务中执行多个数据库操作，确保数据一致性。

using (var transaction = fsql.CreateTransaction())
{try{fsql.Insert(new User { Name = "张三", Age = 30 }).ExecuteAffrows();fsql.Insert(new Order { UserId = 1, Amount = 100 }).ExecuteAffrows();transaction.Commit();}catch{transaction.Rollback();throw;}
}

三、FreeSql 高级特性

3.1 读写分离

FreeSql 内置了读写分离的功能，适用于分布式场景或主从数据库架构。你可以通过配置多个连接字符串来实现读写分离：

var fsql = new FreeSqlBuilder().UseMasterConnectionString("主库连接字符串").UseSlaveConnectionString("从库1连接字符串", "从库2连接字符串").Build();

UseMasterConnectionString 用于设置主库的连接字符串，所有写操作将会发送到主库。
UseSlaveConnectionString 用于配置从库的连接字符串，所有读操作将会发送到从库。

FreeSql 将自动在读操作和写操作之间进行切换，从而实现读写分离。读写分离能够极大地提高系统的性能，尤其是在读操作密集型的应用场景中。

3.2 导航属性

FreeSql 支持导航属性，这使得处理实体之间的关联关系变得非常方便。假设我们有两个实体 User 和 Order，它们之间是一对多的关系：

public class User
{public int Id { get; set; }public string Name { get; set; }[Navigate("UserId")]public List<Order> Orders { get; set; }
}public class Order
{public int Id { get; set; }public int UserId { get; set; }public decimal Amount { get; set; }[Navigate("UserId")]public User User { get; set; }
}

要查询带有导航属性的对象时，FreeSql 会自动加载关联的实体：

var userWithOrders = fsql.Select<User>().IncludeMany(a => a.Orders).Where(a => a.Id == 1).ToOne();

这种方式非常适合处理复杂的实体关系，避免了手动编写复杂的 SQL 语句。

3.3 缓存机制

FreeSql 提供了内置的缓存机制，可以将查询结果缓存起来，以减少数据库的访问次数，提升性能。

var cachedUser = fsql.Select<User>().Where(a => a.Id == 1).Cache(60, "user_cache") // 缓存 60 秒.First();

3.4 数据库审计

FreeSql 还支持数据库审计功能，可以自动跟踪实体的创建、更新和删除时间。你可以通过配置实体的审计属性来启用这一功能：

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

然后在 FreeSql 配置中启用审计功能：

fsql.Aop.AuditValue += (s, e) =>
{if (e.Property.Name == "CreatedTime" && e.Value == null)e.Value = DateTime.Now;if (e.Property.Name == "UpdatedTime")e.Value = DateTime.Now;
};

四、FreeSql 的最佳实践

合理使用缓存：对于频繁查询但数据变动不大的场景，可以启用 FreeSql 的缓存功能，减少数据库的压力。
使用读写分离：对于读多写少的系统，可以启用 FreeSql 的读写分离特性，提升读操作的性能。
合理设计导航属性：在处理复杂的数据库模型时，导航属性可以简化操作，但应注意防止循环依赖，必要时可进行懒加载处理。

五、总结

FreeSql 提供了强大的 ORM 功能，能够简化复杂的数据库操作，提升开发效率。本文从基本的 CRUD 操作开始，介绍了 FreeSql 的核心功能，包括读写分离、导航属性、缓存等高级特性。通过合理使用这些特性，您可以构建出高性能、可扩展的 .NET 应用。

希望这篇从入门到进阶的 FreeSql 指南能为您在开发中提供帮助。如果你想要进一步深入了解 FreeSql，建议查阅官方文档或社区资源，深入挖掘其更多高级功能。