prisma-nestjs-patterns

Prisma ORM + NestJS — 生产模式

遵循 Clean Architecture 的 Prisma 与 NestJS 完整集成指南。涵盖从基础配置到关键原子事务、仓库、查询优化和测试的内容。

可用参考资料

需要深入了解特定领域时，请阅读相应文件：

• references/setup-and-service.md — 安装、PrismaService、全局模块、健康检查
• references/schema-and-migrations.md — Schema 设计、类型、关系、索引、迁移
• references/repository-pattern.md — 将仓库作为基础设施适配器（Clean Architecture）
• references/transactions.md — 原子事务、SELECT FOR UPDATE、并发处理
• references/query-patterns.md — 防止 N+1、include/select、分页、复杂查询
• references/testing.md — 使用 jest-mock-extended、prisma-mock 进行测试，以及与 testcontainers 集成

---

各参考资料的适用场景

任务	参考资料
首次在 NestJS 中配置 Prisma	setup-and-service.md
设计或修改 schema，创建迁移	schema-and-migrations.md
为领域模块创建仓库	repository-pattern.md
预订、锁、并发操作	transactions.md
优化慢查询、消除 N+1	query-patterns.md
在单元测试/集成测试中模拟 Prisma	testing.md

---

关键规则（始终牢记）

1. PrismaService 是全局的，绝不要直接实例化 PrismaClient

// ❌ Nunca
const prisma = new PrismaClient();

// ✅ Siempre via inyección de dependencias
constructor(private readonly prisma: PrismaService) {}

2. 复合写入操作必须使用原子事务

// ✅ Patrón correcto para cualquier operación que modifique >1 tabla
await this.prisma.$transaction(async (tx) => {
  const gift = await tx.gift.findUnique({ where: { id: giftId } });
  if (gift.status !== 'AVAILABLE') throw new ConflictException();
  await tx.gift.update({ where: { id: giftId }, data: { status: 'RESERVED' } });
  await tx.reservation.create({ data: { giftId, reservedById: userId } });
});

3. 仓库位于基础设施层，绝不要放在控制器或领域服务中

// La interfaz vive en el dominio
export interface ReservationRepository {
  findActiveByGiftId(giftId: string): Promise<Reservation | null>;
  create(data: CreateReservationData): Promise<Reservation>;
}

// La implementación Prisma vive en infraestructura
@Injectable()
export class PrismaReservationRepository implements ReservationRepository { ... }

4. 绝不要在基础设施模块之外暴露 PrismaClient

领域模块和应用模块应基于接口工作，而不是直接使用 Prisma。

5. 始终显式使用 select 或 include，绝不要返回完整模型

// ❌ Retorna passwordHash, campos internos
return this.prisma.user.findUnique({ where: { id } });

// ✅ Solo los campos necesarios
return this.prisma.user.findUnique({
  where: { id },
  select: { id: true, nombre: true, email: true, createdAt: true }
});

---

来源和官方文档

• Prisma Docs — NestJS Integration：https://www.prisma.io/docs/guides/other/nestjs
• Prisma Docs — Transactions：https://www.prisma.io/docs/orm/prisma-client/queries/transactions
• Prisma Docs — Interactive Transactions：https://www.prisma.io/docs/orm/prisma-client/queries/transactions#interactive-transactions
• Prisma Docs — Select/Include：https://www.prisma.io/docs/orm/prisma-client/queries/select-fields
• Prisma Docs — Relation Queries：https://www.prisma.io/docs/orm/prisma-client/queries/relation-queries
• Prisma Docs — Migrations：https://www.prisma.io/docs/orm/prisma-migrate
• NestJS Docs — Database：https://docs.nestjs.com/techniques/database
• Prisma Blog — NestJS Best Practices：https://www.prisma.io/blog/nestjs-prisma-rest-api-7D056s1BmOL0
• jest-mock-extended：https://github.com/marchaos/jest-mock-extended