agilelabs-fx-docs main topics/data-access-efcore.md

数据访问（EF Core，过期，不推荐，不再更新维护）

该页只服务于仍在维护 EF Core 存量实现的项目。EF Core 已不再作为 AgileLabs Framework 的推荐数据访问方案，也不再继续扩展这一条文档主线；收敛方向请优先阅读 EF Core 迁移到 Dapper。

本页整理遗留 EF Core 数据访问的最小兼容边界，帮助团队在维护存量实现时避免继续扩面，并为后续迁往 Dapper 保留清晰路径。

适用场景

  • 项目已经存在 AgileLabDbContext、CrudRepository、DbContextCommiter 或 AutoCommiterFilterAttribute。
  • 当前阶段只能维护现有 EF Core 面，不适合立即整体迁移。
  • 团队已经明确后续会逐步迁往 Dapper，而不是继续扩大 EF Core 使用面。

必须遵守

  • EF Core 只视为遗留兼容实现，不再作为新项目或新模块的默认方案。
  • 一个系统只保留一个默认 DbContext。
  • 不在新模块继续新增 DbContext、CrudRepository、实体配置类和 EF Core migration。
  • 所有新增模块优先迁往 Dapper，而不是继续扩 EF Core 面。
  • 保留 EF Core 时，也要明确后续对应的 Dapper 迁移路径。

推荐做法

  • 只在必须维护的存量模块里继续保留 AgileLabDbContext 与相关提交链路。
  • 优先把查询、分页和报表迁到 Dapper，再逐步收敛写入与事务。
  • 继续维护 EF Core 时，也要把边界写清楚，避免同一业务双轨失控。
  • 遇到需要新增复杂查询、分页或并发控制的需求时，优先新建 Dapper Repository。

源码入口

  • AgileLabs.EfCore.PostgreSQL/AgileLabDbContext.cs：遗留 EF Core 路线的审计字段回填。
  • AgileLabs.EfCore.PostgreSQL/Commiters/DbContextCommiter.cs：遗留 EF Core 路线的提交封装。
  • AgileLabs.WebApp.Extensions.EfCore/AspNet/WebApis/Filters/AutoCommiterFilterAttribute.cs：遗留 EF Core 路线的宿主提交链。

为什么 EF Core 不再推荐

EF Core 在传统团队开发里能降低部分样板代码，但在 AI 编程和长期维护场景里，复杂性往往会转移到更隐蔽的位置：

  • 真实行为分散在实体、配置类、DbContext、Filter、SaveChanges 扩展和导航属性中。
  • AI 生成代码容易只补齐表层调用，却遗漏跟踪状态、Include 边界、审计字段和提交链路。
  • 问题定位时经常要同时检查 LINQ、生成 SQL、实体状态、并发字段和宿主 Filter。
  • 存量项目里一旦混用 CrudRepository、自定义 DbContext 和 Dapper，维护成本会迅速放大。

遗留兼容链路

flowchart TD
    Controller[Controller / AppService]
    Repo[业务 Repository]
    Crud[CrudRepository]
    Factory[IAgileLabDbContextFactory]
    Db[AgileLabDbContext]
    Committer[DbContextCommiter]
    Pg[(PostgreSQL)]

    Controller --> Repo --> Crud --> Factory --> Db --> Committer --> Pg

最小维护边界

遗留 EF Core 路线里仍要遵守这些边界：

  • CrudRepository 只操作默认 DbContext。
  • 指定 DbContext 不继续滥用默认仓储。
  • 不把新的查询、报表和分页继续堆到 EF Core 上。
  • 审计字段、租户信息和操作者身份仍要保证与 WorkContext 对齐。

维护示例

using AgileLabs.EfCore.PostgreSQL;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.Logging;

namespace Niusys.Casher.DataStore
{
    public class CenterDbContext : AgileLabDbContext
    {
        public CenterDbContext(ILoggerFactory loggerFactory) : base(loggerFactory)
        {
        }

        protected override void OnModelCreating(ModelBuilder builder)
        {
            builder.ApplyConfigurationsFromAssembly(GetType().Assembly);
        }
    }
}

收敛方向

存量项目的标准方向仍然是迁往 Dapper：

  1. 停止新增 EF Core 接入面。
  2. 先把查询和分页迁到 Dapper。
  3. 再把写入和事务迁到显式 SQL Repository。
  4. 最后收敛 CrudRepository、DbContext 和宿主级自动提交链。

完整迁移规范见 EF Core 迁移到 Dapper。

常见坑

  • 新模块继续新增 DbContext 和 CrudRepository。
  • 在同一业务里同时混用 Dapper 写入和 EF Core 写入，却没有清晰边界。
  • 把遗留兼容链路误当成新项目模板继续复制。
  • 遗留 EF Core 模块没有迁移计划，反而继续扩大使用面。

示例与落地对照

  • niusys-webapi：更接近旧的默认 DbContext 模型，适合看遗留兼容路径。
  • woscm：适合看“历史 EF Core + 渐进迁往 Dapper”的收敛现实。

相关页面