Ccxc.Core.DbOrm 包

Ccxc.Core.DbOrm 是一个基于 SqlSugar 的数据库 ORM 包，提供了数据库操作、缓存管理和实体映射等功能。该包封装了 SqlSugar 的核心功能，并集成了 Redis 缓存，为开发者提供了高性能的数据库访问解决方案。

SqlSugar 官方文档

本包基于 SqlSugar 构建，更多详细的 ORM 功能和用法请参考： SqlSugar 官方文档: https://www.donet5.com/home/doc

核心类

SqlBaseClient 类

SqlSugar 客户端的基础封装类，继承自 SqlSugarClient。

csharp

public class SqlBaseClient : SqlSugarClient

构造函数

csharp

public SqlBaseClient(string connStr, RedisCacheConfig cacheConfig, DbType dbtype)
public SqlBaseClient(string connStr, RedisCacheConfig cacheConfig, DbType dbtype, bool initKeyFromAttribute)
public SqlBaseClient(ConnectionConfig connConfig)

参数:

connStr (string): 数据库连接字符串
cacheConfig (RedisCacheConfig): Redis 缓存配置
dbtype (DbType): 数据库类型
initKeyFromAttribute (bool): 是否从特性初始化主键
connConfig (ConnectionConfig): SqlSugar 连接配置

属性

属性名	类型	描述
`ConnStr`	`string`	数据库连接字符串

方法

方法名	返回类型	描述
`GetDatabaseName()`	`string`	从连接字符串中提取数据库名称

MysqlClient<T> 抽象类

MySQL 数据库客户端的抽象基类，为特定实体类型提供数据库操作。

csharp

public abstract class MysqlClient<T> where T : class, new()

构造函数

csharp

public MysqlClient(string connStr, RedisCacheConfig cacheConfig)

参数:

connStr (string): MySQL 连接字符串
cacheConfig (RedisCacheConfig): Redis 缓存配置

属性

属性名	类型	描述
`Db`	`SqlBaseClient`	获取数据库客户端实例
`SimpleDb`	`SimpleClient<T>`	获取简化的数据库客户端

受保护字段

字段名	类型	描述
`ConnStr`	`string`	连接字符串
`IfInitKeyFromAttribute`	`bool`	是否从特性初始化主键
`CacheConfig`	`RedisCacheConfig`	缓存配置

方法

方法名	返回类型	描述
`GetDatabaseName()`	`string`	获取数据库名称
`InitTable()`	`void`	初始化数据表（CodeFirst）

缓存系统

RedisCache 类

实现 SqlSugar ICacheService 接口的 Redis 缓存服务。

csharp

public class RedisCache : ICacheService

构造函数

csharp

public RedisCache(RedisCacheConfig config, int defaultCacheDurationInSeconds = 86400)

参数:

config (RedisCacheConfig): Redis 缓存配置
defaultCacheDurationInSeconds (int): 默认缓存持续时间（秒），默认为86400秒（24小时）

属性

属性名	类型	描述
`Client`	`RedisClient`	获取 Redis 客户端实例

方法

方法名	返回类型	描述
`Add<V>(string, V)`	`void`	添加缓存项（使用默认过期时间）
`Add<V>(string, V, int)`	`void`	添加缓存项（指定过期时间）
`ContainsKey<V>(string)`	`bool`	检查缓存键是否存在
`Get<V>(string)`	`V`	获取缓存值
`GetAllKey<V>()`	`IEnumerable<string>`	获取所有缓存键
`GetOrCreate<V>(string, Func<V>, int)`	`V`	获取或创建缓存项
`Remove<V>(string)`	`void`	删除缓存项

RedisCacheConfig 类

Redis 缓存配置类。

csharp

public class RedisCacheConfig

属性

属性名	类型	描述
`RedisConnStr`	`string`	Redis 连接字符串
`RedisDatabase`	`int`	Redis 数据库编号

IDataCache 接口

数据缓存接口，提供异步缓存操作。

csharp

public interface IDataCache

方法

