Galosys.Foundation.Dapper 26.10.29.1

Galosys.Foundation.Dapper

成熟度: 🟢 稳定 — 生产可用，测试充分，活跃维护

简介

Galosys.Foundation.Dapper 基于 Dapper 提供轻量级 ORM 和数据访问支持，包含工作单元模式、SQL 映射、CDC（变更数据捕获）等功能。

特性

• Dapper 集成 - 高性能轻量级 ORM
• 工作单元模式 (UnitOfWork) - 事务管理
• SQL 映射 - 静态 SQL 查询映射
• SQL 构建器 - 动态 SQL 构建
• CDC 监听器 - 变更数据捕获（支持 SQL Server）
• 支持多种数据库 - SQL Server, Oracle 等

安装

dotnet add package Galosys.Foundation.Dapper

使用

工作单元

public class OrderRepository
{
    private readonly IUnitOfWork _unitOfWork;

    public OrderRepository(IUnitOfWork unitOfWork)
    {
        _unitOfWork = unitOfWork;
    }

    public async Task InsertOrderAsync(Order order)
    {
        var sql = "INSERT INTO Orders (Id, OrderNo, Amount) VALUES (@Id, @OrderNo, @Amount)";
        await _unitOfWork.ExecuteAsync(sql, order);
    }

    public async Task CommitAsync()
    {
        await _unitOfWork.CommitAsync();
    }
}

查询示例

public class UserService
{
    private readonly IDbConnection _db;

    public UserService(IDbConnection db)
    {
        _db = db;
    }

    public async Task<IEnumerable<User>> GetUsersAsync()
    {
        var sql = "SELECT * FROM Users WHERE Deleted = 0";
        return await _db.QueryAsync<User>(sql);
    }

    public async Task<User> GetUserByIdAsync(long id)
    {
        var sql = "SELECT * FROM Users WHERE Id = @Id";
        return await _db.QueryFirstOrDefaultAsync<User>(sql, new { Id = id });
    }

    public async Task<int> InsertUserAsync(User user)
    {
        var sql = @"INSERT INTO Users (Name, Email) VALUES (@Name, @Email);
                    SELECT CAST(SCOPE_IDENTITY() as bigint)";
        return await _db.ExecuteScalarAsync<int>(sql, user);
    }
}

SQL 映射

// 使用 SqlMap 进行静态 SQL 映射
var result = await SqlMap.QueryAsync<User>("SelectUsers");

CDC 监听（变更数据捕获）

public class OrderCdcListener : ICdcListener
{
    public DatabaseType DatabaseType => DatabaseType.SqlServer;

    public string[] TableNames => new[] { "Orders" };

    public async Task HandleAsync(CdcEventArgs args)
    {
        // 处理变更数据
        Console.WriteLine($"Operation: {args.Operation}");
        Console.WriteLine($"Data: {args.Data}");
    }
}

// 注册 CDC 监听器
services.AddCdcListener<OrderCdcListener>();

分页查询

public async Task<PageOutput> GetUserPageAsync(int page, int size)
{
    var sql = "SELECT * FROM Users ORDER BY Id OFFSET @Offset ROWS FETCH NEXT @Size ROWS ONLY";
    var countSql = "SELECT COUNT(*) FROM Users";
    
    var items = await _db.QueryAsync<User>(sql, new { Offset = (page - 1) * size, Size = size });
    var total = await _db.ExecuteScalarAsync<int>(countSql);
    
    return PageOutput.Of(items, total, page, size);
}

模块化异常处理

Dapper 模块提供 MySqlExceptionHandler（绑定 MySqlConnector.MySqlException，[ExceptionHandler(200)]），用于在 MySql 驱动抛错时优先于框架默认 DbExceptionHandler(0) 接管。处理器归属 Dapper 而非 Data 的原因：MySqlConnector 依赖仅在 Dapper（直引）与 EFCore（pomelo 传递）出现，避免 Data 模块背上 MySql 依赖。

[ExceptionHandler(200)]
public sealed class MySqlExceptionHandler : TypedExceptionHandler<MySqlConnector.MySqlException>
{
    public override ValueTask<ExceptionHandlingOutput> HandleAsync(
        MySqlConnector.MySqlException exception,
        CancellationToken cancellationToken = default)
    {
        var (code, message) = Map(exception.Number);
        return ValueTask.FromResult(new ExceptionHandlingOutput(400, code, message));
    }

    private static (string code, string message) Map(int number) => number switch
    {
        1062 => ("A00400", "提示：数据库主键冲突，请联系管理员"),
        1452 => ("A00400", "提示：违反外键约束，请联系管理员"),
        _ => (ErrorCode.Of("A", (short)BizErrorCode.ParameterInvalid),
              "提示：数据库操作异常，请联系管理员"),
    };
}

处理器继承 System.TypedExceptionHandler<T> 并标注 [ExceptionHandler(200)]，经 AddAnnotationConfiguration 自动注册；按 Priority 降序分发时优先于框架默认 DbExceptionHandler(0)，确保 MySql 错误码（主键冲突 1062、外键约束 1452 等）映射到对用户友好的提示文案。

核心类

依赖

• Dapper
• Microsoft.Data.SqlClient (SQL Server)
• Oracle.ManagedDataAccess.Core (Oracle)
• Galosys.Foundation.Core