MikroORM中嵌入式属性的Upsert操作问题解析

问题背景

在使用MikroORM进行数据库操作时，开发者遇到了一个关于嵌入式属性(Embedded Property)在upsert操作中的异常行为。具体表现为当尝试通过upsert方法更新已存在实体时，嵌入式属性无法被正确更新。

问题复现

首先我们来看一个典型的实体定义示例：

@Embeddable()
class Properties {
  @Property()
  tag: string;

  constructor(tag: string) {
    this.tag = tag;
  }
}

@Entity()
class User {
  @PrimaryKey()
  id!: number;

  @Property()
  name: string;

  @Property({ unique: true })
  email: string;

  @Embedded()
  properties: Properties;

  constructor(name: string, email: string, properties: Properties) {
    this.name = name;
    this.email = email;
    this.properties = properties;
  }
}

当执行以下upsert操作时：

await orm.em.upsert(User, {
  name: "Foo",
  email: "foo",
  properties: {
    tag: "foo2",
  },
});

如果数据库中已存在email为"foo"的用户记录，理论上应该更新该记录的所有字段，包括嵌入式属性properties.tag。然而实际生成的SQL语句中却缺少了对properties_tag字段的更新：

insert into `user` (`email`, `name`, `properties_tag`) 
values ('foo', 'Foo', 'foo2') 
on conflict (`email`) 
do update set `name` = excluded.`name` 
returning `id`, `properties_tag`

问题分析

这个问题源于MikroORM在处理嵌入式属性的upsert操作时存在两个关键缺陷：

1. 默认行为缺陷：当不显式指定onConflictMergeFields时，嵌入式属性不会被自动包含在更新字段中。

2. 显式指定时的语法问题：当尝试显式包含嵌入式属性时，直接使用"properties"会导致SQL语法错误，因为数据库层面实际存储的是展开后的字段properties_tag。

解决方案

经过深入分析，我们找到了几种可行的解决方案：

1. 完整路径指定法（推荐）：

await orm.em.upsert(
  User,
  {
    name: "Baz",
    email: "baz",
    properties: {
      tag: "baz2",
    },
  },
  {
    onConflictFields: ["email"],
    onConflictMergeFields: ["name", "properties.tag" as keyof User],
  }
);

这种方法通过完整指定嵌入式属性的路径（包含点号表示法）来精确控制需要更新的字段。

2. 直接字段名指定法：

await orm.em.upsert(
  User,
  {
    name: "Baz",
    email: "baz",
    properties: {
      tag: "baz2",
    },
  },
  {
    onConflictFields: ["email"],
    onConflictMergeFields: ["name", "properties_tag" as keyof User],
  }
);

这种方法直接使用数据库中的实际字段名，但可读性稍差。

技术原理

MikroORM在处理嵌入式属性时，会在数据库层面将其展开为多个列。例如，properties.tag会被映射为properties_tag列。在upsert操作中：

1. 默认情况下，ORM只会包含顶级字段在冲突更新中
2. 嵌入式属性需要显式指定其完整路径或实际列名
3. 类型断言(as keyof User)在某些情况下是必要的，以通过TypeScript的类型检查

最佳实践建议

1. 对于包含嵌入式属性的upsert操作，建议总是显式指定onConflictMergeFields
2. 优先使用点号表示法指定嵌入式属性的完整路径
3. 在团队开发中，应建立统一的编码规范来处理这类情况
4. 考虑为常用实体创建封装方法，避免重复处理这类问题

总结

MikroORM中嵌入式属性的upsert操作需要特别注意字段的指定方式。理解ORM如何将嵌入式属性映射到数据库列是解决这类问题的关键。通过本文介绍的方法，开发者可以确保嵌入式属性在各种操作场景下都能被正确处理。