「一起学后端」Nest.js + MySQL 查询方法教学文档

Nest.js + MySQL 查询方法教学文档

1. 基础 CRUD 操作

1.1 创建记录

// 创建一个用户对象（此时还未保存到数据库）
const user = this.userRepository.create({
  name: 'John',
  age: 25, 
});

// 将创建的对象保存到数据库
await this.userRepository.save(user);

// 批量创建示例
const users = this.userRepository.create([
  { name: 'Alice', age: 30 },
  { name: 'Bob', age: 28 },
]);
await this.userRepository.save(users);

1.2 查询记录

// 查询所有用户
const allUsers = await this.userRepository.find();

// 条件查询：年龄大于20的用户，带分页（第1页，每页10条）
const filteredUsers = await this.userRepository.find({
  where: { age: MoreThan(20) }, // MoreThan 是 TypeORM 的比较操作符
  skip: 0,  // 跳过0条 = 第一页
  take: 10, // 取10条
});

// 查询单个用户（根据ID）
const user = await this.userRepository.findOneBy({ id: 1 });

// 查询并按创建时间倒序排列
const sortedUsers = await this.userRepository.find({
  order: { createdAt: 'DESC' } // DESC 降序，ASC 升序
});

1.3 更新记录

// 直接更新（适合简单操作）
await this.userRepository.update(
  { id: 1 },  // 更新条件（找到id=1的用户）
  { age: 26 } // 更新内容
);

// 先查询后更新（推荐：可以处理复杂业务逻辑）
const user = await this.userRepository.findOneBy({ id: 1 });
user.age = 26; // 修改属性
await this.userRepository.save(user); // 保存修改

1.4 删除记录

// 物理删除（直接从数据库删除）
await this.userRepository.delete({ id: 1 });

// 软删除（需要实体类添加 @DeleteDateColumn）
await this.userRepository.softDelete({ id: 1 });
// 软删除后，数据不会被真正删除，而是标记删除时间

2. 复杂查询

2.1 分页与排序

// 分页查询用户列表（带总数统计）
const [users, total] = await this.userRepository.findAndCount({
  where: { isActive: true }, // 查询条件：仅活跃用户
  skip: (page - 1) * limit,  // 跳过前 N 条（计算页码偏移量）
  take: limit,               // 每页数量
  order: { createdAt: 'DESC' }, // 按创建时间倒序排列
});

// 返回结果示例：
// {
//   data: users,  // 当前页数据
//   total: 100,   // 总数据量
//   page: 2,      // 当前页码
//   totalPages: 10 // 总页数
// }

2.2 关联查询（JOIN）

// 方式1：自动关联查询（需在实体类中预先定义关联关系）
const orders = await this.orderRepository.find({
  relations: ['user'], // 加载关联的 user 数据
});

// 方式2：使用 QueryBuilder 手动关联（更灵活）
const orders = await this.orderRepository
  .createQueryBuilder('order')          // 主表别名
  .leftJoinAndSelect('order.user', 'user') // 关联 user 表，别名为 user
  .where('user.age > :age', { age: 18 })   // 条件：用户年龄大于18岁
  .getMany();                          // 获取最终结果

2.3 聚合查询

// 计算用户平均年龄
const result = await this.userRepository
  .createQueryBuilder('user')        // 使用别名 'user' 代表用户表
  .select('AVG(user.age)', 'avgAge') // 计算年龄平均值，结果命名为 avgAge
  .getRawOne();                      // 获取原始数据（不经过实体转换）

console.log(result.avgAge); // 直接通过别名访问结果


// 统计活跃用户数量
const activeUserCount = await this.userRepository.count({ 
  where: { isActive: true } 
});

2.4 子查询

// 步骤1：构建子查询（获取年龄大于20的用户ID）
const subQuery = this.userRepository
  .createQueryBuilder('user')
  .select('user.id')
  .where('user.age > :age', { age: 20 });

// 步骤2：在主查询中使用子查询
const users = await this.userRepository
  .createQueryBuilder('user')
  .where(`user.id IN (${subQuery.getQuery()})`) // 嵌入子查询
  .setParameters(subQuery.getParameters())     // 传递子查询参数（防SQL注入）
  .getMany();

3. 高级操作

3.1 事务处理

想象你要完成以下操作：

1. 从A账户扣除100元
2. 向B账户增加100元

如果步骤1成功但步骤2失败，A账户的钱会凭空消失！事务的作用就是确保这两个步骤绑定成一个原子操作：要么全部成功，要么全部回滚（撤销所有操作）。

当需要同时执行多个数据库操作，并确保它们全部成功或全部失败时（比如转账操作），使用事务。

