CSFramework.EF分库分表解决方案

CSFramework.EF分库分表解决方案

本文基于 CSFramework.EF（C/S 框架网 V6.1 旗舰版 .NET8 数据访问层，EF Core 8）源码逐文件分析，回答三个问题：框架现在能不能分库、分表；分库分表时数据库名与表名该怎么命名；历史数据归档场景下，跨区间查询还能不能查得出来。文中所有结论均标注源码位置，便于复核。

一、结论速览

二、事实基线：三个分片维度

框架的分片入口只有一个：DatabaseConfig。它身上挂着三个维度——ConnectionString（库）、Schema（模式）、TableSuffix（表后缀）。三者的接线程度完全不同。

2.1 一个 IDatabase 实例 = 一个库

DatabaseFactory.GetDatabase(config) 每次调用产出一个独立实例，连接串直接决定打到哪个库。值得注意的是 IDatabase.DatabaseName 只是一个只读回读属性：取当前连接的 Database，取不到就退回 Schema（GenericDatabase.cs:61-73）。也就是说：框架既不生成库名，也不校验库名，库名完全由外部连接串决定。

2.2 Schema：唯一真正落地的分片维度

这是框架已经做实的分库分表能力，由三件东西配合完成：

• GenericDbContext.ConfigSchema：调用 modelBuilder.HasDefaultSchema(config.Schema)（GenericDbContext.cs:104-107）；
• DatabaseEngine.RemoveEntitySchema（默认 true，DatabaseEngine.cs:202）：自动剥掉实体 [Table] 上写死的 Schema，所以实体模型不需要指定 Schema；
• SchemaModelCacheFactory 替换 EF 的 IModelCacheKeyFactory，把 Schema 并入模型缓存键（SchemaModelCache.cs:35-55）。

第三点是关键：OnModelCreating 只会执行一次，EF 对模型做了缓存。正是缓存键里加了 Schema，同一实体在不同 Schema 下才会有各自独立的模型，“动态 DbContext”才成立。

2.3 TableSuffix：预留字段，尚未接线

DatabaseConfig.TableSuffix（DatabaseConfig.cs:101-104）的注释原话是“表名后缀(分表时需要)”。但全仓库检索它的出现位置只有两处：定义处，以及消费方赋值处——而且赋的是空串（WebApi 端 DatabaseBuilder.cs:125：TableSuffix = ""）。

2.4 表名唯一来源：[Table] 特性

