DBUtil 8.0.0-preview9

DBUtil（暂时仅支持 MySql）

一款轻量化操作数据库的类库，类DBHelper设计理念，比Dapper略重，比EntityFramework/FreeSql/SqlSugar轻。

特性亮点

DBUtil专为.NET开发者设计，提供简洁高效的数据库操作体验：

• 轻量级架构: 精简设计，避免过度封装带来的性能开销
• Lambda表达式支持: 原生支持Lambda语法，让代码更简洁直观
• 灵活SQL拼接: 创新的SQL片段生成功能，助力复杂查询拼接
• 完善事务管理: 丝滑般的事务控制体验，支持嵌套事务
• 分布式锁支持: 内置分布式锁机制，保障并发安全
• 树形数据处理: 原生支持CTE递归查询，轻松处理层级数据
• JSON深度支持: 强大的JSON操作能力，简化JSON数据处理
• 元数据管理: 提供完整的数据库元信息管理功能

安装配置

通过NuGet包管理器安装DBUtil核心库及对应数据库驱动：

# 安装核心库
dotnet add package DBUtil

# 根据数据库类型选择对应驱动（以MySQL为例）
dotnet add package DBUtil.Provider.MySql

# 支持的数据库类型
dotnet add package DBUtil.Provider.SqlServer  # SQL Server
dotnet add package DBUtil.Provider.PostgreSQL # PostgreSQL  
dotnet add package DBUtil.Provider.SQLite     # SQLite
dotnet add package DBUtil.Provider.Oracle     # Oracle

快速开始

1. 初始化数据库访问实例

using DBUtil;

// 创建数据库访问实例（建议使用单例模式）
var db = DBFactory.CreateDB("MySql", 
    "Server=127.0.0.1;Database=test;Uid=root;Pwd=123456;AllowLoadLocalInfile=true;SslMode=none;AllowPublicKeyRetrieval=True;Charset=utf8mb4;");

// 可选：注入扩展功能（ID生成、流水号、JSON扩展等）
// db.RemoveExtendFeatures(); // 移除扩展功能
// db.AddExtendFeatures();    // 注入扩展功能

2. 数据插入操作

无实体插入：

var insert = db.Insert("t_user", new[]
{
    new Dictionary<string, object> { { "name", "tom" }, { "age", 20 } },
    new Dictionary<string, object> { { "name", "lisa" }, { "age", 18 } },
    new Dictionary<string, object> { { "name", "jim" }, { "age", 18 } },
});

// 生成SQL：insert into `t_user`(`name`,`age`) values ('tom',20),('lisa',18),('jim',18);

有实体插入：

var insert = db.Insert<PersonEntity>().SetEntity(new[]
{
    new PersonEntity { Name = "jack", Age = 18, CreateTime = DateTime.Now, Sex = EnumSex.Male },
    new PersonEntity { Name = "tom", Age = 20, CreateTime = DateTime.Now, Sex = EnumSex.Male },
});

// 执行插入并返回插入的数据
var inserted = await insert.ExecuteInsertedAsync();

3. 数据更新操作

Lambda表达式更新：

var update = db.Update<PersonEntity>()
    .SetColumn("name", "tom")
    .SetColumn(i => i.Age, i => i.Age + 1)
    .SetColumn(i => i.Sex, EnumSex.Male)
    .Where(i => i.Id == 1);

await update.ExecuteAffrowsAsync();

4. 数据查询操作

多种查询方式：

// 查询DataTable
var dt = await db.SelectDataTableAsync("SELECT id,name,age FROM t_user LIMIT 10");

// 查询实体列表
var users = await db.SelectModelListAsync<UserEntity>(
    "SELECT id,name,age FROM t_user WHERE age > @age", 
    [db.CreatePara("age", 18)]
);

// 查询字典列表
var dics = await db.SelectDictionaryListAsync("SELECT id,name,age FROM t_user LIMIT 10");

// 条件查询实体
var person = await db.Select<PersonEntity>()
    .Where(i => i.Id == 1)
    .FirstAsync();

