IceTea.SqlStandard 1.1.6

IceTea.SqlStandard (数据库标准访问类库)

简介

IceTea.SqlStandard 是一个标准化的数据库访问类库，提供了统一的数据库操作接口和多种数据库的支持。该库封装了 ADO.NET 的核心功能，支持事务管理、连接池、异步操作等企业级特性，适用于各种数据库应用场景。

安装

dotnet add package IceTea.SqlStandard

核心功能模块

一、核心接口

IDb (数据库接口)

继承自多个基础接口，提供完整的数据库操作功能。

继承接口：

• IStarter - 启动器接口
• ITransaction - 事务接口
• IDisposable - 资源释放接口

核心属性：

• EnumDbType DbType { get; } - 数据库类型
• IDbCommand Command { get; } - 数据库命令对象

核心方法：

元数据查询

• Task<IEnumerable<string>> GetDBsNameAsync() - 获取数据库名称列表
• Task<IEnumerable<string>> GetTablesAsync() - 获取表名列表
• Task<IEnumerable<string>> GetColumnsAsync(string tableName) - 获取表的列信息

数据查询操作

• Task<IDataReader> ExecuteReaderAsync(string cmdText, IEnumerable<IDataParameter> paramCollection, CommandType cmdType = CommandType.Text) - 执行查询返回数据读取器
• Task<DataSet> ExecuteQueryAtOnceAsync(string cmdText, IEnumerable<IDataParameter> paramCollection, CommandType cmdType = CommandType.Text) - 一次性执行查询返回数据集
• Task<DataSet> ExecuteQueryAtOnceAsync(IEnumerable<CmdTextAndParams> cmdTextAndParams, CommandType cmdType = CommandType.Text) - 批量执行查询返回数据集
• Task<DataSet> ExecuteQueryAsync(string cmdText, IEnumerable<IDataParameter> paramCollection, CommandType cmdType = CommandType.Text) - 异步执行查询返回数据集
• Task<DataSet> ExecuteQueryAsync(IEnumerable<CmdTextAndParams> cmdTextAndParams, CommandType cmdType = CommandType.Text) - 异步批量执行查询返回数据集

数据修改操作

• Task<int> ExecuteNonQueryAtOnceAsync(string cmdText, IEnumerable<IDataParameter> paramCollection = null, CommandType cmdType = CommandType.Text) - 一次性执行非查询操作
• Task<int> ExecuteNonQueryAtOnceAsync(IEnumerable<CmdTextAndParams> cmdTextAndParams, CommandType cmdType = CommandType.Text) - 批量执行非查询操作
• Task<int> ExecuteNonQueryAsync(string cmdText, IEnumerable<IDataParameter> paramCollection = null, CommandType cmdType = CommandType.Text) - 异步执行非查询操作
• Task<int> ExecuteNonQueryAsync(IEnumerable<CmdTextAndParams> cmdTextAndParams, CommandType cmdType = CommandType.Text) - 异步批量执行非查询操作

二、核心枚举

EnumDbType - 数据库类型枚举

定义支持的数据库类型。

枚举值：

• SqlServer - Microsoft SQL Server
• MySql - MySQL
• Oracle - Oracle Database
• PostgreSql - PostgreSQL
• SQLite - SQLite

三、配置类

DBConfig - 数据库配置

数据库连接配置信息。

CmdTextAndParams - 命令文本和参数

封装SQL命令及其参数。

四、管理接口

IDbManager - 数据库管理器接口

提供数据库连接管理和生命周期管理。

ITransaction - 事务接口

提供数据库事务操作支持。

使用指南

1. 基本数据库操作示例

// 创建数据库实例
var db = new StandardDb(EnumDbType.SqlServer, "Server=localhost;Database=TestDB;Integrated Security=true;");

// 启动数据库连接
bool connected = await db.StartAsync();

if (connected)
{
    // 查询数据
    var dataSet = await db.ExecuteQueryAsync("SELECT * FROM Users WHERE Age > @age", 
        new[] { new SqlParameter("@age", 18) });
    
    // 遍历查询结果
    foreach (DataRow row in dataSet.Tables[0].Rows)
    {
        Console.WriteLine($"用户: {row["Name"]}, 年龄: {row["Age"]}");
    }
    
    // 执行插入操作
    int affectedRows = await db.ExecuteNonQueryAsync(
        "INSERT INTO Users (Name, Age, Email) VALUES (@name, @age, @email)",
        new[]
        {
            new SqlParameter("@name", "张三"),
            new SqlParameter("@age", 25),
            new SqlParameter("@email", "zhangsan@example.com")
        });
    
    Console.WriteLine($"插入了 {affectedRows} 行数据");
}

