prisma-patterns

Prisma Patterns

TypeScript 后端中使用 Prisma ORM 的生产级实践方案与隐蔽踩坑指南。

套用模式前请先核对 Prisma 版本。 Prisma 的 API 在各个大版本之间有所演进：

npx prisma --version

不同版本间值得注意的 API 差异：

• relationJoins 可以通过 JOIN 方式加载关联数据，而非发起独立查询，但在大型 1:N 关联或深层 include 时可能引发行数暴涨（Row Explosion）—— 建议对这两种方式进行性能基准测试（Benchmark）
• 新增了 omit 字段修饰符和 prisma.$extends 客户端扩展 API
• 较新安装的版本：包名可能为 prisma 而非 @prisma/client；PrismaClient 可能需要驱动适配器（如 @prisma/adapter-pg）；datasource.url 可能位于 prisma.config.ts 而非 schema.prisma
• CLI 命令（migrate dev、migrate deploy、generate）在各版本间保持一致

何时启用

• 设计或修改 Prisma schema 模型及关联关系时
• 编写查询、事务或分页逻辑时
• 使用 updateMany、deleteMany 或任何批量操作时
• 执行或规划数据库迁移（Migration）时
• 部署到 Serverless 环境（Vercel、Lambda、Cloudflare Workers）时
• 实现软删除（Soft Delete）或多租户行级过滤时

核心概念

ID 策略

策略	适用场景	避用场景
@default(cuid())	默认首选 — URL 安全、可排序、无碰撞风险	外部系统需要自增/连续 ID 时
@default(uuid())	需要与非 Prisma 外部系统保持兼容时	高频写入表（随机 UUID 会导致 B-tree 索引碎片化）
@default(autoincrement())	内部关联表、审计日志	对外暴露的 ID（会泄露系统记录总数）

Schema 默认配置

model User {
  id        String    @id @default(cuid())
  email     String    @unique  // @unique 已自动创建索引 — 无需额外添加 @@index
  name      String
  role      Role      @default(USER)
  posts     Post[]
  createdAt DateTime  @default(now())
  updatedAt DateTime  @updatedAt
  deletedAt DateTime?

  @@index([createdAt])
  @@index([deletedAt, createdAt]) // 用于“软删除 + 排序”查询的复合索引
}

• 在所有作为外键以及常用于 WHERE 或 ORDER BY 的列上添加 @@index。
• 如果可预见后续需要软删除功能，请在初期直接声明 deletedAt DateTime? —— 后期向生产表添加此列需要执行数据库迁移。
• updatedAt @updatedAt 仅在 Prisma 执行 update 和 upsert 时自动更新（批量更新时的踩坑点见“反模式”章节）。

include vs select

	include	select
返回内容	所有标量字段 + 指定的关联关系	仅返回指定的字段
适用场景	需要大部分字段外加关联数据时	高频热点路径、大表、避免过度拉取（Over-fetching）
性能	在字段较多的宽表上可能过度拉取	传输 Payload 极小，大数据集上速度更快
Prisma 5 说明	默认采用 JOIN 方式（relationJoins）	同上

// include — 返回所有列 + 关联数据
const user = await prisma.user.findUnique({
  where: { id },
  include: { posts: { select: { id: true, title: true } } },
});

// select — 显式白名单
const user = await prisma.user.findUnique({
  where: { id },
  select: { id: true, email: true, name: true },
});

切勿直接在 API 响应中返回未过滤的 Prisma 实体对象 —— 请映射为响应 DTO 以精准控制暴露字段：

// 错误示例：泄露了 passwordHash、deletedAt 等内部敏感字段
return await prisma.user.findUniqueOrThrow({ where: { id } });

// 正确示例：显式 DTO 映射
const user = await prisma.user.findUniqueOrThrow({ where: { id } });
return { id: user.id, name: user.name, email: user.email };

事务形式选择

场景	推荐形式
彼此独立、无前后依赖的操作	数组形式（Array form）
后续步骤依赖前一步骤的结果	交互式形式（Interactive form）
包含外部调用（发邮件、HTTP 请求）	放到事务外部处理

// 数组形式 — 在单个往返（Round trip）中批量执行
const [user, post] = await prisma.$transaction([
  prisma.user.update({ where: { id }, data: { name } }),
  prisma.post.create({ data: { title, authorId: id } }),
]);