// 使用 DataSource 对象管理事务
await this.dataSource.transaction(async (transactionManager) => {
  // 在事务中创建用户
  const user = transactionManager.create(User, { name: 'Alice' });
  await transactionManager.save(user);

  // 在事务中更新用户关联的 profile
  await transactionManager.update(
    Profile, 
    { userId: user.id }, 
    { status: 'active' }
  );
});
// 如果过程中任何一步出错，所有操作自动回滚

3.2 TypeORM 中实现事务的两种方式

方式1：transaction 方法（推荐）
直接使用 TypeORM 的 transaction API，自动管理事务的生命周期。

import { DataSource } from 'typeorm';

// 在 Service 类中注入 DataSource
constructor(private dataSource: DataSource) {}

// 示例：转账事务
async transferMoney(fromUserId: number, toUserId: number, amount: number) {
  await this.dataSource.transaction(async (transactionManager) => {
    // 注意：事务内的所有操作必须使用 transactionManager，而不是普通 repository
    
    // 1. 扣款
    await transactionManager.decrement(
      User, 
      { id: fromUserId }, 
      'balance', 
      amount
    );

    // 2. 收款
    await transactionManager.increment(
      User, 
      { id: toUserId }, 
      'balance', 
      amount
    );

    // 3. 记录交易日志（事务内操作）
    await transactionManager.insert(TransactionLog, {
      fromUser: fromUserId,
      toUser: toUserId,
      amount,
    });
  });

  // 如果以上任何一步出错，所有操作自动回滚
}

关键点解释：

方式2：QueryRunner 手动控制（更灵活）
适合需要精细控制事务（如中途提交或回滚）的场景。

async manualTransactionDemo() {
  // 1. 创建 QueryRunner
  const queryRunner = this.dataSource.createQueryRunner();
  
  try {
    // 2. 建立数据库连接并启动事务
    await queryRunner.connect();
    await queryRunner.startTransaction();

    // 3. 执行事务操作（通过 queryRunner.manager）
    await queryRunner.manager.update(User, { id: 1 }, { balance: 100 });
    await queryRunner.manager.delete(Order, { userId: 1 });

    // 4. 手动提交事务（只有提交后操作才生效）
    await queryRunner.commitTransaction();
  } catch (error) {
    // 5. 出错时回滚
    await queryRunner.rollbackTransaction();
    throw new Error('事务执行失败');
  } finally {
    // 6. 释放连接（重要！）
    await queryRunner.release();
  }
}

两种方式对比：

3.3 事务中的错误处理

确保回滚的两种方法

1. 自动回滚：事务内任何未捕获的异常（如数据库错误、手动 throw）都会触发回滚。
2. 手动回滚：在 catch 块中调用 rollbackTransaction()（仅限 QueryRunner 方式）。

// 示例：在事务中检查业务条件
await this.dataSource.transaction(async (manager) => {
  const user = await manager.findOneBy(User, { id: 1 });
  
  // 业务逻辑错误也触发回滚
  if (user.balance < 100) {
    throw new Error('余额不足'); // 抛出错误 → 自动回滚
  }

  // ...其他操作
});

实际应用场景

1. 金融交易：转账、支付、退款
2. 订单系统：创建订单 → 扣减库存 → 生成物流单
3. 用户注册：创建用户 → 初始化配置 → 发送欢迎消息（注意：外部API调用需额外处理）

注意事项

1. 避免长事务：事务执行时间过长会导致数据库锁表，影响性能。
2. 事务嵌套：TypeORM 支持嵌套事务，但不同数据库行为可能不同（需谨慎使用）。
3. 隔离级别：默认使用数据库的隔离级别，可通过 SET TRANSACTION ISOLATION LEVEL 调整。

3.4 原生 SQL 查询

当 TypeORM 的 API 无法满足复杂查询需求时，可以直接写 SQL。

// 执行原生 SQL 查询（参数化查询防止 SQL 注入）
const rawData = await this.userRepository.query(
  'SELECT * FROM users WHERE age > ? AND is_active = ?', 
  [18, true] // 参数按 ? 顺序传递
);

// 示例结果：返回原始数据库结果（字段名与数据库一致）
// [ { id: 1, name: 'John', age: 25, is_active: 1 }, ... ]

3.5 软删除与恢复

软删除不会真正删除数据，而是通过标记时间字段实现“伪删除”。

步骤 1：在实体类中添加 @DeleteDateColumn

import { DeleteDateColumn } from 'typeorm';

@Entity()
export class User {
  // ...其他字段

  @DeleteDateColumn({ name: 'deleted_at' }) // 字段名可自定义
  deletedAt: Date; // 当调用 softDelete 时，此字段会自动记录删除时间
}

步骤 2：操作示例

// 软删除用户（id=1）
await this.userRepository.softDelete({ id: 1 });

// 恢复被软删除的用户
await this.userRepository.restore({ id: 1 });

// 查询时默认排除已软删除的数据
const activeUsers = await this.userRepository.find();

// 查询包含已删除的数据
const allData = await this.userRepository.find({ 
  withDeleted: true, // 显式包含已删除数据
});

