TypeORM EntityManager API 全面解析

TypeORM EntityManager API 全面解析

typeorm TypeORM 是一个用于 JavaScript 和 TypeScript 的 ORM（对象关系映射）库，用于在 Node.js 中操作关系数据库。* 提供了一种将 JavaScript 对象映射到关系数据库中的方法；支持多种数据库，如 MySQL、PostgreSQL、MariaDB、SQLite 等；支持查询构建器和实体关系映射。* 特点：支持 TypeScript；支持异步操作；支持迁移和种子功能；支持复杂查询。 项目地址: https://gitcode.com/gh_mirrors/ty/typeorm

前言

EntityManager 是 TypeORM 中最核心的组件之一，它提供了与数据库交互的各种方法。本文将全面解析 EntityManager 的 API 功能和使用方法，帮助开发者更好地掌握 TypeORM 的核心操作。

基础属性

dataSource 属性

dataSource 属性返回当前 EntityManager 使用的数据源实例。这在需要访问数据库连接配置或执行底层操作时非常有用。

const dataSource = manager.dataSource;

queryRunner 属性

queryRunner 属性仅在事务性 EntityManager 实例中可用，返回当前使用的事务查询运行器。

const queryRunner = manager.queryRunner;

事务管理

transaction 方法

transaction 方法提供了一个事务执行环境，所有数据库操作将在单个事务中执行。

await manager.transaction(async (transactionalEntityManager) => {
    // 必须使用传入的 transactionalEntityManager 执行所有操作
    await transactionalEntityManager.save(user);
    await transactionalEntityManager.save(order);
});

重要提示：事务回调中必须使用传入的 EntityManager 实例，而不是外部的 manager。

原始 SQL 操作

query 方法

query 方法允许执行原始 SQL 查询，支持多种数据库的参数化查询语法：

// MySQL风格参数
await manager.query('SELECT * FROM users WHERE name = ?', ['John']);

// PostgreSQL风格参数
await manager.query('SELECT * FROM users WHERE name = $1', ['John']);

// Oracle风格参数
await manager.query('SELECT * FROM users WHERE name = :1', ['John']);

sql 标签方法

sql 标签方法提供了一种更安全的模板字符串方式来构建 SQL 查询：

const name = 'John';
const age = 25;
const users = await manager.sql`SELECT * FROM users WHERE name = ${name} AND age = ${age}`;

查询构建器

createQueryBuilder 方法

createQueryBuilder 创建查询构建器实例，用于构建复杂的 SQL 查询：

const users = await manager
    .createQueryBuilder(User, 'user')
    .where('user.age > :age', { age: 18 })
    .orderBy('user.name', 'ASC')
    .getMany();

实体操作

实体创建与合并

• create：创建新实体实例
• merge：合并多个实体或对象到一个实体

// 创建新用户
const user = manager.create(User, {
    name: 'John',
    age: 30
});

// 合并属性
manager.merge(User, user, { age: 31 }, { isActive: true });

preload 方法

preload 从普通对象创建实体，如果实体已存在则从数据库加载并更新：

const partialUser = { id: 1, name: 'Updated Name' };
const user = await manager.preload(User, partialUser);

CRUD 操作

保存与删除

• save：保存实体（插入或更新）
• remove：删除实体

// 保存单个或多个实体
await manager.save(user);
await manager.save([user1, user2]);

// 删除实体
await manager.remove(user);
await manager.remove([user1, user2]);

批量操作

• insert：批量插入
• update：条件更新
• delete：条件删除

// 批量插入
await manager.insert(User, [
    { name: 'John', age: 25 },
    { name: 'Jane', age: 22 }
]);

// 条件更新
await manager.update(User, { age: 18 }, { status: 'ADULT' });

// 条件删除
await manager.delete(User, { status: 'INACTIVE' });

upsert 方法

upsert 实现"存在则更新，不存在则插入"的操作：

await manager.upsert(
    User,
    [
        { email: 'john@example.com', name: 'John' },
        { email: 'jane@example.com', name: 'Jane' }
    ],
    ['email']  // 冲突判断字段
);

查询方法

基本查询

• find：条件查询
• findOne：查询单条记录
• findAndCount：查询并计数（分页常用）

// 条件查询
const activeUsers = await manager.find(User, {
    where: { isActive: true }
});

// 查询单条
const john = await manager.findOne(User, {
    where: { name: 'John' }
});

// 查询并计数
const [users, total] = await manager.findAndCount(User, {
    skip: 10,
    take: 20
});

存在性检查

• exists：检查是否存在符合条件的记录
• count：计数符合条件的记录

const hasAdmins = await manager.exists(User, {
    where: { role: 'admin' }
});

const userCount = await manager.count(User, {
    where: { isActive: true }
});

特殊操作

数值增减

• increment：增加数值字段
• decrement：减少数值字段

// 年龄增加1
await manager.increment(User, { id: 1 }, 'age', 1);

// 积分减少10
await manager.decrement(User, { id: 1 }, 'points', 10);

清空表

clear 方法清空整个表数据：

await manager.clear(User);  // TRUNCATE TABLE user

仓库获取

获取不同类型仓库

• getRepository：获取常规仓库
• getTreeRepository：获取树形结构仓库
• getMongoRepository：获取MongoDB专用仓库

const userRepository = manager.getRepository(User);
const categoryRepository = manager.getTreeRepository(Category);
const mongoUserRepository = manager.getMongoRepository(User);

总结

EntityManager 提供了全面的数据库操作方法，从基础的 CRUD 到复杂的事务管理，涵盖了大多数数据库操作场景。掌握这些 API 能够帮助开发者更高效地使用 TypeORM 进行数据持久化操作。在实际开发中，应根据具体场景选择合适的方法，特别注意事务操作中的 EntityManager 实例使用。

typeorm TypeORM 是一个用于 JavaScript 和 TypeScript 的 ORM（对象关系映射）库，用于在 Node.js 中操作关系数据库。* 提供了一种将 JavaScript 对象映射到关系数据库中的方法；支持多种数据库，如 MySQL、PostgreSQL、MariaDB、SQLite 等；支持查询构建器和实体关系映射。* 特点：支持 TypeScript；支持异步操作；支持迁移和种子功能；支持复杂查询。 项目地址: https://gitcode.com/gh_mirrors/ty/typeorm