// 交互式形式 — 只能使用 tx 客户端，严禁使用外部的 prisma 客户端
const post = await prisma.$transaction(async (tx) => {
  const user = await tx.user.findUniqueOrThrow({ where: { id } });
  if (user.role !== 'ADMIN') throw new Error('Forbidden');
  return tx.post.create({ data: { title, authorId: user.id } });
});

PrismaClient 单例模式

每个 PrismaClient 实例都会打开独立的连接池。务必只初始化一次。

// lib/prisma.ts

// 方案 A — 基于适配器的初始化（较新的 Prisma 版本必须）
import { PrismaClient } from '@prisma/client'; // 或当前项目生成的 client 路径
import { PrismaPg } from '@prisma/adapter-pg';

function createPrismaClient() {
  const adapter = new PrismaPg({
    connectionString: process.env.DATABASE_URL!,
  });
  return new PrismaClient({
    adapter,
    log: process.env.NODE_ENV === 'development' ? ['query', 'error'] : ['error'],
  });
}

const globalForPrisma = globalThis as unknown as { prisma?: PrismaClient };

export const prisma = globalForPrisma.prisma ?? createPrismaClient();

if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma;

// 方案 B — 直接初始化（较旧版本，无需适配器）
// import { PrismaClient } from '@prisma/client';
// export const prisma = globalForPrisma.prisma ?? new PrismaClient({ ... });

如果你的 Prisma 版本要求在 PrismaClient 构造函数中传入 adapter 参数，请使用方案 A。
如果 new PrismaClient() 无参调用即可正常工作，请使用方案 B。让 TypeScript 编译器提示你哪种正确。

使用 globalThis 模式可防止热重载（Next.js、nodemon、ts-node-dev）期间创建重复的连接池实例。

N+1 查询问题

在循环内部加载关联数据会导致每行记录都发起一次额外查询。

// 错误示例：N+1 问题 — 每个用户多发起一次查询
const users = await prisma.user.findMany();
for (const user of users) {
  const posts = await prisma.post.findMany({ where: { authorId: user.id } });
}

// 正确示例：单条查询搞定
const users = await prisma.user.findMany({ include: { posts: true } });

在 Prisma 5+ 启用 relationJoins 后，include 形式会使用单条 JOIN。在大型 1:N 数据集中这可能会增大结果集体积 —— 如果关联记录较多，建议对两种方式做 Benchmark 基准测试。

代码示例

游标分页 Cursor Pagination（推荐用于 Feed 流和大数据集）

async function getPosts(cursor?: string, limit = 20) {
  const items = await prisma.post.findMany({
    where: { published: true },
    orderBy: [
      { createdAt: 'desc' },
      { id: 'desc' }, // 增加次级排序字段，防止时间戳重复导致分页抖动/不稳定
    ],
    take: limit + 1,
    ...(cursor && { cursor: { id: cursor }, skip: 1 }),
  });

  const hasNextPage = items.length > limit;
  if (hasNextPage) items.pop();

  return { items, nextCursor: hasNextPage ? items[items.length - 1].id : null };
}

一次查询 limit + 1 条并 pop() 掉多余的一条 —— 这是无需额外发起 count 查询即可判断 hasNextPage 的标准写法。务必将唯一字段（如 id）作为次级 orderBy，以防多条记录时间戳相同时分页顺序失序。只有当用户需要直接跳转到任意页码时（如后台管理表格），才使用 Offset 分页。

软删除（Soft Delete）

// 始终显式过滤 — 不要依赖中间件（中间件会隐藏逻辑，难以调试）
const activeUsers = await prisma.user.findMany({ where: { deletedAt: null } });

await prisma.user.update({ where: { id }, data: { deletedAt: new Date() } });
await prisma.user.update({ where: { id }, data: { deletedAt: null } }); // 恢复

错误处理

import { Prisma } from '@prisma/client'; // 或当前项目生成的 client 路径

try {
  await prisma.user.create({ data: { email } });
} catch (e) {
  if (e instanceof Prisma.PrismaClientKnownRequestError) {
    if (e.code === 'P2002') throw new ConflictError('Email already exists');
    if (e.code === 'P2025') throw new NotFoundError('Record not found');
    if (e.code === 'P2003') throw new BadRequestError('Referenced record does not exist');
  }
  throw e;
}