方法名	返回类型	描述
`Put(string, object, long)`	`Task`	存储对象到缓存
`PutString(string, string, long)`	`Task`	存储字符串到缓存
`Get<T>(string)`	`Task<T>`	获取缓存对象
`GetString(string)`	`Task<string>`	获取缓存字符串
`PutAll(string, IDictionary<string, object>, long)`	`Task`	批量存储到哈希缓存
`GetFromPk<T>(string, string)`	`Task<T>`	根据主键从哈希缓存获取
`GetHashKeys<T>(string)`	`Task<List<(string, T)>>`	获取哈希缓存所有键值对
`GetAll<T>(string)`	`Task<List<T>>`	获取哈希缓存所有值
`Delete(string)`	`Task`	删除缓存键
`Delete(string, string)`	`Task`	删除哈希缓存字段
`GetHashLength(string)`	`Task<long>`	获取哈希缓存长度

数据库特性

DbTableAttribute 特性

数据表映射特性，继承自 SqlSugar.SugarTable。

csharp

[AttributeUsage(AttributeTargets.Class, AllowMultiple = true, Inherited = true)]
public class DbTableAttribute : SqlSugar.SugarTable

构造函数

csharp

public DbTableAttribute(string tableName)
public DbTableAttribute(string tableName, string tableDescription)

参数:

tableName (string): 数据表名称
tableDescription (string): 数据表描述

属性

属性名	类型	描述
`RecordTableName`	`string`	记录表名称（用于审计或历史记录）

DbColumnAttribute 特性

数据列映射特性，继承自 SqlSugar.SugarColumn。

csharp

[AttributeUsage(AttributeTargets.Property, AllowMultiple = true)]
public class DbColumnAttribute : SqlSugar.SugarColumn

使用示例

基本实体定义

csharp

[DbTable("users", "用户表")]
public class User
{
    [DbColumn(IsPrimaryKey = true, IsIdentity = true)]
    public int Id { get; set; }

    [DbColumn(ColumnName = "username", Length = 50)]
    public string Username { get; set; }

    [DbColumn(ColumnName = "email", Length = 100)]
    public string Email { get; set; }

    [DbColumn(ColumnName = "password_hash", Length = 255)]
    public string PasswordHash { get; set; }

    [DbColumn(ColumnName = "created_at")]
    public DateTime CreatedAt { get; set; }

    [DbColumn(ColumnName = "updated_at")]
    public DateTime UpdatedAt { get; set; }

    [DbColumn(ColumnName = "is_active")]
    public bool IsActive { get; set; }
}

创建数据访问层

csharp

public class UserRepository : MysqlClient<User>
{
    public UserRepository(string connStr, RedisCacheConfig cacheConfig) 
        : base(connStr, cacheConfig)
    {
    }

    // 获取所有用户
    public async Task<List<User>> GetAllUsersAsync()
    {
        return await Db.Queryable<User>().ToListAsync();
    }

    // 根据ID获取用户
    public async Task<User> GetUserByIdAsync(int id)
    {
        return await Db.Queryable<User>()
            .Where(u => u.Id == id)
            .FirstAsync();
    }

    // 根据用户名获取用户
    public async Task<User> GetUserByUsernameAsync(string username)
    {
        return await Db.Queryable<User>()
            .Where(u => u.Username == username)
            .FirstAsync();
    }

    // 创建用户
    public async Task<int> CreateUserAsync(User user)
    {
        user.CreatedAt = DateTime.Now;
        user.UpdatedAt = DateTime.Now;
        return await Db.Insertable(user).ExecuteReturnIdentityAsync();
    }

    // 更新用户
    public async Task<bool> UpdateUserAsync(User user)
    {
        user.UpdatedAt = DateTime.Now;
        return await Db.Updateable(user).ExecuteCommandHasChangeAsync();
    }

    // 删除用户
    public async Task<bool> DeleteUserAsync(int id)
    {
        return await Db.Deleteable<User>()
            .Where(u => u.Id == id)
            .ExecuteCommandHasChangeAsync();
    }

    // 分页查询用户
    public async Task<(List<User> data, int total)> GetUsersPagedAsync(int page, int size)
    {
        RefAsync<int> total = 0;
        var data = await Db.Queryable<User>()
            .Where(u => u.IsActive)
            .OrderBy(u => u.CreatedAt, OrderByType.Desc)
            .ToPageListAsync(page, size, total);
        
        return (data, total.Value);
    }
}

使用 SimpleDb 简化操作

csharp

public class UserSimpleRepository : MysqlClient<User>
{
    public UserSimpleRepository(string connStr, RedisCacheConfig cacheConfig) 
        : base(connStr, cacheConfig)
    {
    }

