做 NHibernate 项目的朋友迟早会撞上联合主键composite-id这堵墙我就是这么撞上去的。联合主键在 ORM 里从来不是一个高级话题而是一个逃不掉但又不想面对的话题映射文件里只是一段composite-id真正用起来却牵出实体划分、缓存判断、关联查询、级联操作等一系列连锁反应。这篇想把我在联合主键上攒下的经验整理一遍包括它适合落在哪些业务表上、标准的映射和加载方式、查询时的正确姿势以及几个真正让人血压升高的坑。无论你是 NHibernate 新手还是已经被 composite-id 折磨过一轮正在找答案的人这篇应该都能接住你。1. 为什么我在项目里会对 composite-id 又爱又恨1.1 业务上绕不开的联合主键场景从数据库设计的角度来说联合主键一直是个传统但不讨好的方案传统在于它完全符合关系模型的自然语义不讨好在于它对 ORM、迁移脚本、缓存逻辑都不太友好。我在实际项目里见到最多的是三类表多对多的中间表例如一个采购批次与供应商的关联表业务上本来就靠两个外键联合唯一标识一行没有独立存在的意义。明细行表典型的是订单号加行号、结算单号加明细序号。这类自然主键几乎是业务同学张口就来的查询条件用它们做主键非常直观。历史归档表与快照表把某一时刻的版本信息落库业务唯一键就是某某编号 时间点的组合。这些场景下单列自增主键完全可行但问题是你把自增 ID 当作表主键之后业务上的唯一性约束依然要靠那几个业务字段去兜底等于一个表里同时存在伪主键和真主键两套身份。每次查询都带着两套条件的心理负担而行数一多、索引一复杂味道就更明显。1.2 NHibernate 对联合主键的态度支持但不热情NHibernate 是支持联合主键映射的这一点从 Hibernate 时代就延续了下来。支持归支持代价很具体你得额外设计一个主键类比如OrderItemId你得老老实实实现Equals和GetHashCode你在使用session.Get()、缓存判断、一对多关联时都要随时意识到这里不是单值主键。官方文档里关于 composite-id 的篇幅不长示例语焉不详查资料时经常要靠社区博客补课。我自己的体会是NHibernate 的联合主键更像是为了兼容关系模型而保留的通道而不是它推荐的主流路径。它默认的id生成策略、级联保存、缓存比对全都围绕单值主键优化过。联合主键能用但你要自己承担更多细节。正因如此我才会说又爱又恨——业务语义上它省心工程处理上它费心。理解了 NHibernate 的这个底层态度后面很多为什么这么写的疑问就都能解释通了。2. 联合主键的正规映射.hbm.xml 里的 composite-id 写法2.1 key-property最基础也最常见的联合主键映射先把最标准的写法摆出来。假设有一张订单明细表OrderItem业务主键是OrderId ProductId在 .hbm.xml 里可以这样映射class nameOrderItem tableOrderItem composite-id nameId classOrderItemId key-property nameOrderId columnOrderId typeint/ key-property nameProductId columnProductId typeint/ /composite-id property nameQuantity columnQuantity/ property namePrice columnPrice/ /class对应的实体类和主键类public class OrderItem { public virtual OrderItemId Id { get; set; } public virtual int Quantity { get; set; } public virtual decimal Price { get; set; } } public class OrderItemId { public virtual int OrderId { get; set; } public virtual int ProductId { get; set; } public override bool Equals(object obj) { if (obj null || !(obj is OrderItemId other)) return false; return OrderId other.OrderId ProductId other.ProductId; } public override int GetHashCode() { unchecked { int hash 17; hash hash * 31 OrderId.GetHashCode(); hash hash * 31 ProductId.GetHashCode(); return hash; } } }这里我使用了nameIdclassOrderItemId的独立主键类方式而不是把主键属性直接铺在实体类上的嵌入式写法。为什么推荐独立的类因为实际项目中联合主键几乎都需要被拿来比较、放进集合、作为查询参数传递。独立成类之后Equals和GetHashCode的责任边界清晰序列化也更简单嵌入式的写法虽然省一个类但每次比较主键都得到实体里摸那几个属性代码容易散。提示联合主键类必须有公开无参构造函数并且建议标记[Serializable]。当你的实体要进二级缓存、要跨进程传递或者走 WCF/WCF-like 服务边界时没加这个特性会直接翻车。2.2 key-many-to-one主键里挂着外键时的处理比key-property更复杂一点的是联合主键的某一列本身是对另一张表的外键引用。比如订单明细的主键是OrderId ProductId而OrderId又引用Order表。这时可以改用key-many-to-oneclass nameOrderItem tableOrderItem composite-id nameId classOrderItemId key-many-to-one nameOrder columnOrderId classOrder/ key-many-to-one nameProduct columnProductId classProduct/ /composite-id property nameQuantity columnQuantity/ /class主键类变为持有引用类型的属性public class OrderItemId { public virtual Order Order { get; set; } public virtual Product Product { get; set; } }这样做的最大好处是在 HQL 和 QueryOver 里可以直接沿着Id.Order.OrderNo这样的路径查询从明细反查主单非常自然。但同时它也有隐藏成本——加载OrderItem时ID 中的关联对象会根据你的抓取策略被自动加载也就是说主键本身就是一条关联链路。如果你没配好 lazy loading某些列表查询会多出不少 SQL。用key-many-to-one时Equals和GetHashCode别直接调用关联对象的属性做散列尤其是关联对象是代理proxy时可能会触发额外的数据库访问甚至引发LazyInitializationException。稳妥的做法是给OrderItemId额外保存关联对象的外键值int 或 long 型用标量值做比较和散列。2.3 联合主键实体类的两个硬性要求第一所有映射属性都要是virtual的。NHibernate 默认用代理子类实现延迟加载和变更跟踪属性非 virtual 会导致运行期直接报错或静默失效。这一点对联合主键尤其重要因为主键属性同样需要代理支持。第二实体类要有一个公开的、无参的构造函数。很多新手把自己的实体构造函数设计成必须传业务参数结果 NHibernate 在反射创建对象时直接抛异常。这个要求对普通单主键实体也一样但联合主键场景更敏感——因为你多了主键类、关联属性等多处构造点任何一个构造函数访问修饰符设错了排查起来都更费劲。3. 加载与查询联合主键在工作流里的正确打开方式3.1 session.Get() 按联合主键取数加载一个单主键实体大家习惯写session.GetOrder(1)。联合主键则需要你提前构造主键对象var id new OrderItemId { OrderId 1001, ProductId 2002 }; var item session.GetOrderItem(id); // item 为 null 表示该组合主键不存在这里有一个很容易犯的错误直接传两个 int 进去。NHibernate 的GetT(object id)方法要求传入的对象类型与映射中声明的 ID 类型一致传错了类型时行为很迷惑——有的版本直接抛InvalidCastException有的版本静默返回 null让你误以为表里没有数据。所以我的习惯是凡是用联合主键加载实体都写一个明确命名的小工具方法比如LoadOrderItem(orderId, productId)内部完成主键对象的构造避免各处散落new OrderItemId { ... }的重复代码。如果使用session.LoadOrderItem(id)同样要传主键对象。注意 Load 返回的是代理如果主键不存在访问实体属性时才抛异常。3.2 HQL 和 QueryOver 里的主键判断HQL 里最常见的两种联合主键查询写法。一种是按主键类整体比较var id new OrderItemId { OrderId 1001, ProductId 2002 }; var list session .CreateQuery(from OrderItem oi where oi.Id :id) .SetParameter(id, id) .ListOrderItem();另一种是按主键内部属性比较from OrderItem oi where oi.Id.OrderId :orderId and oi.Id.ProductId :productIdQueryOver 的写法类似var list session.QueryOverOrderItem() .Where(oi oi.Id.OrderId orderId) .And(oi oi.Id.ProductId productId) .List();用 QueryOver 时要注意oi.Id.OrderId是表达式里对两层属性取值的写法编译器没问题但 NHibernate 解析表达式时依赖属性路径。如果Id的setter不是virtual这块会出现运行时解析异常。我在升级一个老项目的 NHibernate 版本时遇到过这个现象最后检查下来就是历史代码里Id的 setter 没加virtual。提示如果主键类用了key-many-to-oneHQL 里可以直接写where oi.Id.Order.OrderNo :no不必先查 Order 再关联。路径解析会按照映射关系生成对应的外键条件比先查外键对象再 in 查询高效得多。3.3 多个子表引用联合主键时的外键映射联合主键表的被引用场景是另一个容易踩雷的地方。假设OrderItem还有一张扩展表OrderItemRemark它要引用OrderItem的两个主键列。映射可以这样写class nameOrderItemRemark tableOrderItemRemark id nameId columnId typelong generator classnative/ /id many-to-one nameOrderItem classOrderItem column nameOrderId/ column nameProductId/ /many-to-one property nameRemark columnRemark/ /class关键在于column的顺序必须与OrderItem主键列的顺序一致。如果OrderItem的composite-id里先写OrderId再写ProductId那么子表的many-to-one里也必须先OrderId列再ProductId列。顺序错乱 NHibernate 不会报映射错误但运行时生成的外键条件会对不上轻则查不出数据重则更新时会把错误的外键值写进库。我自己吃过一次亏当时给一个老表加扩展表建表脚本里列顺序是按ProductId 在前、OrderId 在后建的映射里顺手照搬结果数据分析阶段一切正常到了真正跨实体查询时怎么都关联不上。最后逐条对比生成的 SQL 才定位到列顺序问题。这个经验让我养成了一个习惯凡是涉及复合外键的映射我先看主表composite-id的顺序再对着建表脚本检查子表列定义顺序不一致绝不碰代码。4. 真实踩坑联合主键真正让人头疼的六类问题4.1 Equals 与 GetHashCode 不实现集合缓存全乱套这是所有联合主键项目里最著名的坑。NHibernate 内部判断两个实体是否相同、一级缓存能否命中、集合里是否已存在某元素都依赖实体的标识值。单值主键由数据库生成你通常不关心Equals联合主键时实体标识是多个业务字段的组合如果你没有为OrderItemId实现Equals和GetHashCode那么两个字段值相同但引用不同的对象会被当成两个不同实体。后果包括session.Get()之后一级缓存里可能堆积多个同一主键的重复对象在事务提交时产生重复更新。把实体加进HasSet等去重集合时同一个明细会出现两份。一对多集合对比时级联删除的判定会错乱——你以为删一条结果删一堆或者一条都没删掉。GetHashCode的写法也有讲究。我见过有人直接用OrderId.GetHashCode() ProductId.GetHashCode()这也能工作但散列质量不如质数乘加的方式。上面 2.1 里的写法31 的倍数累加是社区常见的稳定版本散列冲突概率低性能也够用。重要的是Equals里要对类型做is判断而不是直接强转避免子类代理对象参与比较时出错。4.2 瞬态对象判断unsaved-value 带来的保存陷阱NHibernate 保存一个对象前要先判断它是全新的还是已存在的核心依据就是主键的状态。对数据库生成主键来说主键为 0 或 null 即瞬态联合主键则微妙得多。如果你使用独立主键类不要在新建对象时傻乎乎地给它 new 一个默认主键对象// 错误示范Id 不为 nullNHibernate 可能认为这是持久化对象 var item new OrderItem { Id new OrderItemId { OrderId 0, ProductId 0 }, Quantity 5, Price 10 }; session.Save(item);上面这种写法会让Save变成Update或直接插入失败因为 NHibernate 根据unsaved-value判断对象状态时发现 Id 不是 null、不是默认值于是把它当成托管detached对象处理。正确做法是让新对象的Id保持 null保存完成后 NHibernate 会把主键对象回写到实体上。var item new OrderItem { Id null, Quantity 5, Price 10 }; session.Save(item);这个坑特别隐蔽因为项目初期插入的数据量少往往侥幸成功数据量一大、开启批量插入batch insert后行为就会因为对象状态判断出错而变得诡异。4.3 主键字段可变化动一下就是一场灾难联合主键本质上是业务自然键而业务自然键最大的问题就是会变。比如订单明细的ProductId因为商品合并需要统一换成新 ID或者行号因为插入新行需要重新排序。在数据库层面改主键值意味着要同步更新所有引用该行的外键。在 NHibernate 层面你修改一个已经持久化实体的Id.OrderId属性然后在同一 Session 里提交会得到一条非常不友好的异常甚至导致一级缓存里新旧两个实体并存。我不止一次在微信群看到同行问为什么改了联合主键字段后保存报错答案很简单联合主键字段在设计上应该被当成只读。业务上需要改标识时正确姿势是删除旧记录、插入新记录而不是改主键。这个原则要写进团队规范里否则迟早埋雷。4.4 和迁移脚本、Schema 工具的兼容性联合主键在 NHibernate 自己的SchemaExport工具里生成建表 SQL 没有问题但和很多第三方迁移工具配合很别扭。许多自动生成迁移脚本的工具对联合主键的支持都属于能读但生成逻辑有问题的程度外键名自动生成规则不一致、修改列类型时主键列被跳过、甚至把联合主键误判成普通索引。我的建议是联合主键表的表结构变更尽量手写迁移 SQL不要依赖自动 diff。变更动作也要保守例如给联合主键表增加列、加索引是安全的修改主键列的数据类型或长度则要非常谨慎先确认影响范围再操作。我在某项目里给联合主键列从varchar(20)扩到varchar(50)因为忽视了外键关联表的列定义导致迁移后子表关联查询索引失效慢查询一堆最后补了一次全表重建索引才救回来。4.5 key-many-to-one 引发的懒加载问题前面提过用key-many-to-one时主键里挂着关联对象。它有一个典型的连带问题当你批量查询实体列表并输出主键里的关联信息时如果不小心访问了未初始化的代理关联就会触发经典的LazyInitializationException。比如在列表页里循环item.Id.Order.OrderNoSession 一旦关闭这里就炸了。解决思路通常是查询时显式指定抓取策略在 HQL 里写fetch或使用QueryOver的Fetch(oi oi.Id.Order).Eager。这个配置位置很反直觉——不是写在主实体属性上而是写在外层查询里。我曾经在映射文件里给Order属性配置了lazyfalse想图省事结果列表页 N1 查询直接压垮了数据库。正确做法是默认保持 lazy按需在查询里 fetch或者干脆避免使用key-many-to-one改用key-property存外键标量值。4.6 跨数据库方言下的列类型与排序联合主键对列类型更敏感。在 SQL Server 上char和varchar的比较规则、排序规则都有细节差异在 PostgreSQL 上大小写敏感的 collation 会让主键比较变得微妙。比如某字段在 SQL Server 下默认是不区分大小写的但换到 PostgreSQL 的默认 collation 就区分大小写。如果主键列是字符串类型在迁移数据库时这类差异会直接造成同样的逻辑查不到数。避开这类问题不完全靠 NHibernate更靠建表规范主键列使用统一约定比如字符串主键列统一用varchar且固定长度避免char补位问题关键列明确 collation。至少要在项目早期定下这个规范否则等数据量上来再改主键列类型成本极高。5. 权衡与替代代理主键到底香不香5.1 大多数项目的选择代理主键为何成为默认社区里谈到联合主键时最常见的建议其实是换成代理主键也就是给表加一个自增 ID 列业务字段用唯一约束保证语义唯一。这个方案在 NHibernate 下的优势是全方位的主键判断简单Equals和GetHashCode可以直接用 Id 的默认实现关联映射不用关心多列顺序二级缓存和查询缓存的键生成没有歧义批量更新、删除的性能也更好。代价也很明确表里多了一个对业务没有任何意义的列查询时不能直接用业务键做主键加载每次取数要么多一层Id ?的条件要么靠唯一约束索引再转一道。但客观说对绝大多数 OLTP 系统这个代价完全可以接受换来的工程确定性非常值。5.2 我仍然会保留 composite-id 的场景尽管代理主键是主流我也不会全盘否定联合主键。结合实战经验我觉得这几类场景保留它是合理的纯关联的中间表只有两个外键列、没有其他业务字段时用联合主键最干净。如果这个中间表未来要加创建时间、操作人等字段那就该考虑代理主键了。只读的历史快照表业务主键固定不变整个生命周期没有更新操作。联合主键可以减少一层无意义的自增列查询时直接走业务键。领域模型中自然主键语义极强的实体比如行政区划编码 年月这种组合换掉反而让模型失真。在这些场景里只要严格实现Equals/GetHashCode、把主键字段当不可变值运维成本是可控的。5.3 从 composite-id 迁移到代理主键的落地步骤如果你已经在维护一个联合主键项目决定迁移到代理主键这里有我总结的落地顺序数据库先行给表增加自增 ID 列暂时保留原联合主键给原业务字段组合加唯一约束确保迁移过程中不会产生重复业务键。映射切换把composite-id改成id 自增生成器原业务字段变成普通property子表外键关联从多列改为单一 ID 列。代码改造把OrderItemId相关的Equals、查询条件、关联路径全部改为新 ID凡是用到oi.Id.OrderId的代码统一改成oi.OrderId。分阶段发布先让读路径走新 ID 查询跑一段时间确认数据一致再切换写入路径最后删除旧的联合主键约束和多余的复合索引。迁移过程中最容易出问题的是关联清理如果有别的表用复合外键引用旧联合主键必须先改这些表的外键再动主表。顺序反了数据库会把你的迁移操作直接拦下来。我在迁移某结算模块时就是因为漏查了一张归档表发布后线上报错回滚又花了一整晚。最终我总结出一个检查清单确认所有引用表、所有视图里的关联条件、所有缓存键相关代码三者都处理干净才允许动主表的最后一步。最后再说两句说实话联合主键在 NHibernate 里并不是不能用的技术它更像一个需要纪律的方案纪律体现在不可变主键、规范的Equals/GetHashCode、严格的列顺序、以及应用层查询路径的整齐划一。如果团队能守住这些纪律联合主键能为模型保留完整的业务语义如果守不住代理主键是更稳妥的兜底。我在实际项目里的体会是别在建模阶段贪图自然主键很好看而随手用联合主键先想清楚这张表未来会不会被多条关联路径引用、主键字段会不会变、要不要做批量更新。想清楚了再决定比踩坑之后再迁移省心得多。如果你现在已经卡在某个联合主键的报错上建议从第 4 节的几个坑开始逐一排查尤其是Equals和unsaved-value那两条大概率能解决你八成的问题。
