返回文章列表 →

Note

TypeORM

TypeORM介绍和基本使用

发布于 更新于

TypeORM

ORM,Object Relational Mapping,对象关系映射。把“数据库世界”映射成“面向对象世界”,方便服务端操作数据库。如果不使用 ORM , 需要自己处理和数据相关的操作,如:

想查一个用户,传统方式可能需要写:

SELECT * FROM user WHERE id = 1;

Node.js 里可能变成:

const [rows] = await connection.query( ‘SELECT * FROM user WHERE id = ?’, [1], );

随着项目越来越复杂,不断地写SQL语句并且需要自己处理如SQL参数、数据转换、表关系、事务等等,会比较麻烦,所以就诞生了 ORM 。TypeORM 是 TypeScript/JavaScript 领域的 ORM 框架,负责 ORM 、SQL 生成、关系映射、事务等数据库操作。

TypeORM的映射关系

数据库

user 表

id       username       age
1        Tom            20
2        Jack           25

TypeORM

@Entity()
export class User {
  @PrimaryGeneratedColumn()
  id: number;

  @Column()
  username: string;

  @Column()
  age: number;
}

形成的映射关系

数据库 TypeORM
表 Entity 类
一行数据 Entity 对象
字段 类属性
主键 @PrimaryGeneratedColumn()
外键 Relation
SELECT find()
INSERT save() / insert()
UPDATE save() / update()
DELETE delete() / remove()

TypeORM核心对象

名称 作用
DataSource 管理数据库连接
Entity 描述数据库表
Repository 操作某一个 Entity
EntityManager 通用数据库操作入口
QueryBuilder 构建复杂 SQL
QueryRunner 管理单独连接/事务

相关库说明

包 作用
typeorm ORM 本体
@nestjs/typeorm NestJS 与 TypeORM 的集成

DataSource

TypeORM 与数据库之间的连接入口。它里面保存数据库类型、服务器地址、端口、用户名密码、数据库名称、Entity、连接池等等。

如果不使用 NestJS ,纯 TypeORM ,通过以下方式连接:

const dataSource = new DataSource({
  type: "mysql",
  host: "localhost",
  port: 3306,
  username: "root",
  password: "123456",
  database: "test",
  entities: [User],
});

await dataSource.initialize();

但是 NestJS 项目里通常不需要自己调用 new DataSource().initialize(),通过 TypeOrmModule.forRoot() 来实现:

// app.module.ts

import { Module } from "@nestjs/common";
import { TypeOrmModule } from "@nestjs/typeorm";

@Module({
  imports: [
    TypeOrmModule.forRoot({
      type: "mysql",
      host: "localhost",
      port: 3306,
      username: "root",
      password: "123456",
      database: "nestjs_test",
      autoLoadEntities: true,
      synchronize: true,
    }),
  ],
})
export class AppModule {}

参数

名称 含义 类型
type string 数据库类
host string 数据库服务器
port number 端口
username string 数据库账号
password string 数据库密码
database boolean 数据库名
entities array 连接的实体。如entities: [User,Product,Order,Category]
autoLoadEntities string 自动加载通过 TypeOrmModule.forFeature() 注册的 Entity 。如果不开启,需要手动使用 entities 来维护 Entity 。
synchronize boolean 数据库根据 Entity 自动同步数据库表结构。如在注册实体后,会自动创建对应的数据库表,实体字段修改后自动修改对应的表字段

synchronize 说明:

初始:

@Entity()
class User {
  @PrimaryGeneratedColumn()
  id: number;
}

增加字段:

@Column()
username: string;

在开启 synchronize 时,TypeORM 可以自动修改数据库表,所以数据库的User表也会增加username字段。开发环境中可以开启,但是生产环境自动同步可能导致数据风险,正式环境应该使用 Migration 。

Entity

告诉 NestJS 这个类是数据库 Entity ,用这个类描述数据库表结构。

表示User类是数据库 Entity

// user.entity.ts

import {
  Entity,
  PrimaryGeneratedColumn,
  Column,
  CreateDateColumn,
  UpdateDateColumn,
} from "typeorm";

@Entity("users")
export class User {
  @PrimaryGeneratedColumn()
  id: number;

  @Column({
    type: "varchar",
    length: 50,
    unique: true,
  })
  username: string;

  @Column({
    type: "int",
    nullable: true,
  })
  age: number | null;

  @Column({
    default: true,
  })
  isActive: boolean;

  @CreateDateColumn()
  createdAt: Date;

  @UpdateDateColumn()
  updatedAt: Date;
}

默认情况下类名会映射成表名,也可以显示指定数据库表明。推荐显示指定

// 表示:
// TypeScript 类:User
// 数据库表:users
@Entity("users")
export class User {}

@PrimaryGeneratedColumn()

自动生成的主键。还有一种 @PrimaryColumn() ,也是设置主键,但是值需要自己提供,通常使用 @PrimaryGeneratedColumn() 。如果需要 联合组建 ,把需要的字段都加上@PrimaryColumn() 即可,TypeORM会把它们组合成联合主键。

@Column()

映射数据库字段。如 Entity 属性的username => 数据库字段的username。 @Column() 常见参数:

参数 类型 作用
type string 数据库字段类型
name string 数据库字段名
length number 字符串长度
nullable boolean 是否允许 NULL,默认值 false
unique boolean 是否唯一
default - 默认值
select boolean 查询时是否默认返回,默认值 true 。密码字段常设置为 false
enum `` 枚举值
precision `` decimal 总位数
scale `` decimal 小数位数
// 对应:name VARCHAR(50)
@Column({
  type: 'varchar',
  length: 50,
})
name: string;

// 对应:age INT NULL。false对应 NOT NULL
@Column({
  nullable: true,
})
age: number | null;

@Column({
  unique: true,
})
email: string;

// TypeScript:user.username,数据库:user_name。也就是可以让"类属性名 ≠ 数据库字段名"
@Column({
  name: 'user_name',
})
username: string;

@CreateDateColumn()

添加数据时,自动新增时间。格式为: yyyy-mm-dd hh:mm:ss

@CreateDateColumn()
createdAt: Date;

@UpdateDateColumn()

修改数据时自动更新时间

@UpdateDateColumn()
updatedAt: Date;

@DeleteDateColumn()

删除时自动记录时间。用于 软删除

@DeleteDateColumn()
deletedAt: Date;

Entity 和 DTO的区别

两者都是数据模型,但是DTO用于描述接口输入/输出数据,Entity用于描述数据库数据。

Repository

专门负责操作某一个 Entity 的数据库工具对象。

获取Repository

注册

// 假设User的 Entity 已经定义好

@Module({
  imports: [
    // 在当前模块里注册 User 对应的 Repository
    TypeOrmModule.forFeature([User]),
  ],
  providers: [UsersService],
})
export class UsersModule {}

注入和获取

@Injectable()
export class UsersService {
  constructor(
    @InjectRepository(User)
    // 注入 User 对应的 Repository
    private readonly userRepository: Repository<User>,
  ) {}

  // 通过this.userRepository获取,这样就可以操作User表。如this.userRepository.find();
}

常用API

