TypeORM中ObjectLiteral格式Where条件触发异常的原因

我使用TypeORM的QueryBuilder进行查询时，遇到一个奇怪的问题：用对象字面量格式写关联实体的条件会触发异常，但换成字符串格式就可以正常运行。

报错的代码示例 #

const queryBuilder = this.usersRepository.createQueryBuilder('user');
const where = this.findQueryBuilder(options);

const result = queryBuilder
  .leftJoinAndSelect('user.roles', 'role')
  .andWhere((qb) => {
    if (caslQueries.length > 0) {
      const [firstQuery, ...otherQueries] = caslQueries;
      qb.where(firstQuery);
      otherQueries.forEach((query) => qb.orWhere(query));
    }
  })
  .andWhere(where)
  .andWhere({ 'role.name': 'guest' })

触发的异常 #

• EntityPropertyNotFoundError: Property "role.name" was not found in "UserEntity". Make sure your query is correct.

正常运行的代码示例 #

const queryBuilder = this.usersRepository.createQueryBuilder('user');
const where = this.findQueryBuilder(options);

const result = queryBuilder
  .leftJoinAndSelect('user.roles', 'role')
  .andWhere((qb) => {
    if (caslQueries.length > 0) {
      const [firstQuery, ...otherQueries] = caslQueries;
      qb.where(firstQuery);
      otherQueries.forEach((query) => qb.orWhere(query));
    }
  })
  .andWhere(where)
  .andWhere('role.name = :role', { role: 'guest' })

原因解析 #

核心差异在于TypeORM对两种格式条件的解析逻辑：

1. 对象字面量格式：TypeORM会默认将对象的键当作主实体（UserEntity）的直接属性来解析，它不支持role.name这种跨关联实体的点路径写法。所以它会在UserEntity里查找名为role.name的属性，自然找不到，抛出异常。
2. 字符串格式：TypeORM会直接把字符串当作SQL片段处理，能识别到role是你通过leftJoinAndSelect定义的关联实体别名，从而正确解析role.name指向关联的Role实体的name属性。

如果一定要用对象格式处理关联条件，你需要针对关联实体单独构建查询，比如先关联实体后，用该实体的别名来构建对象条件，但对象格式本身不支持跨实体的嵌套路径。

内容的提问来源于stack exchange，提问作者arianpress