4. 装饰器（@）使用大全

以下整理 Nest.js 项目中常见的装饰器用法，涵盖 TypeORM 实体定义 和 DTO 验证 两大场景：

4.1 TypeORM 实体装饰器

用于定义数据库表结构的装饰器，需在实体类（Entity Class）中使用。

4.2 DTO 验证装饰器

用于请求参数验证（搭配 class-validator），需在 DTO 类中使用。

4.3 装饰器组合用法

// 示例：用户注册 DTO
export class CreateUserDto {
  @IsString()
  @Length(3, 20)
  name: string;

  @IsEmail()
  email: string;

  @IsInt()
  @Min(18)
  age: number;

  @IsOptional()
  @IsString()
  address?: string;
}

5. 实用技巧

5.1 错误处理增强

在全局过滤器（Global Filter）中统一处理数据库错误：

// 示例：捕获 TypeORM 错误并返回友好提示
@Catch(QueryFailedError)
export class DatabaseExceptionFilter implements ExceptionFilter {
  catch(exception: QueryFailedError, host: ArgumentsHost) {
    const response = host.switchToHttp().getResponse();
    
    // 处理重复键错误（如唯一约束冲突）
    if (exception.driverError?.code === 'ER_DUP_ENTRY') {
      response.status(400).json({ message: '数据已存在' });
    } else {
      response.status(500).json({ message: '数据库操作失败' });
    }
  }
}

5.2 索引优化实战

合理使用索引可显著提升查询性能：

// 在用户实体中为常用查询字段添加索引
@Entity()
@Index(['email'], { unique: true }) // 唯一索引
@Index(['age', 'createdAt'])       // 复合索引
export class User {
  // ...
}

5.3 索引的作用

索引相当于数据库的“目录”，能快速定位数据，核心作用：

• 加速查询：特别是 WHERE、JOIN、ORDER BY 等操作
• 保证唯一性：唯一索引防止重复数据（如用户名、手机号）
• 减少全表扫描：避免逐行查找，降低数据库负载

5.4 索引的代价

• 占用存储空间：索引需要额外的磁盘空间
• 影响写入速度：每次增删改操作需同步更新索引
• 维护成本：不合理的索引会拖慢性能

5.5 何时创建索引？

5.6 TypeORM 中创建索引

单字段索引
直接在实体类字段上使用 @Index：

@Entity()
export class User {
  @Column()
  @Index() // 为 email 字段创建普通索引
  email: string;

  @Column()
  @Index({ unique: true }) // 创建唯一索引
  username: string;
}

复合索引
为多个字段联合创建索引（注意字段顺序）：

@Entity()
@Index(['lastName', 'firstName']) // 联合索引：lastName + firstName
export class User {
  @Column()
  firstName: string;

  @Column()
  lastName: string;
}

5.7 索引命名与高级配置

@Index('IDX_USER_AGE', ['age'], { unique: false, where: 'age > 18' })
@Entity()
export class User {
  @Column()
  age: number;
}

6. 完整项目结构

src/
├── modules/
│   └── user/
│       ├── dto/
│       │   ├── create-user.dto.ts      # 创建用户DTO（带验证装饰器）
│       │   └── update-user.dto.ts
│       ├── entities/
│       │   └── user.entity.ts          # 用户实体（TypeORM装饰器）
│       ├── user.controller.ts          # API路由（@Get、@Post等）
│       └── user.service.ts             # 业务逻辑（包含所有查询方法）
├── common/
│   ├── filters/                        # 全局异常过滤器
│   └── decorators/                     # 自定义装饰器
└── app.module.ts                       # 主模块（数据库配置、模块注册）

7. 完整示例代码

实体类示例

// user.entity.ts
import { Entity, Column, PrimaryGeneratedColumn, Index } from 'typeorm';

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

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

  @Column()
  name: string;

  @Column()
  age: number;

  @CreateDateColumn()
  createdAt: Date;
}

服务类示例

// user.service.ts
@Injectable()
export class UserService {
  constructor(
    @InjectRepository(User)
    private userRepository: Repository<User>,
  ) {}

  // 查询用户列表（分页）
  async getUsers(page: number, limit: number) {
    const [data, total] = await this.userRepository.findAndCount({
      skip: (page - 1) * limit,
      take: limit,
    });
    return { data, total, page, totalPages: Math.ceil(total / limit) };
  }
}

总结

通过 TypeORM 和 Nest.js 的结合，可以高效实现：

• 安全的数据操作（事务、软删除）
• 清晰的代码结构（实体、DTO、服务分层）
• 强大的参数验证（装饰器组合）

建议在实际开发中：

1. 优先使用 TypeORM 的高级查询方法（如 QueryBuilder）
2. 始终验证用户输入（DTO + 装饰器）
3. 合理使用索引优化查询性能