API 作用
create() 创建 Entity 对象,但不写数据库
save() 保存写入库。用于新增或更新
find() 查询多条
findBy() 按简单条件查询多条
findOne() 查询一条
findOneBy() 按简单条件查询一条
update() 直接更新
delete() 直接删除
remove() 删除 Entity
count() 数量统计
exists() 判断是否存在
findAndCount() 查询列表 + 总数

create()

创建 Entity 对象。create() 只是创建 Entity 实例,不执行 INSERT,也就是它不会操作数据库,需要通过 save() 保存才能入库。create是同步的。

参数与返回值
// 传对象
repository.create(
  data: DeepPartial<Entity>
): Entity;

// 传数组
repository.create(
  data: DeepPartial<Entity>[]
): Entity[];
参数 含义
data 符合 Entity 结构的对象或“部分对象”(即不需要所有字段全部传),或者这种对象组成的数组
示例
const user = this.userRepository.create({
  username: "Tom",
  age: 20,
});

// 返回:User { username: 'Tom', age: 20 }

save()

保存 Entity

参数与返回值
// 传对象
repository.save(
  entity: DeepPartial<Entity>,
  options?: SaveOptions,
): Promise<Entity>;

// 传数组
repository.save(
  entities: DeepPartial<Entity>[],
  options?: SaveOptions,
): Promise<Entity[]>;
参数 含义
Entity 符合 Entity 结构的对象或“部分对象”(即不需要所有字段全部传),或者这种对象组成的数组
options 高级配置
示例
const user = this.userRepository.create({
  username: "Tom",
  age: 20,
});

await this.userRepository.save(user);

// 也可以用以下方式,但是推荐通过create显示创建
// await this.userRepository.save({
//   username: 'Tom',
//   age: 20,
// });

// 可能返回:
// {
//   id: 1,
//   username: 'Tom',
//   age: 20,
//   isActive: true
// }

当数据不存在,save是INSERT,当数据存在,save是UPDATE

find()

查询多条数据。如果一条也没找到,返回空数组。

参数和返回值
repository.find(
  options?: FindManyOptions<Entity>
): Promise<Entity[]>;
参数 含义
options 查询配置对象
示例
const users = await this.userRepository.find({
  where: {
    isActive: true,
  },
  order: {
    id: "DESC",
  },
});

findBy()

按照简单条件查询多条

repository.findBy(
  where:
    | FindOptionsWhere<Entity>
    | FindOptionsWhere<Entity>[]
): Promise<Entity[]>;
参数 含义
where where 条件
示例
const users = await this.userRepository.findBy({
  age: 20,
  isActive: true,
});
// 相当于:WHERE age = 20 AND isActive = true
findOne()

查询一条数据

repository.findOne(
  options: FindOneOptions<Entity>
): Promise<Entity | null>;
参数 含义
options 查询配置对象
示例
const user = await this.userRepository.findOne({
  where: {
    id: 1,
  },
});

findOneBy()

按照简单条件查询一条数据

参数和返回值
repository.findOneBy(
  where:
    | FindOptionsWhere<Entity>
    | FindOptionsWhere<Entity>[]
): Promise<Entity | null>;
参数 含义
where where 条件
const user = await this.userRepository.findOneBy({
  id: 1,
});

update()

直接更新数据

参数与返回值
repository.update(
  criteria: id | ids | FindOptionsWhere<Entity>,
  partialEntity: QueryDeepPartialEntity<Entity>,
  options?: UpdateOptions,
): Promise<UpdateResult>;
参数 含义
criteria 需要被修改的数据
partialEntity 修改后的新值
options
class UpdateResult {
  raw: unknown;
  affected?: number;
  generatedMaps: object[];
}
参数 含义
raw 数据库驱动返回的原始结果,未经 TypeORM 统一格式化。无需使用,直接使用 affected 进行判断即可
affected 本次 UPDATE SQL 实际影响了多少行数据
generatedMaps 数据库额外生成了哪些实体字段
示例
const result = await this.userRepository.update(1, {
  age: 21,
});

// 相当于UPDATE users SET age = 21 WHERE id = 1;
// 注意返回值是result,不是User。如果想要User可以使用findOneBy查询

delete()

直接删除

参数和返回值
repository.delete(
  criteria: | id | id[] | FindOptionsWhere<Entity> | FindOptionsWhere<Entity>[]
): Promise<DeleteResult>;
参数 含义
criteria 要被删除的数据
示例
await this.userRepository.delete(1); // 相当于 DELETE FROM users WHERE id = 1;

remove()

删除 Entity ,需要传入实体,所以使用 remove 前需要获取实体。

参数和返回值
// 传对象
repository.remove(
  entity: Entity,
  options?: RemoveOptions
): Promise<Entity>;

// 传数组
repository.remove(
  entities: Entity[],
  options?: RemoveOptions
): Promise<Entity[]>;
参数 含义
entity 实体
options 高级配置对象
示例
const user = await repository.findOneBy({ id });

await repository.remove(user);

exists()

判断数据是否存在

参数和返回值
repository.exists(
  options?: FindManyOptions<Entity>
): Promise<boolean>;
参数 含义
options 完整查询配置
示例
const exists = await this.userRepository.exists({
  where: {
    username: "Tom",
  },
});

existsBy()

使用简单条件判断存在

参数与返回值
repository.existsBy(
  where:
    | FindOptionsWhere<Entity>
    | FindOptionsWhere<Entity>[]
): Promise<boolean>;
参数 含义
where where 条件
示例
const exists = await this.userRepository.existsBy({
  username: "Tom",
});

count()

统计数量

repository.count(
  options?: FindManyOptions<Entity>
): Promise<number>;
参数和返回值
参数 含义
options 完整查询配置
示例
const count = await this.userRepository.count({
  where: {
    isActive: true,
  },
});

countBy()

使用简单条件统计数量

参数和返回值
repository.countBy(
  where:
    | FindOptionsWhere<Entity>
    | FindOptionsWhere<Entity>[]
): Promise<number>;
参数 含义
where where 条件
示例
const count = await this.userRepository.countBy({
  isActive: true,
});

findAndCount()

查询数据和总数量,分页很常用

参数和返回值
repository.findAndCount(
  options?: FindManyOptions<Entity>
): Promise<[Entity[], number]>;
参数 含义
options 完整查询配置

注意返回值是个tuple,前面为数据,后面为数量。如[ User[], number ]

示例
const [users, total] = await repository.findAndCount({
  skip: (pages - 1) * pageSize,
  take: pageSize,
});

findAndCountBy()

使用简单条件查询数据和总数量

参数和返回值
repository.findAndCountBy(
  where:
    | FindOptionsWhere<Entity>
    | FindOptionsWhere<Entity>[]
): Promise<[Entity[], number]>;
参数 含义
where where 条件
示例
const [users, total] = await repository.findAndCountBy({
  isActive: true,
});

findOneOrFail()、findOneByOrFail()

和 findOne() 、 findOneBy() 作用一样,区别是 findOneOrFail() 、findOneByOrFail() 没有找到数据直接抛出异常。

sum() / average() / minimum() / maximum()

对查询结果进行运算,所以要求操作列必须是数字。