    // 获取所有用户
    public async Task<List<User>> GetAllAsync()
    {
        return await SimpleDb.GetListAsync();
    }

    // 根据ID获取用户
    public async Task<User> GetByIdAsync(int id)
    {
        return await SimpleDb.GetByIdAsync(id);
    }

    // 插入用户
    public async Task<bool> InsertAsync(User user)
    {
        return await SimpleDb.InsertAsync(user);
    }

    // 更新用户
    public async Task<bool> UpdateAsync(User user)
    {
        return await SimpleDb.UpdateAsync(user);
    }

    // 删除用户
    public async Task<bool> DeleteAsync(int id)
    {
        return await SimpleDb.DeleteByIdAsync(id);
    }
}

配置和初始化

csharp

// 配置
var connStr = "Server=localhost;Database=testdb;User=root;Password=123456;";
var cacheConfig = new RedisCacheConfig
{
    RedisConnStr = "localhost:6379",
    RedisDatabase = 0
};

// 创建仓储
var userRepo = new UserRepository(connStr, cacheConfig);

// 初始化表结构（CodeFirst）
userRepo.InitTable();

// 使用仓储
var users = await userRepo.GetAllUsersAsync();
var user = await userRepo.GetUserByIdAsync(1);

缓存使用示例

csharp

public class UserCacheService
{
    private readonly RedisCache _cache;
    private readonly UserRepository _userRepo;

    public UserCacheService(RedisCacheConfig config, UserRepository userRepo)
    {
        _cache = new RedisCache(config);
        _userRepo = userRepo;
    }

    public async Task<User> GetUserWithCacheAsync(int userId)
    {
        var cacheKey = $"user:{userId}";
        
        // 尝试从缓存获取
        var cachedUser = _cache.Get<User>(cacheKey);
        if (cachedUser != null)
        {
            return cachedUser;
        }

        // 从数据库获取
        var user = await _userRepo.GetUserByIdAsync(userId);
        if (user != null)
        {
            // 缓存30分钟
            _cache.Add(cacheKey, user, 1800);
        }

        return user;
    }

    public User GetOrCreateUserCache(int userId)
    {
        var cacheKey = $"user:{userId}";
        
        return _cache.GetOrCreate(cacheKey, () =>
        {
            // 这里应该是同步方法，或者使用 GetAwaiter().GetResult()
            return _userRepo.GetUserByIdAsync(userId).GetAwaiter().GetResult();
        }, 1800); // 缓存30分钟
    }

    public void RemoveUserCache(int userId)
    {
        var cacheKey = $"user:{userId}";
        _cache.Remove<User>(cacheKey);
    }
}

复杂查询示例

csharp

public class UserAdvancedRepository : MysqlClient<User>
{
    public UserAdvancedRepository(string connStr, RedisCacheConfig cacheConfig) 
        : base(connStr, cacheConfig)
    {
    }

    // 条件查询
    public async Task<List<User>> SearchUsersAsync(string keyword, bool? isActive = null)
    {
        var query = Db.Queryable<User>();

        if (!string.IsNullOrEmpty(keyword))
        {
            query = query.Where(u => u.Username.Contains(keyword) || u.Email.Contains(keyword));
        }

        if (isActive.HasValue)
        {
            query = query.Where(u => u.IsActive == isActive.Value);
        }

        return await query.OrderBy(u => u.CreatedAt, OrderByType.Desc).ToListAsync();
    }

    // 统计查询
    public async Task<Dictionary<string, int>> GetUserStatisticsAsync()
    {
        var stats = new Dictionary<string, int>();

        stats["total"] = await Db.Queryable<User>().CountAsync();
        stats["active"] = await Db.Queryable<User>().Where(u => u.IsActive).CountAsync();
        stats["inactive"] = await Db.Queryable<User>().Where(u => !u.IsActive).CountAsync();

        return stats;
    }

    // 批量操作
    public async Task<bool> BatchUpdateStatusAsync(List<int> userIds, bool isActive)
    {
        return await Db.Updateable<User>()
            .SetColumns(u => new User { IsActive = isActive, UpdatedAt = DateTime.Now })
            .Where(u => userIds.Contains(u.Id))
            .ExecuteCommandHasChangeAsync();
    }