2. 事务操作示例

var db = new StandardDb(EnumDbType.MySql, connectionString);

await db.StartAsync();

try
{
    // 开始事务
    await db.BeginTransactionAsync();
    
    // 执行多个相关操作
    await db.ExecuteNonQueryAsync("UPDATE Accounts SET Balance = Balance - 100 WHERE UserId = 1");
    await db.ExecuteNonQueryAsync("UPDATE Accounts SET Balance = Balance + 100 WHERE UserId = 2");
    
    // 提交事务
    await db.CommitTransactionAsync();
    
    Console.WriteLine("转账成功");
}
catch (Exception ex)
{
    // 回滚事务
    await db.RollbackTransactionAsync();
    Console.WriteLine($"转账失败: {ex.Message}");
}
finally
{
    await db.CloseAsync();
}

3. 批量操作示例

var db = new StandardDb(EnumDbType.PostgreSql, connectionString);

await db.StartAsync();

// 批量执行多个SQL命令
var commands = new[]
{
    new CmdTextAndParams
    {
        CmdText = "INSERT INTO Products (Name, Price) VALUES (@name, @price)",
        Parameters = new[]
        {
            new NpgsqlParameter("@name", "产品A"),
            new NpgsqlParameter("@price", 99.99m)
        }
    },
    new CmdTextAndParams
    {
        CmdText = "INSERT INTO Products (Name, Price) VALUES (@name, @price)",
        Parameters = new[]
        {
            new NpgsqlParameter("@name", "产品B"),
            new NpgsqlParameter("@price", 149.99m)
        }
    }
};

int totalAffected = await db.ExecuteNonQueryAtOnceAsync(commands);
Console.WriteLine($"总共插入了 {totalAffected} 条记录");

4. 数据读取器使用示例

var db = new StandardDb(EnumDbType.SQLite, connectionString);

await db.StartAsync();

using (var reader = await db.ExecuteReaderAsync("SELECT Id, Name, Email FROM Users ORDER BY Name"))
{
    while (await reader.ReadAsync())
    {
        var user = new
        {
            Id = reader.GetInt32("Id"),
            Name = reader.GetString("Name"),
            Email = reader.GetString("Email")
        };
        
        Console.WriteLine($"用户: {user.Name} ({user.Email})");
    }
}

5. 元数据查询示例

var db = new StandardDb(EnumDbType.SqlServer, connectionString);

await db.StartAsync();

// 获取数据库列表
var databases = await db.GetDBsNameAsync();
Console.WriteLine("数据库列表:");
foreach (var dbName in databases)
{
    Console.WriteLine($"  - {dbName}");
}

// 获取表列表
var tables = await db.GetTablesAsync();
Console.WriteLine("\n表列表:");
foreach (var tableName in tables)
{
    Console.WriteLine($"  - {tableName}");
    
    // 获取表的列信息
    var columns = await db.GetColumnsAsync(tableName);
    foreach (var column in columns)
    {
        Console.WriteLine($"    * {column}");
    }
}

技术特性

数据库支持

• SQL Server: 完整的 T-SQL 支持
• MySQL: 标准 MySQL 语法支持
• Oracle: PL/SQL 和 Oracle 特有功能
• PostgreSQL: PostgreSQL 扩展功能
• SQLite: 轻量级嵌入式数据库

连接管理

• 连接池: 自动连接池管理
• 连接复用: 高效的连接复用机制
• 超时控制: 连接和命令超时设置
• 自动重连: 连接断开后的自动恢复

事务支持

• ACID特性: 完整的事务ACID特性
• 嵌套事务: 支持嵌套事务处理
• 保存点: 事务保存点支持
• 隔离级别: 可配置的事务隔离级别

性能优化

• 异步操作: 全异步API设计
• 参数化查询: 防止SQL注入攻击
• 批处理: 支持批量SQL执行
• 缓存机制: 查询结果缓存支持

