Sage.FreeSqlManager 1.0.0.4

Sage.FreeSqlManager

一个用于管理 FreeSql ORM 实例的 .NET 库，提供了工厂模式、单例模式、DI 注入集成、多租户支持和事务管理等功能，帮助开发者更高效地使用 FreeSql。

功能特点

• 工厂模式：通过工厂类集中管理 FreeSql 实例
• 单例模式：确保每个数据库连接只有一个 FreeSql 实例
• DI 注入集成：无缝集成到 ASP.NET Core 的依赖注入系统
• 多租户支持：提供全局过滤器和租户上下文管理
• 事务管理：支持方法级别的事务控制，提供六种传播方式
• 配置灵活：支持从配置文件或代码中配置数据库连接
• 读写分离：支持数据库读写分离配置
• 监控支持：提供 SQL 命令监控功能
• 支持 AOT 编译优化：兼容 .NET Native AOT 编译

安装

# 使用 NuGet 包管理器
Install-Package Sage.FreeSqlManager

# 或使用 .NET CLI
dotnet add package Sage.FreeSqlManager

快速开始

1. 在 appsettings.json 中配置数据库连接

{
  "DbConnections": {
    "Default": {
      "DataType": "MySql",
      "ConnectionString": "Data Source=localhost;Port=3306;User ID=root;Password=123456;Initial Catalog=test_db;Charset=utf8mb4;",
      "UseAutoSyncStructure": false,
      "UseNoneCommandParameter": true,
      "UseMonitorCommand": false,
      "EnableTenant": true,
      "CommandTimeout": 60
    },
    "SqlServerDb": {
      "DataType": "SqlServer",
      "ConnectionString": "Data Source=localhost;Initial Catalog=test_db;User Id=sa;Password=123456;"
    }
  }
}

2. 服务注册方式

2.1 多库模式（推荐）

using Sage.FreeSqlManager.Extensions;

var builder = WebApplication.CreateBuilder(args);

// 注册 FreeSql 工厂服务（多库模式）
builder.Services.AddFreeSqlFactory();

// 可选：添加仓储支持
builder.Services.AddFreeSqlRepositories(typeof(YourDbContext).Assembly);

var app = builder.Build();

app.Run();

2.2 单库模式（直接注入 IFreeSql）

using Sage.FreeSqlManager.Extensions;

var builder = WebApplication.CreateBuilder(args);

// 方式1：从配置文件读取
// builder.Services.AddFreeSql(builder.Configuration, "Default");

// 方式2：直接指定连接参数
// builder.Services.AddFreeSql(DataType.MySql, "连接字符串");

// 方式3：带事务支持的单库模式（推荐）
builder.Services.AddFreeSqlWithTransaction(builder.Configuration, "Default");

var app = builder.Build();

app.Run();

2.3 注册中间件

// 注册并使用多租户中间件
builder.Services.AddTenantMiddleware(options =>
{
    // 配置租户ID解析逻辑
    options.TenantIdResolver = async context =>
    {
        // 从请求头、查询参数或路由中解析租户ID
        if (context.Request.Headers.TryGetValue("X-Tenant-Id", out var tenantIdHeader))
        {
            if (long.TryParse(tenantIdHeader, out var tenantId))
            {
                return tenantId;
            }
        }
        return 0; // 返回0表示未指定租户
    };
    options.IsDevelopment = builder.Environment.IsDevelopment();
    options.DevDefaultTenantId = 1; // 开发环境默认租户ID
});

// 注册并使用事务中间件
builder.Services.AddTransactionMiddleware();

var app = builder.Build();

// 使用中间件（如果需要）
app.UseTransactionalMiddleware(); // 注意这里是UseTransactionalMiddleware，不是UseTransactionMiddleware
app.UseTenantMiddleware();

app.Run();

使用示例

基本用法

3.1 多库模式使用示例

using Sage.FreeSqlManager.Core;
using Sage.FreeSqlManager.Tenant;

public class UserService
{
    private readonly IFreeSqlFactory _freeSqlFactory;

    public UserService(IFreeSqlFactory freeSqlFactory)
    {
        _freeSqlFactory = freeSqlFactory;
    }

    public List<User> GetUsers()
    {
        // 获取默认数据库的 FreeSql 实例
        var fsql = _freeSqlFactory.GetFreeSql("Default");
        return fsql.Select<User>().ToList();
    }

    public List<Order> GetOrdersFromSqlServer()
    {
        // 获取指定数据库的 FreeSql 实例
        var fsql = _freeSqlFactory.GetFreeSql("SqlServerDb");
        return fsql.Select<Order>().ToList();
    }
}

3.2 单库模式使用示例

using FreeSql;

public class ProductService
{
    private readonly IFreeSql _freeSql;

    public ProductService(IFreeSql freeSql)
    {
        _freeSql = freeSql;
    }

    public async Task<List<Product>> GetAllProductsAsync()
    {
        return await _freeSql.Select<Product>().ToListAsync();
    }

    public async Task AddProductAsync(Product product)
    {
        await _freeSql.Insert(product).ExecuteAffrowsAsync();
    }
}

多租户使用示例

1. 实体类实现 ITenant 接口

using Sage.FreeSqlManager.Tenant;

