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> 。
注意
- 连续两次调用
where()后一次的会覆盖前一次的
.where(
'transaction.amount > :amount',
{ amount: 100 },
)
.where(
'transaction.type = :type',
{ type: 'expense' },
)
// 会变成
WHERE type = 'expense'
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
返回值
注意
-
后面的
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 自动完成以下工作:
- 获取数据库连接。
- 开启事务。
- 执行回调函数中的数据库操作。
- 回调正常完成时提交事务。
- 回调抛出异常时回滚事务。
- 最后释放事务使用的连接资源。
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;
注意
- SQL 执行成功,不一定代表业务成功。比如
await manager.update( User, { id: 99999 }, { name: '张三丰' },);假设不存在 id = 99999 的用户,这条 SQL 可能正常执行完毕,只是影响行数为 0,并不会自动抛出异常。如果业务要求用户必须存在,就应该检查UpdateResult.affect来判断是否抛出异常,这样才能触发事务回滚。 - 如果使用使用了
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)
示例
示例中可以看到:
- 使用仓库实体transactionRepo中开启事务,没有用Datasource
- 事务中使用getRepository重新获取实体操作数据库,而不是直接使用this.transactionRepo
- 进入事务回调后,所有相关数据库操作都使用传入的 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({...});
}
}