常见错误码：P2002 唯一约束冲突 · P2025 记录未找到 · P2003 外键约束冲突。

请在 Service 业务边界捕获这些异常并转换为领域错误（Domain Error）。切勿将底层的 Prisma 原始错误信息直接暴露给 API 调用方。

连接池 — Serverless 环境

将连接参数直接嵌入到 DATABASE_URL 中 —— 如果 URL 本身已包含查询参数（例如 ?schema=public），直接进行字符串拼接会导致 URL 格式失效：

# .env — 推荐写法：直接在 URL 中配置参数
DATABASE_URL="postgresql://user:pass@host/db?connection_limit=1&pool_timeout=20"

# 使用外部连接池代理时（如 PgBouncer、Supabase pooler）
DATABASE_URL="postgresql://user:pass@host/db?pgbouncer=true&connection_limit=1"

// Vercel、AWS Lambda 及类似 Serverless 运行时：
// 将每个实例的连接池上限限制为 1；connection_limit 和 pool_timeout 通过 DATABASE_URL 控制

// 基于适配器的配置（若 Prisma 安装版本要求传入 adapter）：
import { PrismaClient } from '@prisma/client';
import { PrismaPg } from '@prisma/adapter-pg';

const prisma = new PrismaClient({
  adapter: new PrismaPg({ connectionString: process.env.DATABASE_URL }),
});

// 直接配置（若 Prisma 安装版本不需要 adapter）：
// const prisma = new PrismaClient();

反模式（Anti-Patterns）

updateMany 返回的是 count 而非记录列表

// 错误示例：返回结果为 { count: 2 } — users[0] 为 undefined
const users = await prisma.user.updateMany({ where: { role: 'GUEST' }, data: { role: 'USER' } });

// 正确示例：先获取 ID 列表，再更新，最后仅查询受影响的行
const targets = await prisma.user.findMany({
  where: { role: 'GUEST' },
  select: { id: true },
});
const ids = targets.map((u) => u.id);
await prisma.user.updateMany({ where: { id: { in: ids } }, data: { role: 'USER' } });
const updated = await prisma.user.findMany({ where: { id: { in: ids } } });

deleteMany 同理 —— 仅返回 { count: n }，绝不会返回被删除的记录数据。

$transaction 交互式事务默认 5 秒超时

// 错误示例：事务内部包含耗时超过 5 秒默认限制的外部调用 → 导致 "Transaction already closed" 报错
await prisma.$transaction(async (tx) => {
  const user = await tx.user.findUniqueOrThrow({ where: { id } });
  await sendWelcomeEmail(user.email); // 外部网络调用
  await tx.user.update({ where: { id }, data: { emailSent: true } });
});

// 正确示例：将外部调用移到事务外部
const user = await prisma.user.findUniqueOrThrow({ where: { id } });
await sendWelcomeEmail(user.email);
await prisma.user.update({ where: { id }, data: { emailSent: true } });

// 仅在批量处理确实需要时才调大 timeout
await prisma.$transaction(async (tx) => { ... }, { timeout: 30_000 });

migrate dev 可能会重置数据库

migrate dev 会检测 Schema 偏移（Schema drift），并可能提示重置数据库，从而删掉全部数据。

# 严禁在共享开发环境、测试环境或生产环境运行！
npx prisma migrate dev --name add_column

# 除本地单人开发外，其余所有环境通用安全命令：
npx prisma migrate deploy

# 仅检查 Drift 偏移而不实际执行迁移：
npx prisma migrate diff \
  --from-migrations ./prisma/migrations \
  --to-schema-datamodel ./prisma/schema.prisma \
  --shadow-database-url "$SHADOW_DATABASE_URL"

手动修改 Migration 文件会导致后续部署失败

Prisma 会对每个迁移文件计算 Checksum 校验和。文件在应用后若被手动修改，会导致已运行过原迁移的各个环境抛出 P3006 checksum mismatch 错误。正确的做法是新建一个 Migration。

破坏性 Schema 变更需要分步迁移

向已有字段添加 NOT NULL 或重命名列...