    // 事务操作
    public async Task<bool> TransferUsersAsync(List<User> usersToUpdate)
    {
        try
        {
            Db.BeginTran();

            foreach (var user in usersToUpdate)
            {
                await Db.Updateable(user).ExecuteCommandAsync();
            }

            Db.CommitTran();
            return true;
        }
        catch (Exception)
        {
            Db.RollbackTran();
            throw;
        }
    }
}

数据库初始化示例

csharp

public class DatabaseInitializer
{
    private readonly string _connStr;
    private readonly RedisCacheConfig _cacheConfig;

    public DatabaseInitializer(string connStr, RedisCacheConfig cacheConfig)
    {
        _connStr = connStr;
        _cacheConfig = cacheConfig;
    }

    public void InitializeDatabase()
    {
        using var db = new SqlBaseClient(_connStr, _cacheConfig, DbType.MySql);

        // 创建数据库（如果不存在）
        db.DbMaintenance.CreateDatabase();

        // 初始化表结构
        db.CodeFirst.InitTables<User>();
        db.CodeFirst.InitTables<UserProfile>();
        db.CodeFirst.InitTables<UserRole>();

        // 插入初始数据
        SeedData(db);
    }

    private void SeedData(SqlBaseClient db)
    {
        // 检查是否已有数据
        if (db.Queryable<User>().Any())
            return;

        // 插入初始用户
        var adminUser = new User
        {
            Username = "admin",
            Email = "admin@example.com",
            PasswordHash = "hashed_password",
            IsActive = true,
            CreatedAt = DateTime.Now,
            UpdatedAt = DateTime.Now
        };

        db.Insertable(adminUser).ExecuteCommand();
    }
}

配置选项

连接字符串格式

csharp

// MySQL 连接字符串示例
var connStr = "Server=localhost;Port=3306;Database=mydb;User=root;Password=123456;CharSet=utf8mb4;";

// 带SSL的连接字符串
var connStrSsl = "Server=localhost;Port=3306;Database=mydb;User=root;Password=123456;CharSet=utf8mb4;SslMode=Required;";

Redis 缓存配置

csharp

var cacheConfig = new RedisCacheConfig
{
    RedisConnStr = "localhost:6379,password=mypassword",
    RedisDatabase = 0 // 使用数据库0
};

// 集群配置
var clusterConfig = new RedisCacheConfig
{
    RedisConnStr = "server1:6379,server2:6379,server3:6379",
    RedisDatabase = 0
};

依赖项

SqlSugar: ORM 核心框架
Ccxc.Core.Utils: 核心工具包（Redis 客户端）
System.ComponentModel.DataAnnotations: 数据注解支持

Ccxc.Core.DbOrm 包 ​

SqlSugar 官方文档 ​

核心类 ​

SqlBaseClient 类 ​

构造函数 ​

属性 ​

方法 ​

MysqlClient<T> 抽象类 ​

构造函数 ​

属性 ​

受保护字段 ​

方法 ​

缓存系统 ​

RedisCache 类 ​

构造函数 ​

属性 ​

方法 ​

RedisCacheConfig 类 ​

属性 ​

IDataCache 接口 ​

方法 ​

数据库特性 ​

DbTableAttribute 特性 ​

构造函数 ​

属性 ​

DbColumnAttribute 特性 ​

使用示例 ​

基本实体定义 ​

创建数据访问层 ​

使用 SimpleDb 简化操作 ​

配置和初始化 ​

缓存使用示例 ​

复杂查询示例 ​

数据库初始化示例 ​

配置选项 ​

连接字符串格式 ​

Redis 缓存配置 ​

依赖项 ​

相关资源 ​

Ccxc.Core.DbOrm 包

SqlSugar 官方文档

核心类

SqlBaseClient 类

构造函数

属性

方法

MysqlClient<T> 抽象类

构造函数

属性

受保护字段

方法

缓存系统

RedisCache 类

构造函数

属性

方法

RedisCacheConfig 类

属性

IDataCache 接口

方法

数据库特性

DbTableAttribute 特性

构造函数

属性

DbColumnAttribute 特性

使用示例

基本实体定义

创建数据访问层

使用 SimpleDb 简化操作

配置和初始化

缓存使用示例

复杂查询示例

数据库初始化示例

配置选项

连接字符串格式

Redis 缓存配置

依赖项

相关资源