public class User : ITenant
{
    public long Id { get; set; }
    public string Name { get; set; }
    public string Email { get; set; }
    
    // 必须实现的租户ID属性
    public long TenantId { get; set; }
}

2. 在控制器中使用租户

using Sage.FreeSqlManager.Core;
using Sage.FreeSqlManager.Tenant;

[ApiController]
[Route("[controller]")]
public class UserController : ControllerBase
{
    private readonly IFreeSqlFactory _freeSqlFactory;

    public UserController(IFreeSqlFactory freeSqlFactory)
    {
        _freeSqlFactory = freeSqlFactory;
    }

    [HttpGet]
    public IActionResult GetUsers()
    {
        // 自动应用当前租户过滤器
        var fsql = _freeSqlFactory.GetFreeSql("Default");
        var users = fsql.Select<User>().ToList(); // 只会查询当前租户的数据
        return Ok(users);
    }

    [HttpGet("cross-tenant")]
    public IActionResult GetUsersForTenant(long tenantId)
    {
        // 临时切换到指定租户
        using var tenantScope = _freeSqlFactory.CreateTenantScope("Default", tenantId);
        var users = tenantScope.FreeSql.Select<User>().ToList(); // 查询指定租户的数据
        return Ok(users);
    }
}

事务管理使用示例

使用 TransactionalAttribute 特性

using Sage.FreeSqlManager.Core;
using Sage.FreeSqlManager.Transaction;

public class OrderService
{
    private readonly IFreeSqlFactory _freeSqlFactory;

    public OrderService(IFreeSqlFactory freeSqlFactory)
    {
        _freeSqlFactory = freeSqlFactory;
    }

    // 使用事务特性装饰方法
    [Transactional]
    public void CreateOrder(Order order)
    {
        var fsql = _freeSqlFactory.GetFreeSql("Default");
        
        // 保存订单
        fsql.Insert(order).ExecuteAffrows();
        
        // 创建订单明细
        foreach (var item in order.Items)
        {
            item.OrderId = order.Id;
            fsql.Insert(item).ExecuteAffrows();
        }
        
        // 如果发生异常，所有操作都会回滚
    }

    // 自定义事务传播方式和隔离级别
    [Transactional(Propagation.RequiresNew, IsolationLevel.ReadCommitted)]
    public async Task<Order> CreateOrderAsync(Order order)
    {
        var fsql = _freeSqlFactory.GetFreeSql("Default");
        await fsql.Insert(order).ExecuteAffrowsAsync();
        return order;
    }
}

配置说明

DbConnectionConfig 配置项

事务传播方式

• Required: 如果当前存在事务，则加入该事务；否则创建一个新事务
• RequiresNew: 创建一个新事务，暂停当前事务（如果存在）
• Supports: 如果当前存在事务，则加入该事务；否则以非事务方式执行
• NotSupported: 以非事务方式执行，如果当前存在事务，则暂停该事务
• Mandatory: 必须在事务中执行，如果当前没有事务，则抛出异常
• Never: 必须在非事务方式执行，如果当前存在事务，则抛出异常

高级特性

读写分离配置

{
  "DbConnections": {
    "Default": {
      "DataType": "MySql",
      "ConnectionString": "主库连接字符串",
      "EnableReadWriteSeparation": true,
      "SlaveConnectionStrings": [
        "从库1连接字符串",
        "从库2连接字符串"
      ]
    }
  }
}

SQL 命令监控

{
  "DbConnections": {
    "Default": {
      "DataType": "MySql",
      "ConnectionString": "连接字符串",
      "UseMonitorCommand": true
    }
  }
}

启用后，所有 SQL 命令会输出到控制台和调试输出窗口。

手动创建 FreeSqlFactory

除了通过依赖注入方式使用，还可以手动创建 FreeSqlFactory：

using Sage.FreeSqlManager.Core;
using Sage.FreeSqlManager.Models;

// 创建连接配置字典
var connectionConfigs = new Dictionary<string, DbConnectionConfig>
{
    ["Default"] = new DbConnectionConfig
    {
        DataType = DataType.MySql,
        ConnectionString = "连接字符串",
        UseAutoSyncStructure = false
    }
};

// 手动创建工厂实例
var factory = new FreeSqlFactory(connectionConfigs);
var fsql = factory.GetFreeSql("Default");

仓储模式支持

// 1. 定义实体和仓储接口
public class User : ITenant
{
    public long Id { get; set; }
    public string Name { get; set; }
    public string Email { get; set; }
    public long TenantId { get; set; }
}

// 2. 在服务中使用仓储
public class UserService
{
    private readonly IBaseRepository<User> _userRepository;
    
    public UserService(IBaseRepository<User> userRepository)
    {
        _userRepository = userRepository;
    }
    
    public async Task<List<User>> GetAllUsersAsync()
    {
        return await _userRepository.Select.ToListAsync();
    }
}

服务注册方法对比

版本要求

• .NET 9.0 及以上版本
• FreeSql数据库系列 3.5.213 及以上版本

许可证

本项目采用 Apache 2.0 许可证。详情请参阅 LICENSE 文件。

贡献

欢迎提交问题报告和改进建议。如果您想贡献代码，请提交拉取请求。

作者

• LiuPengLai - 甲壳虫科技 欢迎提交问题和功能请求。 QQ Group: 1054304346