参数和返回值
repository.sum(
  columnName: 数字字段名,
  where?: FindOptionsWhere<Entity>
): Promise<number | null>;
参数 含义
columnName 数据库字段名
where where 条件
示例
// 求age列符合条件的数据的值总和
const totalAge = await repository.sum("age", {
  isActive: true,
});

查询配置对象FindOneOptions

查询配置对象 FindManyOptions 则是在 FindOneOptions 的基础上额外多了分页功能的 skip 和 take 这两个属性。

interface FindOneOptions<Entity> {
  // 查询哪些字段
  select?: FindOptionsSelect<Entity>;

  // WHERE 条件
  where?: FindOptionsWhere<Entity> | FindOptionsWhere<Entity>[];

  // 加载哪些关联关系
  relations?: FindOptionsRelations<Entity>;

  // 关系加载方式
  relationLoadStrategy?: "join" | "query";

  // ORDER BY
  order?: FindOptionsOrder<Entity>;

  // 查询缓存
  cache?: boolean | number | { id: any; milliseconds: number };

  // 数据库锁
  lock?: LockOptions;

  // 是否包含软删除数据
  withDeleted?: boolean;

  // 是否只加载 Relation ID
  loadRelationIds?:
    | boolean
    | { relations?: string[]; disableMixedMap?: boolean };

  // 是否加载 eager 关系
  loadEagerRelations?: boolean;

  // 查询是否放入事务执行
  transaction?: boolean;

  // 给 SQL 添加注释
  comment?: string;
}
select属性

设置要查询的字段,不传入默认查询全部字段

select?: {
  id?: boolean; // true表示返回该字段,false表示不返回
  age?: boolean;
  isActive?: boolean;

  profile?: ...;
  posts?: ...;
}
where属性

设置 where 条件。 键值对形式默认为 = , 一个对象中多个属性为 AND ,对象数组为 OR

await repository.find({
  // 相当于 WHERE age = 20 AND isActive = true
  where: { age: 20, isActive: true },
});
await repository.find({
  // 相当于 WHERE username = 'Tom' OR profile.city = 'Shenzhen'
  where: [
    {
      username: "Tom",
    },
    profile: {
      city: 'Shenzhen',
    },
  ],
});
API 参数 对应的SQL
Equal(value) 一个值 =
Not(value) 值 / Operator NOT / !=
MoreThan(value) 一个值 >
MoreThanOrEqual(value) 一个值 >=
LessThan(value) 一个值 <
LessThanOrEqual(value) 一个值 <=
Between(a,b) 起点、终点 BETWEEN
In(array) 数组 IN (...)
Like(pattern) LIKE 字符串 LIKE
ILike(pattern) 大小写不敏感 LIKE ILIKE 等
IsNull() 无 IS NULL
And(...) 多个 Operator AND
Or(...) 多个 Operator OR
Raw(...) SQL 表达式 自定义

示例

const users = await this.userRepository.find({
  where: {
    age: Between(18, 30),

    username: Like("%Tom%"),

    id: In([1, 2, 3, 4, 5]),

    isActive: true,
  },
});

// 对应SQL
// SELECT *
// FROM users

// WHERE age BETWEEN 18 AND 30

// AND username LIKE '%Tom%'

// AND id IN (1, 2, 3, 4, 5)

// AND isActive = true;

普通 where 没法满足复杂条件,可以使用 Raw() 来书写复杂条件, Raw() 是在 find()、findBy() 等方法的 where 查询条件中使用自定义 SQL 表达式。

Raw<T>(
  valueOrSqlGenerator:
    | string
    | ((columnAlias: string) => string),
  sqlGeneratorParameters?: ObjectLiteral,
): FindOperator<any>

valueOrSqlGenerator

要应用到当前字段上的 SQL 表达式。

  • string

直接传入当前字段右侧的原始 SQL 表达式。

where: {
    createdTime: Raw("NOW()"),
  },

// TypeORM 会自动把当前字段和传入的表达式使用 = 连接,不是把 "NOW()" 当成普通字符串,而是把它当作 SQL 函数表达式。相当于SQL
WHERE created_time = NOW()

where: {
    totalAmount: Raw(
      "paid_amount + discount_amount",
    ),
  },
// 相当于SQL
WHERE total_amount = paid_amount + discount_amount
  • (columnAlias: string) => string

如果需要修改运算符或者编写完整条件,例如 >、LIKE、BETWEEN,则需要使用该回调函数。columnAlias 是 TypeORM 传入的当前字段在 SQL 中的列引用。

Raw(
  /**
    * @columnAlias 当前属性对应的数据库列
    * @return string
    */
  (columnAlias: string): string => {
    return "完整的SQL查询条件";
  },
)

  where: {
    amount: Raw(
      (columnAlias) =>
        `${columnAlias} > 100`, // columnAlias就是amount
    ),
  },
  // 相当于SQL
  WHERE amount > 100

Raw(
  (columnAlias) =>
    `${columnAlias} IS NOT NULL`, // 相当于:WHERE 当前字段 IS NOT NULL
)

Raw(
  (columnAlias) =>
    `${columnAlias} LIKE '%餐饮%'`,// 相当于:WHERE 当前字段 LIKE '%餐饮%'
)

sqlGeneratorParameters

SQL 命名参数的值。这是一个可选参数,主要配合 valueOrSqlGenerator 的回调函数形式使用。当 SQL 条件中包含动态值时,通过它给 :参数名 提供实际参数值。

Raw(
  (columnAlias) =>
    `${columnAlias} > :minimumAmount`,
  {
    minimumAmount: 100,
  },
)
// :minimumAmount 就是SQL 命名参数,两者必须一一对应,即:minimumAmount → minimumAmount: 100。所以相当于SQL
WHERE amount > 100

Raw(
  (columnAlias) =>
    `${columnAlias} BETWEEN :start AND :end`,
  {
    start: 100,
    end: 500,
  },
)
// 相当于
WHERE amount BETWEEN 100 AND 500
relations属性

查询关联数据,涉及到多表查询可以使用。

relationLoadStrategy属性

控制 TypeORM 用什么方式加载 relations,取值为 'join'| 'query' 。 join 类似 LEFT JOIN 。

order属性

设置排序。升序: ASC 或 asc 或 1 ,降序: DESC 或 desc 或 -1 。 多字段排序

// 对应:ORDER BY age DESC, id ASC
order: {
  age: 'DESC',
  id: 'ASC',
}
skip属性

表示跳过多少条。该属性只存在于 FindManyOptions 。

await repository.find({
  skip: 20, // 跳过前20条,从21条开始
});
// 对应:OFFSET 20
take属性

最多获取多少条。该属性只存在于 FindManyOptions 。

await repository.find({
  take: 10, // 最多获取十条
});
// 对应:LIMIT 10
withDeleted属性

是否包含软删除数据

建立外键

TypeORM 建立外键的方式有两种

  • 建立实体之间的关联,会自动建立外键
  • 通过 @ForeignKey 装饰器指定字段来建立外键。这种方式只会定义外键不会建立实体关系,通常情况最好建立实体关系,所以使用较少。

建立实体关联

通过以下装饰器建立实体关系,在实体关系建立后会根据配置自动创建外键

