EF Core 迁移到 Dapper

本页定义 AgileLabs Framework 项目从 EF Core 收敛到 Dapper / SQL 的标准迁移规范。目标不是一次性推翻所有存量代码，而是给出一条对人和 AI Agent 都可执行的收敛路径。

为什么迁移

当前文档已经把 Dapper / SQL 定义为默认推荐方案，原因主要有三类：

SQL、事务、并发和影响行数都是显式行为，更适合代码审查和 AI 生成后的人工校验。
EF Core 的真实行为分散在实体、配置类、DbContext、Filter、SaveChanges() 扩展和导航属性里，问题排查链更长。
当项目同时混用 CrudRepository、自定义 DbContext 和 Dapper 时，维护成本通常会继续扩大，而不是自然下降。

适用场景

项目已经存在 AgileLabDbContext、CrudRepository、AutoCommiterFilterAttribute 或 EF Core migration。
团队希望停止继续扩大 EF Core 使用面，并把新增模块收敛到 Dapper。
当前项目需要更强的 SQL 可控性、并发控制可见性和 AI 协作可审查性。

不建议立刻整体迁移的情况

当前发布窗口极短，无法接受较大数据访问面调整。
模块高度依赖导航属性、复杂 Change Tracking，且业务边界尚未明确。
团队还没有完成 Repository 边界、DTO 边界和事务边界梳理。

这些情况下也不要继续新增 EF Core 面，而应先冻结扩张，再逐步准备迁移。

迁移目标

新模块不再新增 DbContext、CrudRepository 和 EF Core migration。
查询、分页、报表、列表页统一收敛到 Dapper Repository。
写入逻辑显式表达 SQL、事务、并发条件和影响行数校验。
审计字段、租户信息和操作者身份不再隐式依赖 SaveChanges() 扩展。

分阶段迁移路径

flowchart LR
    A[冻结新增 EF Core] --> B[先迁查询与分页]
    B --> C[再迁写入与事务]
    C --> D[收敛并发与审计字段]
    D --> E[移除 DbContext 主路径依赖]

阶段 1：冻结新增 EF Core

不再新增 RegisterDbContext<TDbContext>() 接入。
不再给新模块增加 CrudRepository、新的实体配置类和新的 EF Core migration。
新需求默认直接落到 Dapper Repository。

阶段 2：先迁查询与分页

优先迁移列表页、详情页、报表和分页查询。
这些能力最容易从 LINQ 收敛到显式 SQL，也最容易独立验收。
迁移后确保 Controller 或 AppService 只依赖业务 Repository，不直接持有 SQL。

阶段 3：再迁写入与事务

把新增、修改、删除逻辑迁到 Repository 中的显式 SQL。
明确 where 条件、租户条件、版本条件和影响行数判断。
涉及多步写入时，统一改用 TransScopeAsync 之类的显式事务入口。

阶段 4：收敛并发与审计字段

把 ts、版本号、更新时间、更新人等字段回填逻辑显式落在参数组装或项目级基类中。
不再依赖 SaveChanges() 的隐式审计行为兜底。
所有需要当前用户、租户、时区的逻辑都显式从 WorkContext 取值。

阶段 5：移除 EF Core 主路径依赖

业务主路径不再依赖 CrudRepository。
新功能不再依赖 AutoCommiterFilterAttribute。
历史 DbContext 保留到可接受的最小范围后，再决定是否继续清退。

Repository 重构规范

迁移时，先改边界，再改实现。推荐规则：

Controller / AppService 只调用业务语义方法，例如 GetOrderListAsync、ApproveOrderAsync。
Repository 内封装 SQL、参数对象、事务和并发判断。
不把 DbConnection、IDbTransaction、SQL 字符串散落到控制器和服务层。
DTO、查询参数对象、写入命令对象和数据库实体概念要分清，不继续复用 EF Core Entity 当成所有层通用模型。

查询迁移模板

EF Core 查询通常长这样：

var query = await _crudRepository.GetQueryAsync<OrderEntity>();
var list = await query
    .Where(x => x.BuyerId == buyerId)
    .OrderByDescending(x => x.CreateTime)
    .Select(x => new OrderListItemDto { Id = x.Id, OrderNo = x.OrderNo })
    .ToListAsync();

迁到 Dapper 后，目标形态应该更接近：

public async Task<IEnumerable<OrderListItemDto>> GetOrderListAsync(string buyerId, CancellationToken cancellationToken)
{
    const string sql = @"
select id, order_no as OrderNo
from orders
where buyer_id = @buyerId
order by create_time desc";

    return await GetListAsync<OrderListItemDto>(sql, new { buyerId }, cancellationToken: cancellationToken);
}

迁移要求：

SQL 字段选择显式列出，不依赖整表实体投影。
排序、过滤和分页规则在 SQL 中可见。
返回 DTO 只保留调用方真实需要的字段。

写入迁移模板

EF Core 写入通常是：

var entity = await context.Set<OrderEntity>().FirstAsync(x => x.Id == id);
entity.Status = OrderStatus.Approved;
await context.SaveChangesAsync();