如何扩展TypeORM QueryBuilder？自定义构建器遇EntityMetadataNotFoundError报错

问题重现 #

尝试为TypeORM的SelectQueryBuilder扩展自定义方法时，运行时抛出EntityMetadataNotFoundError，相关代码及错误信息如下：

实体与数据源定义 #

import { Column, Entity, PrimaryGeneratedColumn } from 'typeorm'

@Entity()
export class User {
  @PrimaryGeneratedColumn('uuid')
  id!: string

  @Column()
  name!: string
}

export const AppDataSource = new DataSource({
  ...config,
  entities: [User],
})

自定义QueryBuilder实现 #

import { SelectQueryBuilder } from 'typeorm'

class CustomUserQueryBuilder extends SelectQueryBuilder<User> {
  constructor() {
    super(AppDataSource.createQueryBuilder())
    this.from(User, 'user')
  }
  async customLeftJonAndSelect() {
    return this.where(`...`)
  }
}

const customQb = new CustomUserQueryBuilder()
customQb.select('*').customLeftJonAndSelect().getQuery()

错误信息 #

EntityMetadataNotFoundError: No metadata for "User" was found: this.from(User, 'user')
                                                                        ^

错误原因 #

1. 数据源未完成初始化：AppDataSource创建后必须调用initialize()方法完成初始化流程，否则TypeORM无法加载实体的元数据。
2. 继承逻辑不合理：直接继承SelectQueryBuilder并在构造函数中调用this.from(User, 'user')时，实体元数据可能还未被TypeORM完成注册。

正确实现方案 #

方案一：确保数据源初始化后创建自定义QueryBuilder #

先完成数据源初始化，再基于已初始化的仓库创建基础QueryBuilder，再扩展自定义方法：

import { SelectQueryBuilder } from 'typeorm'
import { AppDataSource, User } from './your-file-path'

// 先完成数据源初始化
await AppDataSource.initialize()

class CustomUserQueryBuilder extends SelectQueryBuilder<User> {
  constructor(baseQb: SelectQueryBuilder<User>) {
    super(baseQb)
  }

  customLeftJoinAndSelect() {
    // 示例自定义逻辑：添加左连接与筛选条件
    return this.leftJoinAndSelect('user.relatedEntity', 'related')
      .where('user.name IS NOT NULL')
  }
}

// 通过User仓库创建基础QueryBuilder，传入自定义构造函数
const baseQb = AppDataSource.getRepository(User).createQueryBuilder('user')
const customQb = new CustomUserQueryBuilder(baseQb)

const query = customQb.select('*').customLeftJoinAndSelect().getQuery()
console.log(query)

方案二：使用Mixin方式全局扩展QueryBuilder #

如果需要更灵活的全局扩展，可以用Mixin方式为所有QueryBuilder添加自定义方法：

import { SelectQueryBuilder } from 'typeorm'

// 定义扩展方法
function CustomQueryBuilderMixin<T>(qb: SelectQueryBuilder<T>) {
  return {
    customLeftJoinAndSelect(this: SelectQueryBuilder<T>) {
      // 泛化自定义逻辑，可根据当前QueryBuilder的别名适配不同实体
      return this.leftJoinAndSelect(`${this.alias}.relatedEntity`, 'related')
        .where(`${this.alias}.name IS NOT NULL`)
    }
  }
}

// 扩展TypeORM的SelectQueryBuilder类型声明
declare module 'typeorm' {
  interface SelectQueryBuilder<T> {
    customLeftJoinAndSelect(): SelectQueryBuilder<T>
  }
}

// 将扩展方法挂载到QueryBuilder原型
Object.assign(SelectQueryBuilder.prototype, CustomQueryBuilderMixin())

// 使用方式（确保数据源已初始化）
await AppDataSource.initialize()
const qb = AppDataSource.getRepository(User).createQueryBuilder('user')
const query = qb.select('*').customLeftJoinAndSelect().getQuery()
console.log(query)

方案三：工厂函数封装自定义QueryBuilder #

不想使用继承的话，可以用工厂函数封装带有自定义方法的QueryBuilder：

import { SelectQueryBuilder } from 'typeorm'
import { AppDataSource, User } from './your-file-path'

async function createCustomUserQueryBuilder(): Promise<SelectQueryBuilder<User> & { customLeftJoinAndSelect: () => SelectQueryBuilder<User> }> {
  await AppDataSource.initialize()
  const qb = AppDataSource.getRepository(User).createQueryBuilder('user')
  
  // 为QueryBuilder实例添加自定义方法
  const customQb = qb as typeof qb & { customLeftJoinAndSelect: () => typeof qb }
  customQb.customLeftJoinAndSelect = function() {
    return this.leftJoinAndSelect('user.relatedEntity', 'related')
      .where('user.name IS NOT NULL')
  }
  
  return customQb
}

// 使用示例
const customQb = await createCustomUserQueryBuilder()
const query = customQb.select('*').customLeftJoinAndSelect().getQuery()

关键注意点 #

• 必须初始化数据源：所有QueryBuilder操作前，务必调用await AppDataSource.initialize()，确保TypeORM加载完所有实体元数据。
• 避免构造函数直接操作实体：继承SelectQueryBuilder时，优先基于已有的、关联了实体的QueryBuilder实例初始化，避免元数据未就绪的问题。

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