prisma_orm

用途

该技能面向使用 Prisma ORM 的开发者，提供从基础查询到高级优化的完整模式集合，重点包括查询优化、事务处理，以及用于清晰数据访问的仓储（Repository）模式。

适用时机

使用 Prisma Client 进行数据库查询
为数据访问创建仓储
使用事务
查询优化与 N+1 预防
处理 Prisma 错误

基础用法与核心查询模式

资料给出基于 PrismaService 的示例：始终使用 PrismaService.main，并在使用前检查 PrismaService.isAvailable，未初始化时抛出错误。示例覆盖 findUnique、findMany（带 where、orderBy、take）、create、update、delete。复杂过滤支持多条件组合，以及 AND/OR 条件，例如按 email 包含、isActive、createdAt 大于等于某日期过滤，或在 AND/OR 中组合 published、author.isActive、title/content 包含等条件。

仓储模式

资料建议在以下情况使用仓储：包含 join/include 的复杂查询、在多个位置复用的查询、需要为测试提供 mock。对于简单的一次性查询或原型开发，可以跳过仓储。仓储模板示例包含 findById（带 include profile）、findByEmail、findActive、create、update、delete，并使用 Prisma.UserCreateInput、Prisma.UserUpdateInput 等类型。服务层通过构造函数实例化仓储并调用，例如 getById 在未找到用户时抛出错误。

事务模式

简单事务使用 PrismaService.main.$transaction(async (tx) => {...})，在事务内创建用户与用户资料并返回结果。交互式事务同样使用 $transaction 回调，示例中先查询用户、更新 lastLogin、写入审计日志，并配置 maxWait（最长等待 5 秒开始）与 timeout（10 秒超时）。

查询优化

资料强调使用 select 限制字段，避免 findMany 拉取全部字段；select 也可用于关系字段，例如只选择 profile 的 firstName、lastName。使用 include 时需谨慎，避免过度嵌套 include（如 posts 再 include comments、workflows 再 include steps 再 include actions），只包含真正需要的关联。

N+1 查询预防

资料指出在循环中对每个用户调用 findUnique 会产生 N+1 问题。解决方案一：使用 include 在单次查询中获取关联；解决方案二：批量查询，先收集 userIds，再用 where: { userId: { in: userIds } } 一次查询，并用 Map 建立映射。

关系与嵌套写入

一对多示例：查询用户时 include posts，并支持 where、orderBy、take。嵌套写入示例：创建用户时同时 create profile；更新用户时同时 update profile 的 bio。

错误处理

资料使用 Prisma.PrismaClientKnownRequestError 判断错误码：P2002 唯一约束冲突、P2003 外键约束失败、P2025 记录未找到、P2014 关系违规。示例中将 P2002 转为 ConflictError、P2003 转为 ValidationError、P2025 转为 NotFoundError，并调用 Sentry.captureException 后重新抛出。

高级模式

聚合：count 带 where；aggregate 使用 _count、_avg、_sum 与 where；groupBy 按 authorId 分组并统计 id。Upsert：按 email 更新 lastLogin，不存在则创建用户。TypeScript 模式：使用 Prisma.UserCreateInput 作为创建输入类型；使用 Prisma.UserGetPayload<{ include: { profile: true } }> 定义包含关系的类型。

最佳实践

始终使用 PrismaService.main，不要新建 PrismaClient 实例
复杂查询使用仓储，保持数据访问有组织
只选择需要的字段，用 select 提升性能
预防 N+1 查询，使用 include 或批量查询
多步骤操作使用事务保证原子性
处理错误时检查具体的 Prisma 错误码

相关工作流（资料中的增强部分）

阶段一：Schema 优先设计。将 schema.prisma 作为“唯一事实来源”，在其中定义关系（1-1、1-n、m-n）与索引（@index）；数据库变更始终通过 prisma migrate dev 进行，避免手动执行 SQL 造成漂移；除 prisma-client-js 外，可使用 zod-prisma 或 prisma-nestjs-graphql 等 generator 减少重复代码。

阶段二：查询实现。不要使用 findMany()（即 SELECT *），始终用 select 只取所需字段；不要将用户输入直接放入 where，需先经过校验，并优化过滤以利用索引；使用 include 时注意嵌套查询性能，必要时使用 fluent api 或 raw query。

阶段三：优化与安全。避免在循环中调用 findUnique，收集 ids 后用 where: { id: { in: ids } } 单次查询；需要一致性的多写操作使用 $transaction([]) 或 $transaction(async tx => ...) 包裹；在 Serverless 环境（Lambda/Vercel）中，为避免超出连接上限，使用 Prisma Accelerate 或 PgBouncer 进行连接池管理。

检查点

阶段一：schema.prisma 中是否使用 @updatedAt、@default(now()) 等便利特性？
阶段二：是否需要软删除？如需要，是否通过 Middleware 或 Extension 实现？
阶段三：大数据集是否优先使用 cursor pagination 而非 skip/take（Offset pagination）？

技能介绍