@IdClass仅影响JPA实体映射，不自动生成MySQL复合索引，需手动创建对应索引并确保查询条件顺序、实体字段顺序、SQL列顺序与主键类定义严格一致，且不可混用@EmbeddedId。
在 Java 自定义 ORM 中使用 @IdClass 处理联合主键时，MySQL 的复合索引查询不能靠注解自动生效，需手动保证索引存在、查询条件顺序匹配、实体构造正确，否则容易全表扫描或查不到数据。
确保 MySQL 表上有对应复合索引
@IdClass 只影响 JPA/Hibernate 的实体映射，不生成数据库索引。必须显式为联合主键字段创建复合索引（即使主键本身已隐含聚簇索引，但非主键查询或覆盖查询仍依赖二级索引）：
- 如果联合主键是
(order_id, item_seq)，且常按order_id = ? AND item_seq = ?查询，主键本身已支持高效查找； - 但如果常查
order_id = ?（只用第一个字段），或order_id = ? AND status = ?，就需要额外建复合索引，例如：
ALTER TABLE order_item ADD INDEX idx_order_seq (order_id, item_seq); - 注意字段顺序：索引最左前缀原则生效，
(a,b)索引可加速a=?或a=? AND b=?，但无法加速b=?单独查询。
查询时保持字段顺序与 @IdClass 类一致
@IdClass 要求提供一个独立的主键类，其字段名和类型必须与实体中 @Id 字段完全一致，且顺序决定 JPA 构造主键对象的逻辑：
- 假设
OrderItemPK定义为：
public class OrderItemPK {
private Long orderId;
private Integer itemSeq;
// 必须有无参构造、equals/hashCode
} - 则 JPQL 查询必须按相同顺序传参：
em.createQuery("SELECT o FROM OrderItem o WHERE o.id.orderId = :oid AND o.id.itemSeq = :seq", OrderItem.class)
.setParameter("oid", 1001L).setParameter("seq", 2); - 若 HQL 或 Criteria API 中字段顺序颠倒，虽语法不报错，但可能触发错误的绑定或缓存失效。
避免在 @IdClass 实体中混用 @EmbeddedId
同一个实体不能同时使用 @IdClass 和 @EmbeddedId —— 这是 JPA 规范禁止的。常见误用场景：
立即学习“Java免费学习笔记（深入）”；
- 有人为“方便”在实体里保留一个
@EmbeddedId字段，又用@IdClass声明主键，导致 Hibernate 启动失败或运行时行为异常； - 正确做法：二选一。
@IdClass更适合简单联合主键，且主键字段直接暴露在实体中；@EmbeddedId更适合复用主键结构或需封装逻辑的场景； - 若已用
@IdClass，所有主键字段必须是实体的普通字段（如private Long orderId;），并配@Id，且主键类中字段名严格对应。
原生 SQL 查询需显式指定字段别名与顺序
自定义 ORM 执行原生 SQL 时，@IdClass 不参与结果映射，必须手动对齐：
- SELECT 字段顺序必须与主键类构造器或
ResultSet映射顺序一致，例如：
SELECT order_id AS orderId, item_seq AS itemSeq FROM order_item WHERE ... - 若用
new OrderItemPK(order_id, item_seq)构造，SQL 返回列顺序必须严格匹配构造参数顺序； - 建议配合
@SqlResultSetMapping或手动ResultSet解析，避免依赖字段名自动匹配（易因大小写或别名缺失出错）。
