Prisma Client API Reference

Prisma Client API Reference 是什么

Prisma Client API Reference 是 Prisma 官方面向当前 Prisma 项目的查询参考 Skill，覆盖客户端构造、模型 CRUD、查询结果形状、筛选、关系、事务、原生 SQL和客户端级方法。它按影响等级组织参考，遇到 findMany、create、update、delete 或 transaction 等问题时只加载相关章节。

适用场景与选择边界

适合编写和审查 Prisma 查询、实现分页与过滤、读取关系、聚合统计、批量写入和事务。数据库首次接入应使用 Prisma Database Setup；命令行迁移、生成和 Studio 操作应使用 Prisma CLI，避免把 API 与 CLI 责任混在一起。

核心能力与工作机制

模型方法包括 findUnique、findFirst、findMany、create、createMany、update、upsert、delete、count、aggregate 与 groupBy。查询选项覆盖 where、select、include、omit、orderBy、take、skip、cursor 和 distinct；关系过滤支持 some、every、none、is 与 isNot，并提供事务和原生查询安全指导。

实际工作流

先确认 schema 中的模型、唯一键和关系，再定义查询目标与返回字段。优先使用类型安全模型 API，明确 where 与 select 或 include，评估分页和索引。多步原子操作进入 transaction；只有模型 API 无法表达时才考虑原生 SQL，并使用安全的参数化接口。

输入、输出与交付物

输入是 Prisma schema、业务查询目标、筛选与排序规则、事务边界和期望返回形状。输出通常是类型安全的 Prisma Client 代码及错误处理建议；重要查询还应附带索引假设、数据量和并发考虑，而不是只给一段能编译的示例。

依赖、账号与权限

需要已经生成且与 schema 同步的 Prisma Client，以及正确配置的数据库连接和 driver adapter。调用方式还受 Prisma 版本、数据库提供商和部署运行时影响；示例中的模型名与字段必须替换为项目真实 schema。

限制与安全风险

无约束 findMany、深层 include、offset 分页和逐行关系查询可能带来性能问题。updateMany、deleteMany 与原生 SQL 会大范围改变数据；事务过长会增加锁竞争。所有写操作要有明确 where 和测试，原生查询避免不安全字符串拼接。

适合谁使用

适合 TypeScript 或 JavaScript 后端开发者、代码审查者和正在把 SQL 需求映射到 Prisma API 的团队。对数据库性能负责的人还应结合具体数据库的执行计划和索引工具，不要只依赖 ORM 层。

上手与验收建议

从一个真实模型和小数据集开始，先写最窄的 select 与明确 where，再增加关系和分页。验收时检查生成 SQL 或执行计划、返回字段、空值与异常路径；事务用失败注入验证回滚，批量写入先在副本或事务中演练。

来源、版本与许可

依据 prisma/skills 固定提交中的完整 Prisma Client API Reference、skills.sh 详情与 MIT 许可证整理。

常见问题

1. 查一条记录应使用 findUnique 还是 findFirst？

有唯一键条件时优先 findUnique，它明确表达唯一性；需要按普通条件和排序取第一条时才用 findFirst。若不存在应直接失败，可选择对应的 OrThrow 版本。

2. select、include 和 omit 有什么区别？

select 明确只返回指定字段，include 加载关系，omit 排除不希望返回的字段。应根据接口最小数据需求选择，避免为了方便把大字段和深层关系全部加载。

3. 关系列表如何筛选？

对一对多或多对多关系可用 some、every 和 none 表达至少一个、全部或没有相关记录匹配；一对一关系用 is 与 isNot。条件应结合真实关系可空性测试。

4. 什么时候使用 $transaction？

多个读写必须作为一个原子业务动作提交时使用事务，并选择适合的批量或交互形式。事务应尽量短，避免在其中执行慢网络请求，以减少锁时间和失败重试成本。

5. 原生 SQL 可以直接拼接用户输入吗？

不可以。只有类型安全模型 API 无法表达需求时才考虑原生查询，并使用参数化、标记模板等安全接口。字符串拼接会引入 SQL 注入和类型转换风险。

6. 大列表分页应使用 skip 还是 cursor？

skip 与 take 适合浅层页码，但很大的 offset 可能越来越慢；稳定排序且数据量大时通常更适合 cursor 分页。选择前要确认唯一排序键和产品的跳页需求。

7. 如何避免查询返回过多数据？

为 where 设置明确条件，用 select 限定字段，用 take 控制条数，并谨慎 include 关系。对热点查询还应查看数据库索引和执行计划，ORM 类型安全不等于查询一定高效。

8. 批量更新或删除怎样降低风险？

先用相同 where 做 count 或只读查询确认范围，在事务和备份策略下执行，并检查返回数量。没有 where 的 deleteMany 或 updateMany 可能影响整表，不能直接用于生产。