命名策略
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 字段名也变了 | 排除面:消息契约字段不是库列名 | 消息消费方按契约字段名读——不受策略影响 |