ReflectionHelper.GetTableName(Type) 优先取 [Table].Name，无特性时回退类名（Helper/ReflectionHelper.cs:30-39）。实体注册时只做 modelBuilder.Entity(T)，不指定表名（GenericDbContext.cs:85-89），整个解决方案内 ToTable( / SetTableName( 零命中。读路径拼 SQL 用的也是这个口径：GetDataByKey、SelectAll、RemoveAll<T>、IsExistsKeyValue<T>。

结论：今天的表名是编译期写死的，运行期没有任何一处会改写它。顺带一提，模型缓存键目前只含 Schema、不含表名，这一点在后面做分表时会变成最大的隐形地雷。

三、分库：框架已支持，消费方已实装

核心库视角很简单——每次 GetDatabase 就是一个新库实例，库名无约束、无校验。真正的分库规则，在消费方的账套机制里。

3.1 账套加载链路

3.2 账套定义表 tb_DataSet 的关键字段

DataSetID（账套编号，唯一）、DBName（物理库名）、DatabaseType、Schema、LocalServerIP/Port、RemoteServerIP/Port、DBUserName、DBUserPassword（加密存储）、IsUse、IsVisible。

现行命名习惯：系统库 CSFrameworkV6_System（账套 ID 固定 SystemDB），默认业务库 CSFrameworkV6_Normal（账套 ID Normal）；表按前缀分三类：dt_* 基础资料、sys_* 系统表、tb_* 业务表。

3.3 WebApi 侧：一个接口 = 一个库

WebApi 开发框架的做法是用派生接口区分库：UseDatabase<TDatabase>(...) 以接口全名作为配置项名称注册，需要几个库就定义几个 IDatabase 派生接口（如系统库访问器、业务库访问器）。

四、分表：需要补齐的四个改造点

要让 TableSuffix 真正生效，需要改四处。前两处必须同时做，拆开做必踩坑。

① 给 DbContext 增加表名配置

// GenericDbContext.OnModelCreating 内，ConfigSchema 之后追加一步
protected virtual void ConfigTableName(ModelBuilder modelBuilder)
{
    var suffix = _databaseConfig.TableSuffix;   // 如 "_202601"
    if (String.IsNullOrEmpty(suffix)) return;

    foreach (var entityType in modelBuilder.Model.GetEntityTypes())
    {
        // 基表名来自 [Table] 特性或类名
        entityType.SetTableName(entityType.GetTableName() + suffix);
    }
}

② 模型缓存键必须并入 TableSuffix

// SchemaModelCache：缓存键只比 Schema，不比表名 —— 分表后必须一起改
readonly string _tableSuffix;   // 取自 DatabaseConfig.TableSuffix

protected override bool Equals(ModelCacheKey other)
{
    return base.Equals(other)
        && (other as SchemaModelCache)?._schema == _schema
        && (other as SchemaModelCache)?._tableSuffix == _tableSuffix;
}

public override int GetHashCode()
{
    var hashCode = base.GetHashCode() * 168;
    if (_schema != null) hashCode ^= _schema.GetHashCode();
    if (_tableSuffix != null) hashCode ^= _tableSuffix.GetHashCode();
    return hashCode;
}

③ 读路径统一加后缀

框架的写操作走 EF，但读操作（GetDataTable / ExecuteScalar / GetDataSet / ExecuteSql(Type) 等）多是自建 ADO.NET 连接拼 SQL。所以除了 EF 模型，还要把这些拼表名的地方统一收口成一个方法（例如 GetPhysicalTableName(Type)），至少覆盖：GetDataByKey、SelectAll、RemoveAll<T>、IsExistsKeyValue<T>。

④ 五个数据库提供程序各自的 override

SqlServer / MySql / Oracle / PostgreSql / 达梦五个提供程序里，凡是自己组装 SQL 或指定批量导入目标表名的 override（如 Oracle 的 SelectAll、RemoveAll、BulkInsert）都要一并加后缀。顺带修一个现存问题：Oracle 的 SelectAll 仍在用类名而非 [Table] 名，遇到类名与表名不一致的实体（例如 sys_Data_SN 类对应 sys_DataSN 表）会直接报表不存在。

五、命名规则

5.1 数据库名（分库）

• 建议格式：CSFrameworkV6_{DataSetID}，如 CSFrameworkV6_Normal、CSFrameworkV6_FactoryA；
• 系统库固定为 CSFrameworkV6_System（多处常量引用，不要改）；
• 字符集只用 [A-Za-z0-9_]，不要中文、空格、连字符——它会进入连接串、Oracle/达梦的 Schema、备份脚本的文件名；
• 账套编号 DataSetID 是逻辑键（登录界面选择、实例缓存 key），可与库名保持一致便于排错。

5.2 表名（分表后缀）

• 格式：{基表名}{分隔符}{后缀}，框架侧只有“追加后缀”一种形态，没有前缀、没有替换；
• 时间分片：tb_PO_202601（按月）、tb_PO_2026（按年）；哈希分片：tb_PO_03（取模，定宽两位）；
• 后缀字符集同样只用 [A-Za-z0-9_]，不要裸数字开头，不要含 -；
• Schema 与表名之间的点号由 FormatSchema 自动补，后缀里不要带点。

5.3 各库标识符硬约束（决定上限）

六、历史数据归档实操

典型诉求：把几年前的旧数据搬出去做备份，归档表主要供查询。以采购订单 tb_PO（主表）/ tb_POs（明细）为例，把 2024/12/31 之前的数据分出去。

6.1 先看清实体，口径才不会错

6.2 归档数据放哪里

“归档 + 只读”这类诉求下方案 A 明显更划算：表名不变，就不用碰 TableSuffix、不用碰模型缓存键，现有 IDatabase 直接就能读。

6.3 搬迁步骤（幂等、可重跑）

1. 建归档表——注意 SELECT INTO / CTAS 不会带主键和索引，事后必须单独创建；
2. 抽主表：WHERE PODate < '2025-01-01'（即 2024/12/31 及之前）；
3. 抽明细：WHERE PONO IN (SELECT PONO FROM 归档主表)；
4. 对账：行数 + 金额合计双查，主表明细各一次，不一致就停下；
5. 删原表：先明细、后主表，按 PONO 分批（每批 1000~5000 行），不要一次性 DELETE（会锁表、日志暴涨）；
6. 备份归档库，可设为只读账号或只读文件组。