典型应用场景

1. 企业应用: ERP、CRM等企业级系统
2. Web应用: ASP.NET Core Web API 数据访问
3. 桌面应用: WPF、WinForms 数据库操作
4. 移动应用: Xamarin、MAUI 数据存储
5. 微服务: 微服务架构的数据访问层

最佳实践

1. 连接管理最佳实践

public class DataService : IDisposable
{
    private readonly IDb _db;
    
    public DataService(EnumDbType dbType, string connectionString)
    {
        _db = new StandardDb(dbType, connectionString);
    }
    
    public async Task InitializeAsync()
    {
        await _db.StartAsync();
    }
    
    public async Task<List<User>> GetUsersAsync()
    {
        var dataSet = await _db.ExecuteQueryAsync("SELECT * FROM Users");
        return MapToUsers(dataSet.Tables[0]);
    }
    
    public void Dispose()
    {
        _db?.Dispose();
    }
}

2. 事务处理最佳实践

public async Task<bool> TransferMoneyAsync(int fromUserId, int toUserId, decimal amount)
{
    try
    {
        await _db.BeginTransactionAsync();
        
        // 检查余额
        var balance = await GetBalanceAsync(fromUserId);
        if (balance < amount)
        {
            await _db.RollbackTransactionAsync();
            return false;
        }
        
        // 执行转账
        await _db.ExecuteNonQueryAsync(
            "UPDATE Accounts SET Balance = Balance - @amount WHERE UserId = @userId",
            new[] { new SqlParameter("@amount", amount), new SqlParameter("@userId", fromUserId) });
            
        await _db.ExecuteNonQueryAsync(
            "UPDATE Accounts SET Balance = Balance + @amount WHERE UserId = @userId",
            new[] { new SqlParameter("@amount", amount), new SqlParameter("@userId", toUserId) });
        
        await _db.CommitTransactionAsync();
        return true;
    }
    catch (Exception ex)
    {
        await _db.RollbackTransactionAsync();
        _logger.LogError(ex, "转账操作失败");
        throw;
    }
}

3. 参数化查询最佳实践

public async Task<User> GetUserByIdAsync(int userId)
{
    var parameters = new[]
    {
        CreateParameter("@userId", userId, DbType.Int32)
    };
    
    var dataSet = await _db.ExecuteQueryAsync(
        "SELECT * FROM Users WHERE UserId = @userId", 
        parameters);
    
    return dataSet.Tables[0].Rows.Count > 0 
        ? MapToUser(dataSet.Tables[0].Rows[0]) 
        : null;
}

private IDataParameter CreateParameter(string name, object value, DbType type)
{
    var parameter = _db.Command.CreateParameter();
    parameter.ParameterName = name;
    parameter.Value = value ?? DBNull.Value;
    parameter.DbType = type;
    return parameter;
}

配置说明

基本配置

// SQL Server 配置
var sqlServerDb = new StandardDb(EnumDbType.SqlServer, 
    "Server=localhost;Database=MyDB;User Id=user;Password=pass;");

// MySQL 配置
var mySqlDb = new StandardDb(EnumDbType.MySql, 
    "Server=localhost;Database=MyDB;Uid=user;Pwd=pass;");

// Oracle 配置
var oracleDb = new StandardDb(EnumDbType.Oracle, 
    "Data Source=localhost:1521/XE;User Id=user;Password=pass;");

高级配置

// 连接池配置
var connectionString = "Server=localhost;Database=TestDB;" +
                      "Integrated Security=true;" +
                      "Pooling=true;" +
                      "Min Pool Size=5;" +
                      "Max Pool Size=100;" +
                      "Connection Timeout=30;";

var db = new StandardDb(EnumDbType.SqlServer, connectionString);

依赖说明

• System.Data.Common: ADO.NET 核心数据访问
• 各数据库驱动: SQL Server、MySQL、Oracle 等驱动
• IceTea.Pure: 基础工具类库

兼容性

• .NET版本: .NET Standard 2.0+
• 数据库: SQL Server, MySQL, Oracle, PostgreSQL, SQLite
• 操作系统: Windows, Linux, macOS

许可证

MIT License

作者

WuMing

贡献

欢迎提交 Issue 和 Pull Request！