关系 外键在哪 Owning Side
ManyToOne Many 一侧 ManyToOne
OneToMany 不保存 FK 反向侧
OneToOne @JoinColumn 一侧 @JoinColumn 一侧
ManyToMany 中间表 @JoinTable 一侧

@ManyToOne/@OneToMany

表示多对一/一对多的情况。在多的一方使用 @ManyToOne ,少的一方使用 @OneToMany ,外键会建立在多的一方

ManyToOne<T>(
  typeFunctionOrTarget:
    | string
    | ((type?: any) => ObjectType<T>),

// 如果是OneToMany,该参数必填,因为 OneToMany 自己不保存外键,它必须知道关联的是哪个字段
  inverseSide?:
    | string
    | ((object: T) => any),

  options?: RelationOptions,
): PropertyDecorator
参数 作用
typeFunctionOrTarget 指定关联的 Entity
inverseSide 指定关联的 Entity 中哪个属性,多的一方可以省略,但是在一的一方该参数必填
options RelationOptions Relation 配置

RelationOptions 参数

interface RelationOptions {
  cascade?:
    | boolean
    | ("insert" | "update" | "remove" | "soft-remove" | "recover")[];

  nullable?: boolean;

  onDelete?: "RESTRICT" | "CASCADE" | "SET NULL" | "DEFAULT" | "NO ACTION";

  onUpdate?: "RESTRICT" | "CASCADE" | "SET NULL" | "DEFAULT" | "NO ACTION";

  deferrable?: "INITIALLY IMMEDIATE" | "INITIALLY DEFERRED";

  createForeignKeyConstraints?: boolean;

  lazy?: boolean;

  eager?: boolean;

  persistence?: boolean;

  orphanedRowAction?: "nullify" | "delete" | "soft-delete" | "disable";
}
参数 类型 作用
cascade boolean | string[] ORM 级联保存、更新、删除等
nullable boolean FK 是否允许 NULL
onDelete OnDeleteType 被引用数据 DELETE 时 FK 行为
onUpdate OnUpdateType 被引用键 UPDATE 时 FK 行为
deferrable DeferrableType 延迟 FK 检查
createForeignKeyConstraints boolean 是否真正创建数据库 FK
lazy boolean 懒加载
eager boolean 自动加载 Relation
persistence boolean 是否通过该 Relation 持久化关系变化
orphanedRowAction union 孤儿关联记录如何处理

@ManyToOne() 允许把 options 直接作为第二个参数(inverseSide省略)

@ManyToOne(() => Category, {
  nullable: false,
})

category表

id name
1 早餐
2 午餐
3 娱乐

transaction表

id amount category_id
1 10 1
2 35 2
3 50 3
4 5 1
import { Entity, PrimaryGeneratedColumn, Column, OneToMany } from "typeorm";

import { Transaction } from "./transaction.entity";

@Entity("categories")
export class Category {
  @PrimaryGeneratedColumn()
  id: number;

  @Column()
  name: string;

  // 建立一对多关系
  @OneToMany(
    // 与Transaction实体建立关系
    () => Transaction,
    // 与Transaction实体的category字段关联
    (transaction) => transaction.category,
    {
      nullable: false, // 不允许外键为空
      onDelete: "RESTRICT", // 子表使用引用数据时不允许父表删除
    },
  )
  transactions: Transaction[];
}
import {
  Entity,
  PrimaryGeneratedColumn,
  Column,
  ManyToOne,
  JoinColumn,
} from "typeorm";

import { Category } from "./category.entity";

@Entity("transaction")
export class Transaction {
  @PrimaryGeneratedColumn()
  id: number;

  @Column("decimal", {
    precision: 10,
    scale: 2,
  })
  amount: number;

  // 建立多对一关系
  @ManyToOne(
    // 与Category实体建立关系。自动与Category实体的主键id关联建立外键,外键为categroyId
    () => Category,
    // 可以写也可以不写
    (category) => category.transactions,
  )
  category: Category;
}

@ManyToOne自动创建的外键字段命名依据:Relation属性名 + 被引用字段名,拼接后使用小驼峰最终得出外键名。比如上方 () => Category,Category实体中的主键是id,自动建立外键categoryId。如果是() => Tag,Tag实体中的主键是tid,那么得到的外键字段是TagTid。但是数据库的字段命名规范是snake_case,所以一般会用@JoinColumn重新显示定义外键名。

虽然数据库中建立了字段categoryId(外键),但是实体中没有,所以通过transaction.categoryId是获取不到的。想要获取分类id只能通过transaction.category.id。

当一张表与多张表存在外键关系,并且该张表又是一的一方,实体要写非常多次的OneToMany。比如与A、B、C表都有关联并且都是作为一的一方,要书写:

  @OneToMany(
    () => A,
    a => a.category,
  )
  as: A[];

  @OneToMany(
    () => B,
    b => b.category,
  )
  bs: B[];

  @OneToMany(
    () =>C,
    c => c.category,
  )
  cs: C[];

确实是都需要书写出来,但是 @OneToMany 的作用是让实体能够反向访问所有引用它的表。比如你要获取 transaction.category ,Category 实体中就必须写 @OneToMany ,如果不需要是可以不写的,而并非像 @ManyToMany 要写出来。TypeORM 的一对多 / 多对一关系,@ManyToOne 是核心、通常必须,@OneToMany 是可选,不是必须。所以上述即使与A、B、C表关联,如果一的一方不需要使用A、B、C表中的数据,实体中可以不写 @OneToMany 。

@JoinColumn

用于自定义外键名。在一对一中必须使用,多对一可以不用,因为多对一会在使用 @ManyToOne 的实体自动创建外键。不过还是推荐使用,显示指定便于维护。

JoinColumn(
  optionsOrOptionsArray?:
    | JoinColumnOptions
    | JoinColumnOptions[],
): PropertyDecorator

JoinColumnOptions 结构

interface JoinColumnOptions {
  name?: string;
  referencedColumnName?: string;
  foreignKeyConstraintName?: string;
}
参数 类型 作用
name string 当前Entity外键字段
referencedColumnName string 对方 Entity 被引用字段
foreignKeyConstraintName string 数据库 FK constraint 名称

自定义外键名

  @ManyToOne(
    () => Category,
  )
  @JoinColumn({
    name:'category_id' // 指定外键名为category_id
  })
  category: Category;

虽然数据库中建立了符合规范的字段 category_id (外键),但是实体中没有,只能通过 transaction.category.id 获取分类id。所以为了方便获取实体中的分类id,通常会使用 @Cloumn 来创建一个,和 @JoinColumn 指向同一个数据库字段,这样数据库也不会创建两个字段。

@Column({
  name: 'category_id',
})
categoryId: number;

@ManyToOne(() => Category)
@JoinColumn({
  name: 'category_id',
})
category: Category;

// 它们指向同一个数据库字段category_id,并不会创建两个字段。这种方式方便了开发中从实体中获取categoryId,所以通常开发推荐这么写。

@OneToOne

一对一,必须在拥有外键的一侧添加 @JoinColumn()来指定外键。

OneToOne<T>(
  typeFunctionOrTarget:
    | string
    | ((type?: any) => ObjectType<T>),

  inverseSide?:
    | string
    | ((object: T) => any),

  options?: RelationOptions,
): PropertyDecorator

