Table of Contents

命名策略

C# PascalCase 与数据库命名规范(snake_case / UPPER_SNAKE)的整库映射——上下文级策略,转换发生在发射期。 上位:总览。

形态

逐属性标 [EfColumn(Name =)] 在整库策略下不现实。命名策略 = 上下文级选项,转换发生在发射期(生成器把转换后的名字发射为显式 ToTable/HasColumnName——运行时零转换、产物入库可评审、冻结模型一致——编译期事实直出的家族哲学,非运行时 convention)。

声明

// 程序集级单一声明源(推荐——一处声明整程序集生效)
[assembly: EfNaming(LoomNamingStrategy.SnakeCase)]
// 上下文级覆盖(同程序集个别上下文特殊化)
services.AddLoomEf<LegacyCtx>(o => o.UseSqlServer(cs), loom =>
{
    loom.Naming.Strategy = LoomNamingStrategy.UpperSnakeCase;
});
策略 转换 适用
None(缺省) 无转换——EF 约定名,现状逐字节不变 新项目不指定 = 零变化
SnakeCase OrderItem → order_item PG/MySQL 小写规范
UpperSnakeCase OrderItem → ORDER_ITEM Oracle/DB2 大写规范
CustomTransform 任意 Func<string, string> 其他库方言习惯(设置即覆盖 Strategy)

转换规则(定死,无解释空间)

  • 词边界:连续大写序列作为一个词(IDNumber → id_number、ABCDef → abc_def——缩写不逐字母拆);数字不触发下划线(Address1 → address1)。
  • 三层优先:显式声明([EfTable]/[EfColumn(Name =)]/[EfShadow] 显式名)> 命名策略 > EF 约定——显式名即字面永不转换(含 [EfTablePrefix] 前缀与 [EfComment] 注释值——字面量)。
  • 作用面(框架内置一样遵守):业务表名/列名 + Loom 框架内置实体与列(LoomOutboxMessage/LoomInboxMessage/审计表/种子记账/框架审计影子列——全部跟随策略,整库命名统一;软删 filter/租户 SQL 等发射文案同源取转换后列名,无漂移)。
  • 排除面(仅两条):outbox/watch 消息 Payload 内的 JSON 字段名(消息契约非库列名)与显式声明字面量。
  • 实现要求:单一转换入口(LoomNaming.Apply(name))——outbox/inbox store、审计表 sink、清理服务、种子的表名/列名全部经此口生成(禁止硬编码表名)。
  • 诊断:转换后同名冲突(KLSG140 同名表诊断覆盖;列冲突 EF 自检为准)。

既有部署策略不可变

策略一经上线不可变更——换名 = 表消失重建。已有库要改策略 = 走改名迁移(dotnet ef migrations add RenameAll 逐表 Rename),或接受重建。这是"发射期物化"的直接代价与收益:名字在产物里可评审,但也就不是运行时能热切的开关。

冻结模型一致性

策略在发射期物化 → loom ef optimize 产物里名字已固化——冻结模型与运行时模型天然一致,指纹卡点无命名漂移面。

反模式

症状 为什么错 正确形态
上线后改 Strategy 表列名全变 = 表消失重建 不可变;确需切换走改名迁移
期望显式名跟随策略转换 显式即字面([EfTable]/[EfColumn(Name=)] 永不转换) 全走约定名吃策略,或全显式自管——不混
存量库半途引入策略 既有表按旧名建,新模型按新名发射——全部对不上 存量库维持 None + 逐表 [EfTable] 显式名
Payload JSON 字段名也变了 排除面:消息契约字段不是库列名 消息消费方按契约字段名读——不受策略影响

想深入