// 聚合查询
var stats = db.Select<PersonEntity>()
    .GroupBy(i => i.Age)
    .Having(i => i.Key > 18)
    .ToListAsync(i => new
    {
        Age = i.Key,
        Count = i.Length,
        Names = i.Join(i => i.Name, ",")
    });

5. 事务管理

await db.RunInTransactionAsync(async () =>
{
    // 业务逻辑代码
    await DoSomethingAsync();
    
    // 支持嵌套事务
    await db.RunInTransactionAsync(async () =>
    {
        await DoOtherThingAsync();
    });
});

6. 分布式锁

// 使用分布式锁保护关键代码段
await db.RunInLockAsync("order.process.lock", async () =>
{
    await ProcessOrderAsync();
});

7. ID与流水号生成

// 生成唯一ID
var id = await db.NewIdAsync("t_user", "id");

// 生成业务流水号
var sno = await db.NewSNOAsync("t_user", "sno", SerialFormat.CreateFast("Order_"));
// 流水号示例：Order_20250816000001

8. 批量数据导入

// 百万级数据批量导入
DataTable dt = GetDataTable(); // 准备好的数据
await db.BulkCopyAsync(dt, "t_user");

9. 树形数据查询（CTE）

// 查询树形结构数据
var tree = await db.SelectTree<AreaEntity>()
    .Where(i => i.Name == "郑州")
    .SetSpreedMode(EnumTreeSpreedMode.Both)
    .ToListAsync();

功能特性详解

实体配置

支持通过特性注解配置实体与数据库表的映射关系：

public class UserEntity
{
    [PrimaryKey]
    public int Id { get; set; }
    
    public string Name { get; set; }
    
    [JsonMap]
    public UserProfile Profile { get; set; }
    
    [ParentId]
    public int? ParentId { get; set; }
    
    [Children]
    public List<UserEntity> Children { get; set; }
}

SQL片段功能

创新的SQL片段生成器，简化复杂查询的拼接：

var sql = db.CaseSeg<UserEntity>(u => u.Status)
    .WhenSeg(u => u.Status == 1).Then("已激活")
    .WhenSeg(u => u.Status == 0).Then("未激活")
    .ElseSeg("未知状态")
    .EndAs("StatusText");

JSON操作支持

深度集成JSON操作能力：

// JSON属性包含判断
var hasPermission = user.Permissions.ContainsKey("admin");

// JSON数组操作
user.Roles.Add("new_role");
user.Roles.RemoveAt(0);

// JSON属性设置
user.Info.SetValue("last_login", DateTime.Now);

枚举类型处理

支持多种枚举存储方式：

• 数字存储：建议方式，数据库存储枚举值对应的数字
• 字符串存储：数据库存储枚举名称字符串
• JSON数组：复杂枚举场景使用JSON数组存储

性能表现

DBUtil经过优化，在以下场景表现出色：

文档与支持

详细文档请访问项目docs目录：

• 实体配置
• 插入操作
• 更新操作
• 保存操作
• 删除操作
• 基础查询
• 简单查询
• 事务管理
• 会话管理
• SQL片段
• 树形查询
• JSON支持
• 分布式锁
• ID与流水号
• 枚举处理
• 元数据管理
• 批量导入
• SQL监控
• 性能测试
• 日期处理

限制说明

本库专注于数据库操作，不提供以下功能：

1. CodeFirst：不提供根据实体自动创建表结构的功能
2. AOP支持：暂无AOP集成计划，支持SQL执行监控
3. 关系配置：不提供一对多、多对多的实体关系配置

许可证

本项目采用 MIT License 开源许可证。

贡献指南

欢迎提交Issue或Pull Request贡献代码：

1. Fork本项目
2. 创建特性分支
3. 提交代码更改
4. 发起合并请求

联系我们

• 项目地址：https://gitee.com/jackletter/DBUtil
• 问题反馈：https://gitee.com/jackletter/DBUtil/issues