SmartDapper.Middleware 1.0.1

SmartDapper.Middleware

SmartDapper.Middleware 为 ASP.NET Core 提供 声明式事务（UnitOfWork）编排能力：通过在控制器/方法上标记 [UnitOfWork]，自动开启事务，并在请求结束时 无异常提交 / 异常回滚。

功能特性

• 自动事务管理：基于 [UnitOfWork] 特性自动管理数据库事务
• 隔离级别配置：支持在特性中配置事务隔离级别
• 日志可观测性：输出事务开启/提交/回滚的关键日志，便于排查
• 复用外层事务：检测到外层已存在事务时，自动跳过嵌套开启
• 推荐 Filter 化：Controllers 用 ActionFilter；Minimal API 用 EndpointFilter（更符合事务提交时机）

快速开始

1) 安装

dotnet add package SmartDapper.Middleware

2) 注册服务 + 事务编排

在 Program.cs 中：

using Microsoft.Data.SqlClient;
using SmartDapper.Middleware.Extensions;
using SmartDapper.Repository.Extensions;

var builder = WebApplication.CreateBuilder(args);

var connectionString = builder.Configuration.GetConnectionString("Default")!;

// 注册仓储 + 工作单元（DI，下沉在 SmartDapper.Repository）
builder.Services.AddSmartDapperRepository(connectionString, cs => new SqlConnection(cs));

// Controllers：启用 [UnitOfWork] 事务过滤器（按异常回滚）
builder.Services.AddSmartDapperUnitOfWork();

var app = builder.Build();

// 可选：兼容层中间件（一般不需要；推荐优先用 Filter/EndpointFilter）
// app.UseSmartDapperUnitOfWork();

app.MapControllers();
app.Run();

3) 使用事务特性

using Microsoft.AspNetCore.Mvc;
using SmartDapper.Middleware.Attributes;
using SmartDapper.Repository;

[ApiController]
[Route("api/[controller]")]
public class CustomerController : ControllerBase
{
    private readonly IRepository<Customer> _repo;

    public CustomerController(IRepository<Customer> repo)
    {
        _repo = repo;
    }

    [HttpPost]
    [UnitOfWork]
    public async Task<IActionResult> Create(Customer customer)
    {
        await _repo.InsertAsync(customer);
        return Ok(customer);
    }
}

高级配置

配置隔离级别/超时/描述

[UnitOfWork(
    IsolationLevel = System.Data.IsolationLevel.Serializable,
    TimeoutSeconds = 120,
    AutoRollbackOnException = true,
    Description = "用户注册事务"
)]
public async Task<IActionResult> RegisterUser(User user)
{
    // ...
}

注：TimeoutSeconds 当前用于业务语义与日志标识；若需要“命令超时”，应在数据访问层（Dapper CommandDefinition 等）设置。

Minimal API 用法（通过 Middleware 按 metadata 开启事务）

using Microsoft.Data.SqlClient;
using SmartDapper.Middleware.Extensions;
using SmartDapper.Repository.Extensions;

var builder = WebApplication.CreateBuilder(args);
var cs = builder.Configuration.GetConnectionString("Default")!;
builder.Services.AddSmartDapperRepository(cs, x => new SqlConnection(x));

var app = builder.Build();

// 启用事务中间件：它会读取 endpoint 上的 [UnitOfWork] metadata 来决定是否开启事务
app.UseSmartDapperUnitOfWork();

app.MapPost("/customers", async (IRepository<Customer> repo, Customer customer) =>
    {
        await repo.InsertAsync(customer);
        return Results.Ok(customer);
    })
    .WithSmartDapperUnitOfWork(o =>
    {
        o.IsolationLevel = System.Data.IsolationLevel.ReadCommitted;
        o.Description = "创建客户";
    });

app.Run();

注意事项

• 事务语义：默认 无异常提交 / 异常回滚（不再依据 HTTP StatusCode）。
• 连接工厂：AddSmartDapperRepository 需要你提供 connectionFactory（避免库内部猜测数据库类型）。
• 可选兼容层：若仍使用中间件，确保在调用 app.UseSmartDapperUnitOfWork() 前已注册 IUnitOfWork。
• 后台任务：后台任务建议自己创建 DI Scope 并使用 IUnitOfWork/扩展方法显式管理事务。