user表

id name profile_id
1 李华 1
2 小明 2
3 小红 3

profile表

id address age
1 XX 18
2 XX 28
3 XX 29
@Entity()
export class User {
  @PrimaryGeneratedColumn()
  id: number;

  @OneToOne(() => Profile, (profile) => profile.user)
  // 建立外键
  @JoinColumn({
    name: "profile_id",
  })
  profile: Profile;

  @Column({
    name: "profile_id",
  })
  profileId: number;
}
@Entity()
export class Profile {
  @PrimaryGeneratedColumn()
  id: number;

  @OneToOne(() => User, (user) => user.profile)
  user: User;
}

ManyToMany

多对多,不建议用。多对多更好的做法是建立一张关联表,然后转换成多对一/一对多。

多表联查

createQueryBuilder()

通过 createQueryBuilder 返回 SELECT SQL 构造器 SelectQueryBuilder ,通过构造器里的方法实现多表联查。

createQueryBuilder(
  alias?: string,
  queryRunner?: QueryRunner,
): SelectQueryBuilder<Entity>
alias

当前主表在SQL中的别名。比如 createQueryBuilder('txn'),相当于SQL FROM transaction AS txn 。

SelectQueryBuilder

一个 SELECT SQL 构造器,这个类非常强大,常见的公开方法有:

方法 作用
select() 指定 SELECT 查询哪些字段或表达式
addSelect() 在已有的 select 基础上继续添加查询字段
from() 设置当前的主查询数据源,即主表
leftJoin() 左外连接,但不查询表字段。只包含主表数据
leftJoinAndSelect() 左外连接,但不查询表字段。包含主表和JOIN表的数据
innerJoin() 显示内连接,但不查询表字段。只包含主表数据
innerJoinAndSelect() 显示内连接,但不查询表字段。包含主表和JOIN表的数据
where() 添加SQL的where查询条件
andWhere() 在已有 WHERE 后添加 AND 条件
orWhere() 在已有 WHERE 后添加 OR 条件
groupBy()
having()
orderBy()
skip()
take()
getOne()
subQuery() 创建一个 SQL 子查询构造器 SelectQueryBuilder ,它不同于外层的SQL构造器
getQuery() 将 SelectQueryBuilder 转换为 SQL 字符串
getMany() 执行SQL语句并返回数据库原始结果转换后的实体
getRaw() 执行SQL并返回数据库的原始结果
getRawAndEntities() 执行SQL语句,并且返回数据库原始结果和部分原始结果转换后的实体
setParameter() 设置一个 SQL 动态参数
setParameters() 一次设置多个 SQL 动态参数
getParameters() 获取当前 SelectQueryBuilder的参数对象

leftJoin()

leftJoin(
  entityOrProperty:
    | Function
    | string
    | ((qb: SelectQueryBuilder<any>) => SelectQueryBuilder<any>),
  alias: string,
  condition?: string,
  parameters?: ObjectLiteral,
): this
entityOrProperty

要 JOIN 的目标。比如 leftJoin(category) ,相当于SQL LEFT JOIN category 。

JOIN 的目标可以使关联属性、实体、表名:

  • 关联属性

    如果实体之间已经已经通过 @ManyToOne 或 @OneToMany 关联,推荐传关联的属性,这样TypeORM 会根据关联属性自动建立ON条件

    .leftJoin(
      'transaction.category',
      'ctg',
    )
    TypeORM 会根据:
    @ManyToOne(() => Category)
    category: Category;
    
    自动知道:
    transaction.category_id
            ↓
    category.id
    
    所以会自动加上一下条件,不需要手动写
    ON transaction.category_id = ctg.id
    
    所以上述就相当于
    LEFT JOIN category AS ctg
    ON transaction.category_id = ctg.id
  • 实体

    直接传实体,就需要自己写ON的条件

    .leftJoin(
      Category,
      'ctg',
      'ctg.id = transaction.categoryId',
    )
  • 表名

    不清楚意义,用前两种就行。

alias

JOIN 目标的别名。比如leftJoin('transaction.category','ctg') ,相当于SQL LEFT JOIN category AS ctg 。

condition

JOIN 的 ON 条件。

.leftJoin(
  'transaction.category',
  'category',
  'category.isActive = :isActive',
)
// 生成的SQL
LEFT JOIN category category
    ON category.id = transaction.category_id
    AND category.is_active = ?
parameters

SQL 命名参数的值,用于给条件动态传值。给 condition 中的 :参数名 提供具体的参数值,参数名之间必须一一对应。

.leftJoin(
  'transaction.category',
  'category',
  'category.isActive = :isActive'
  {
    isActive: true,
  },
)
// 这里:isActive必须和isActive对应,等价于category.isActive = true,相当于SQL:
LEFT JOIN category AS category ON category.id = transaction.category_id AND category.is_active = true
返回值

返回值 this ,还是当前的 SelectQueryBuilder<Transaction> 。所以可以进行链式调用:

this.transactionRepository
  .createQueryBuilder('transaction')
  .leftJoin(...)
  .where(...)
  .orderBy(...)
  .getMany(); // 最终通过getMany()执行SQL语句即可查询到数据
示例
const transactions =
  await this.transactionRepository
    .createQueryBuilder('transaction')
    .leftJoin(
      'transaction.category',
      'category',
    )
    .getMany();

// 相当于SQL
SELECT transaction.*
FROM transaction transaction
LEFT JOIN category category
ON category.id = transaction.category_id;

// 可能得到
[
  {
    id: 1,
    amount: 20,
  },
]

leftJoinAndSelect()

方法结构和 leftJoin 一致,区别在于 leftJoinAndSelect() 还会查询 JOIN 目标的数据,即leftJoinAndSelect() ≈ leftJoin() + addSelect()。

const transactions =
  await this.transactionRepository
    .createQueryBuilder('transaction')
    .leftJoinAndSelect(
      'transaction.category',
      'category',
    )
    .getMany();

// 相当于SQL
SELECT
    transaction.*,
    category.*
FROM transaction transaction
LEFT JOIN category category
ON category.id = transaction.category_id;

// 可能得到
[
  {
    id: 1,
    amount: 20,

    category: {
      id: 10,
      name: '早餐',
    },
  },

  {
    id: 2,
    amount: 50,

    category: {
      id: 20,
      name: '娱乐',
    },
  },
]

where()

where(
  where:
    | string
    | ((qb: this) => string)
    | Brackets
    | ObjectLiteral
    | ObjectLiteral[],
  parameters?: ObjectLiteral,
): this
where

