XiheNet.Data 3.1.0

DBHelper组件说明

DBHelper是系统自研的数据库操作组件，基于SqlSugar ORM封装，提供统一的数据库访问接口，支持单库和多库操作。

1. 组件特性

• 统一的数据库访问接口: 基于IDBHelper接口，提供统一的数据库操作方法
• SqlSugar集成: 完整集成SqlSugar ORM
• 多数据库支持: 支持单库和多库操作
• 连接字符串管理: 自动从配置文件读取数据库配置并生成连接字符串
• SQL日志记录: 自动记录执行的SQL语句，便于调试和监控
• 异常处理: 统一的异常处理机制，抛出XException自定义异常
• 依赖注入: 完整的DI集成，支持Scoped生命周期管理
• 自动连接管理: 自动开启和关闭数据库连接，无需手动管理

2. 组件结构

Core/DBHelper/
├── Abstractions/          # 抽象接口层
│   └── IHelper.cs      # 核心接口定义
├── Dtos/                 # 数据传输对象
│   └── DBConfigDto.cs    # 数据库配置DTO
├── Implementations/      # 具体实现层
│   └── Helper.cs    # SQL Server实现
└── Extensions.cs         # 扩展方法和服务注册

3. 配置说明

在 appsettings.json 中配置数据库连接信息：

{
	"DBConfig": {
		"Configs": [{
			"Code": "xihe",						// 数据库代码标识 (可选)
			"Type": "SqlServer",				// 数据库类型
			"Server": "your-server",			// 数据库服务器地址
			"Name": "your-database-name",		// 数据库名称
			"UId": "your-username",				// 用户名
			"Password": "your-password",		// 密码
			"DataSource": ""					// 数据源
		}, {
			"Code": "yonyou",					// 数据库代码标识
			"Type": "SQLite",					// 数据库类型
			"Server": "",						// 数据库服务器地址
			"Name": "",							// 数据库名称
			"UId": "",							// 用户名
			"Password": "",						// 密码
			"DataSource": "/data.sqlite3"		// 数据源
		}]
	}
}

配置特性:

• 支持SQL Server数据库和SQLite数据库，启用加密连接并信任服务器证书
• 通过依赖注入自动管理数据库连接生命周期

4. 服务注册

在 Program.cs 中注册DBHelper服务：

// 注册DBHelper服务
builder.Services.RegisterDBHelper(builder.Configuration);

5. 使用方法

5.1 依赖注入

public class UserService
{
    private readonly IHelper _dbHelper;
    private readonly ISqlSugarClient _db;
    
    public UserService(IHelper dbHelper, ISqlSugarClient db)
    {
        _dbHelper = dbHelper;
        _db = db;
    }
}

5.2 单库操作

// 方式1: 使用ISqlSugarClient直接操作 (推荐)
public async Task<List<User>> GetUsersAsync()
{
    return await _db.Queryable<User>().ToListAsync();
}

// 方式2: 使用IHelper获取连接
public async Task<List<User>> GetUsersByHelperAsync()
{
    using var db = _dbHelper.GetSugarScope();
    return await db.Queryable<User>().ToListAsync();
}

5.3 多数据库操作

// 操作主库
var users = await db.Queryable<User>().ToListAsync();

// 操作指定库
var logs = await db.GetConnection("ConfigsCode").Queryable<LogEntity>().ToListAsync();

6. 开发规范

• 服务注册: 在Program.cs中使用services.RegisterDBHelper(configuration)注册服务
• 依赖注入: 通过构造函数注入IHelper或SqlSugarScope接口
• 单库操作: 优先使用注入的SqlSugarScope，或使用GetSugarScope()方法获取连接
• 异常处理: 捕获XException异常，错误码为"1400"表示数据库连接异常
• 资源管理: 使用using语句确保数据库连接正确释放

7. 注意事项

• 连接字符串自动启用加密并信任服务器证书，适用于内网环境