WHERE 的查询条件。常见类型:

  • string

    如果需要使用动态传值,跟 leftJoin 的 parameters 一样需要确保名称一一对应。

    const type = 'expense';
    const minAmount = 100;
    const userId = 10;
    
    .where(
      `
        transaction.type = :type
        AND transaction.amount >= :minAmount
        AND transaction.userId = :userId
      `,
      {
        type,
        minAmount,
        userId,
      },
    )
    
    // 相当于SQL
    WHERE
      transaction.type = 'expense'
      AND transaction.amount >= 100
      AND transaction.user_id = 10
  • Brackets

    给一组 WHERE 条件加括号。

    .where(
      new Brackets((qb) => {
        qb
          .where('transaction.amount > :min', {
            min: 100,
          })
          .orWhere('transaction.type = :type', {
            type: 'income',
          });
      }),
    )
    
    // 相当于
    WHERE (
      transaction.amount > 100
      OR transaction.type = 'income'
    )
  • ObjectLiteral

    类似对象形式条件

    {
      id: 1;
    }
    // 相当于where id = 1。还是推荐使用'字段 = :参数',更加直观
parameters

leftJoin 的 parameters 一样

.where(
  'transaction.amount > :amount',
  {
    amount: 100,
  },
)
返回值

返回值 this 也是表示当前 SelectQueryBuilder<Entity> 。

注意
  1. 连续两次调用 where() 后一次的会覆盖前一次的
.where(
  'transaction.amount > :amount',
  { amount: 100 },
)
.where(
  'transaction.type = :type',
  { type: 'expense' },
)

// 会变成
WHERE type = 'expense'
  1. IN 有一个特殊的数组参数写法
const ids = [1, 2, 3];

.where(
  'transaction.id IN (:...ids)',
  {
    ids,
  },
)

// 相当于
WHERE transaction.id IN (1, 2, 3)

andWhere()

方法结构域 where() 一致,区别是它是已有 WHERE 后添加 AND 。

.where(
  'transaction.amount > :amount',
  {
    amount: 100,
  },
)
.andWhere(
  'transaction.type = :type',
  {
    type: 'expense',
  },
)

// 相当于
WHERE transaction.amount > 100
AND transaction.type = 'expense'

orWhere()

方法结构域 where() 一致,区别是它是已有 WHERE 后添加 OR 。

getMany()

执行SQL返回数据

getMany(): Promise<Entity[]>

getRawMany()

也是执行SQL返回数据,与 getMany() 的区别是 getMany() 得到的是完整的 Entity , getRawMany<T>() 可以自定义返回的数据。

getRawMany<T = any>(): Promise<T[]>
interface TransactionRow {
  transactionId: number;
  amount: number;
  categoryName: string | null;
}
const result = await this.transactionRepository
  .createQueryBuilder("transaction")

  .leftJoin("transaction.category", "category")
  .select("transaction.id", "transactionId")
  .addSelect("transaction.amount", "amount")
  .addSelect("category.name", "categoryName")

  .getRawMany<TransactionRow>();

// 可能得到
[
  {
    transactionId: 1,
    amount: 20,
    categoryName: "早餐",
  },
];

select()

select(
  selection?:
    | string
    | string[]
    | (
        (
          qb: SelectQueryBuilder<any>,
        ) => SelectQueryBuilder<any>
      ),
  selectionAliasName?: string,
): this
selection

要查询的字段,如果不写,默认查询所有。常见类型如下:

  • string

    可选择单个字段,也可以选择整个实体别名,如果是选择实体,相当于选择该实体的所有可查询字段

    .select(
      'transaction.id',
    )
    // 相当于
    SELECT transaction.id
    
    .select(
      'transaction', // Transaction实体别名
    )
    // 相当于
    SELECT
      transaction.id,
      transaction.amount,
      transaction.type,
      ...
  • string[]

    .select([
      'transaction.id',
      'transaction.amount',
      'transaction.type',
    ])
    //相当于
    SELECT
      transaction.id,
      transaction.amount,
      transaction.type
selectionAliasName

给 SELECT 出来的字段 / 表达式起一个结果别名。

.select(
   'transaction.id',
   'id',
  'SUM(transaction.amount)',
  'totalAmount',
)
// 相当于
SELECT  transaction.id AS id,SUM(transaction.amount) AS totalAmount
返回值
注意
  1. 后面的 select 会覆盖前面的

    .select(
      'transaction.id',
    )
    .select(
      'transaction.amount',
    )
    // 相当于
    SELECT transaction.amount

addSelect()

方法结构跟 select() 一致。

.select(
  'transaction.id',
)
.addSelect(
  'transaction.amount',
)
.addSelect(
  'transaction.type',
)
// 相当于
SELECT
  transaction.id,
  transaction.amount,
  transaction.type

from()

from<T extends ObjectLiteral>(
  entityTarget:
    | { new (): T }
    | Function
    | EntitySchema<T>
    | string
    | {
        type: T;
        name: string;
      }
    | (
        (
          qb: SelectQueryBuilder<any>,
        ) => SelectQueryBuilder<any>
      ),
  aliasName: string,
): SelectQueryBuilder<T>
entityTarget

指定当前查询从哪个实体、数据表或者子查询中获取数据,相当于 SQL 的 FROM 查询目标。

  • 传实体

    .from(
      TransactionTagEntity,
      'filterTag',
    )
    // 相当于SQL
    FROM transaction_tags AS filterTag
  • EntitySchema

    const TransactionTagSchema =
      new EntitySchema<TransactionTag>({
        name: 'TransactionTag',
        tableName: 'transaction_tags',
        columns: {
          transactionId: {
            type: Number,
            name: 'transaction_id',
            primary: true,
          },
          tagId: {
            type: Number,
            name: 'tag_id',
            primary: true,
          },
        },
      });
    
    .from(
      TransactionTagSchema,
      'filterTag',
    )
    
    // 相当于
    FROM transaction_tags AS filterTag
  • string

    可传入表名,子查询SQL

    .from(
      'transaction_tags',
      'filterTag',
    )
    // 相当于SQL
    FROM transaction_tags AS filterTag
    
    // 也可以是一个带括号的子查询 SQL
    .from(
      `(${subQuery.getQuery()})`,
      'filteredTag',
    )
    // 相当于
    FROM (
      SELECT ...
    ) AS filteredTag
  • 子查询回调函数

    .from(
      (subQuery) => {
        return subQuery
          .select(
            'transactionTag.transactionId',
            'transactionId',
          )
          .from(
            TransactionTagEntity,
            'transactionTag',
          )
          .where(
            'transactionTag.tagId IN (:...tagIds)',
            {
              tagIds,
            },
          );
      },
      'filteredTag',
    )
    // 相当于SQL
    FROM (
      SELECT
        transactionTag.transaction_id AS transactionId
      FROM transaction_tags AS transactionTag
      WHERE transactionTag.tag_id IN (?, ?)
    ) AS filteredTag
aliasName

设置 entityTarget 在当前 SQL 中的别名

返回值

返回值为 SelectQueryBuilder ,因此可以继续链式调用

from() 设置的是当前查询的主数据源。如果重复调用 from(),后面的主数据源会覆盖前面的主数据源。需要增加额外的 FROM 数据源时,应使用: addFrom()

subQuery()

subQuery(): SelectQueryBuilder<any>

创建一个用于构建子查询的 SelectQueryBuilder ,不是原来的外层查询构造器。 所以 subQuery() 可以用于子查询,不过它不会执行SQL,所以需要链式调用 getQuery() 转为SQL字符串。

const queryBuilder =
  this.transactionEntity.createQueryBuilder('transaction');

const subQueryBuilder = queryBuilder.subQuery();

queryBuilder
└─ 外层查询构造器,查询 transactions

subQueryBuilder
└─ 子查询构造器,此时还没有指定查询的数据表

innerJoin()

方法结构跟 leftJoin() 一致。区别在于 innerJoin() 是内连接,查两表的交集数据。

innerJoinAndSelect()

作用跟 innerJoin() 一致,区别在于 innerJoin() 还会查询 JOIN 目标的数据,即innerJoinAndSelect() ≈ innerJoin() + addSelect()。

getRawAndEntities()

可以获取 TypeORM 把数据库原始 SELECT 结果转换后的实体对象和数据库原始 SELECT 结果

getRawAndEntities<T = any>(): Promise<{
  entities: Entity[];
  raw: T[];
}>
entities

TypeORM 转换后的实体对象

raw

数据库原始 SELECT 结果

setParameters()

setParameters(
  parameters: ObjectLiteral
): this
parameters

key-value形式的SQL参数

interface ObjectLiteral {
  [key: string]: any;
}
属性 类型 说明
key string SQL 中的命名参数名称,不包含 :
value any 对应参数的实际值,例如字符串、数字、布尔值、数组等
const result = await this.transactionRepository
  .createQueryBuilder("transaction")
  .where(
    "transaction.amount >= :minAmount AND transaction.amount <= :maxAmount",
  )
  .setParameters({
    minAmount: 100,
    maxAmount: 1000,
  })
  .getMany();
返回值

当前的SelectQueryBuilder<Entity>,因此支持链式调用

setParameter()

和 setParameters() 作用一样,只不过 setParameter() 只能设置一个参数。如:where('amount >= :minAmount').setParameter('minAmount', 100)

setParameter(
  key: string,
  value: any
): this

注意,使用 setParameter() 设置同名参数时,后面的会覆盖掉前面的

.setParameter('amount', 100)
.setParameter('amount', 200)
// 最终amount = 200

事务

TypeORM 最常见的事务管理方式有两种:自动管理事务 、手动管理事务。自动管理事务,TypeORM 会负责开启、提交和异常回滚事务,绝大多数情况都是使用自动管理事务。

对比 自动管理事务 手动管理事务
核心 API transaction() QueryRunner
开启事务 TypeORM 自动处理 调用 startTransaction()
提交事务 回调成功后自动提交 调用 commitTransaction()
回滚事务 回调抛出异常时自动回滚 调用 rollbackTransaction()
数据库连接 TypeORM 管理 开发者管理
释放资源 TypeORM 自动处理 调用 release()
适合场景 绝大多数普通业务 需要精细控制事务生命周期的业务

自动管理事务

通过 DataSource / EntityManager 下的 transaction() 方法来实现自动管理事务。 transaction() 用于将多个数据库操作放入同一个事务中执行,由 TypeORM 自动完成以下工作:

  1. 获取数据库连接。
  2. 开启事务。
  3. 执行回调函数中的数据库操作。
  4. 回调正常完成时提交事务。
  5. 回调抛出异常时回滚事务。
  6. 最后释放事务使用的连接资源。

transaction()

DataSource 和 EntityManager 的 transaction() 方法结构完全一致

transaction<T>(
  isolationLevel?: IsolationLevel,
  runInTransaction: (
    entityManager: EntityManager
  ) => Promise<T>
): Promise<T>;
参数
  • isolationLevel

    用于设置当前事务的隔离级别,类型有:

    type IsolationLevel =
      | "READ UNCOMMITTED"
      | "READ COMMITTED"
      | "REPEATABLE READ"
      | "SERIALIZABLE"
      | "SNAPSHOT";
    
    // 这是 TypeORM 的通用类型,不代表每种数据库都支持全部选项。
    // 比如 MySQL 支持前四种,不支持 SNAPSHOT 这个选项
  • runInTransaction

    定义事务中需要执行的操作。这是个回调函数,TypeORM 会主动调用它,并向它传入一个专属于当前事务的 EntityManager。示例:

    user 用户表:

    id name
    1 张三

    user_profile 用户资料表:

    id user_id nickname
    1 1 小张
    // 注入DataSource
    constructor(
      @InjectDataSource()
      private readonly dataSource: DataSource
    ){}
    
    // 现在需要修改用户姓名和昵称,并要求两个更新必须同时成功
    async updateUser() {
      return this.dataSource.transaction(
        // 只要事务回调抛出异常,TypeORM 就会执行回滚
        async (manager) => {
          // 1. 修改用户姓名
          await manager.update(
            User,
            { id: 1 },
            { name: '张三丰' },
          );
    
          // 2. 修改用户昵称
          await manager.update(
            UserProfile,
            { userId: 1 },
            { nickname: '张真人' },
          );
    
          return {
            message: '修改成功',
          };
        },
      );
    }

    相当于 SQL 如下,如果执行过程中出现异常,则执行 ROLLBACK 。

    START TRANSACTION;
    
    UPDATE user
    SET name = '张三丰'
    WHERE id = 1;
    
    UPDATE user_profile
    SET nickname = '张真人'
    WHERE user_id = 1;
    
    COMMIT;

注意

  1. SQL 执行成功,不一定代表业务成功。比如 await manager.update( User, { id: 99999 }, { name: '张三丰' },); 假设不存在 id = 99999 的用户,这条 SQL 可能正常执行完毕,只是影响行数为 0,并不会自动抛出异常。如果业务要求用户必须存在,就应该检查 UpdateResult.affect 来判断是否抛出异常,这样才能触发事务回滚。
  2. 如果使用使用了 try...catch ,但是 catch 中没有抛出异常,会存在事务无法回滚的风险。因为 catch 把异常吞掉了,回调最终正常结束,TypeORM 就可能提交之前成功的数据库操作。解决方法是 catch 中明确抛出异常,或者事务中不写 try...catch ,让异常自然向外传播。
    await this.dataSource.transaction(async (manager) => {
      try {
        await manager.save(User, user);
        await manager.save(UserProfile, profile);
      } catch (error) {
        console.error(error);
        // 错误被捕获,但没有重新抛出,会导致事务无法回滚
      }
    });
两种方式开启事务的区别

DataSource.transaction() 和 EntityManager.transaction() 的事务管理能力基本相同,真正的区别在于:它们从哪个 EntityManager 开始创建事务,以及这个 Manager 是否已经绑定了一个事务连接。

// 1 DataSource 开启事务
this.dataSource.transaction(...);

// 2 全局 EntityManager 开启事务
this.dataSource.manager.transaction(...);

// 3 已经处于事务中的 EntityManager 再开启事务
manager.transaction(...);

// `DataSource.transaction()` 本质上也是委托给其 `EntityManager` 执行事务,
// 所以前两种方法可以看做是等价的
类型 从哪里获得 是否绑定特定事务连接
全局EntityManager dataSource.manager 否
事务EntityManager transaction() 回调参数 manager 是

场景一:通过事务 Manager 开启内层事务

await this.dataSource.transaction(async (manager) => {
  // ① 外层事务:新增张三
  await manager.save(User, {
    name: "张三",
  });

  // ② 通过当前事务 Manager 开启内层事务。这种就是事务EntityManager
  await manager.transaction(async (innerManager) => {
    await innerManager.save(User, {
      name: "李四",
    });
  });

  // ③ 模拟外层业务失败
  throw new Error("外层事务执行失败");
});

执行过程

‘图片’

相当于SQL:

START TRANSACTION;

-- 外层新增张三
INSERT INTO user (name) VALUES ('张三');

-- 内层创建保存点
SAVEPOINT typeorm_1;

-- 内层新增李四
INSERT INTO user (name) VALUES ('李四');

-- 内层成功,释放保存点
RELEASE SAVEPOINT typeorm_1;

-- 外层发生异常
ROLLBACK;

最终结果:张三和李四都没有保存成功。因为内层事务并没有独立提交,它仍然属于外层事务的一部分。

场景二:在外层事务中调用 DataSource.transaction()

await this.dataSource.transaction(async (manager) => {
  // ① 外层事务:新增张三
  await manager.save(User, {
    name: "张三",
  });

  // ② 使用 DataSource 开启另一个事务
  await this.dataSource.transaction(async (innerManager) => {
    await innerManager.save(User, {
      name: "李四",
    });
  });

  // ③ 模拟外层事务失败
  throw new Error("外层事务执行失败");
});

第二种方式从全局 DataSource 开启一个新事务,并不会自动复用外层事务 Manager 的连接,所以两个事务是独立的 ‘图片’ 相当于SQL

-- 连接 A
START TRANSACTION;
INSERT INTO user (name) VALUES ('张三');

-- 连接 B
START TRANSACTION;
INSERT INTO user (name) VALUES ('李四');
COMMIT;

-- 连接 A
ROLLBACK;

在没有额外约束冲突和锁等待的情况下,最终结果:

用户 是否保存成功 原因
张三 否 外层事务回滚
李四 是 内层独立事务已经提交

所以常规业务中,创建业务事务并进入事务回调后,所有相关数据库操作都使用传入的 manager,这样可以保证都属于同一个事务,一个异常可以全部回滚,避免部分提交部分回滚的问题。

从仓库对象中获取实体管理器

在 TypeORM 中,每个 Repository(仓库对象)都有一个 manager 属性,它可以获取当前 Repository 所关联的 EntityManager,它返回 EntityManager 对象。也就是说,也可以从仓库对象中获取实体管理器 EntityManager ,通过这种方式开启事务属于 EntityManager.transaction() 。

constructor(
  @InjectRepository(TransactionEntity)
  private readonly transactionRepo: Repository<TransactionEntity>,
) {}

const manager = this.transactionRepo.manager;
// 开启事务
manager.transaction(...);

// 查询用户
manager.find(UserEntity);

// 保存账单
manager.save(TransactionEntity, data);

// 获取其他表的 Repository
manager.getRepository(TagEntity);

// 虽然这个 Manager 来自transaction的仓库实体,但它并不是只能操作transactionEntity。
// EntityManager 可以管理同一个 DataSource 下的多个实体
this.transactionRepo.manager.transaction(
  async (manager) => {
    // 操作账单表
    await manager.find(TransactionEntity);

    // 操作分类表
    await manager.find(UserCategoryEntity);

    // 操作标签表
    await manager.find(TagEntity);
  },
);
  • 这种写法与DataSource.transaction() 有什么区别? 如果 Repository 和 DataSource 对应的是同一个数据库连接配置(同一个 DataSource),并且Repository 并不是额外创建的事务绑定 Repository。那么两者写法没区别,所以下面几种写法没有区别:
@InjectRepository(TransactionEntity)
private readonly transactionEntity: Repository<TransactionEntity>

// 方式一:通过 Repository 的 Manager
await this.transactionEntity.manager.transaction(
  async (manager) => {
    await manager.save(TransactionEntity, data);
  },
);

// 方式二:直接使用 DataSource
await this.transactionEntity.manager.transaction(
  async (manager) => {
    await manager.save(TransactionEntity, data);
  },
);

// 方式三:使用 DataSource 的 Manager
await this.dataSource.manager.transaction(
  async (manager) => {
    await manager.save(TransactionEntity, data);
  },
);

所以这种情况下,更推荐使用从 Repository 的 Manager 开启事务,不用额外引入 DateSource

constructor(
  // TransactionEntity会在多处使用所以一定会引入,
  // 那么直接从transactionRepo开启事务就不用引入DataSource了
  @InjectRepository(TransactionEntity)
  private readonly transactionRepo: Repository<TransactionEntity>,

  // 不需要
  // @InjectDataSource()
  // private readonly dataSource: DataSource,
) {}
不同Repository获取EntityManager

引入仓库实体后,常见的可以直接通过 transactionRepo 操作数据库,也可以通过 manager.getRepository(TransactionEntity) 获取仓库对象操作数据库。前者不属于事务,所以如果开启了事务,一定要使用 manager 获取的仓库对象来操作数据库,不然起不到事务效果。即:不需要使用事务,直接通过仓库实体操作数据库,需要使用事务时,通过 manager 获取仓库实体后操作数据库。

对象 使用的 Manager 是否属于当前事务
this.transactionEntity 全局 EntityManager 默认不属于
manager.getRepository(TransactionEntity) 事务 EntityManager 属于
constructor(
  @InjectRepository(TransactionEntity)
  private readonly transactionRepo: Repository<TransactionEntity>,

) {}

// 事务外的 Repository
await this.transactionRepo.save(data)

// 事务内的 Repository
const repo = manager.getRepository(TransactionEntity)
await repo.save(data)
示例

示例中可以看到:

  1. 使用仓库实体transactionRepo中开启事务,没有用Datasource
  2. 事务中使用getRepository重新获取实体操作数据库,而不是直接使用this.transactionRepo
  3. 进入事务回调后,所有相关数据库操作都使用传入的 manager ,保证都处于同一事务
import { EntityManager, Repository } from "typeorm";
interface CreateTransactionData {...}

@Injectable()
export class TransactionsService {
  constructor(
    @InjectRepository(TransactionEntity)
    private readonly transactionRepo: Repository<TransactionEntity>,
    @InjectRepository(UserCategoryEntity)
    private readonly userCategoryRepo: Repository<UserCategoryEntity>,
  ) {}

  async createTransaction(data): Promise<void> {
    try {
      // 关联方法和全部写入共用事务 manager,保证锁与事务边界一致。
      await this.transactionRepo.manager.transaction(async (manager) => {
        await this.aFn(manager, data);

        // 创建实体
        const transactionRepo = manager.getRepository(TransactionEntity);
        const transaction = this.bFn(transactionRepo, data);

        // 保存
        const savedTransaction = await transactionRepo.save(transaction);
      });
    } catch (error) {
      throw new InternalServerErrorException("创建流水失败,请重新尝试", {
        cause: error,
      });
    }
  }

  private async aFn(
    manager: EntityManager,
    data: CreateTransactionData,
  ): Promise<void> {
    const categoryRepo = manager.getRepository(UserCategoryEntity);

    const category = await categoryRepo.findOne(...);
  }

    private bFn(
    transactionRepo: Repository<TransactionEntity>,
    data: CreateTransactionData,
  ): TransactionEntity {
    return transactionRepo.create({...});
  }
}