用途
Prisma Expert 是一个围绕 Prisma ORM 的专家技能,用于处理模式设计、迁移、查询优化、关系建模,以及 PostgreSQL、MySQL、SQLite 上的数据库操作。当问题明确属于原始 SQL 优化、数据库服务器配置或基础设施层连接池时,该技能会停止并建议转交 postgres-expert、mongodb-expert、database-expert 或 devops-expert。
环境检测
被调用时会先执行环境检测:使用 npx prisma --version 检查 Prisma 版本(未安装时提示 Prisma not installed);在 prisma/schema.prisma 中查找 provider;查看 prisma/migrations/ 中是否已有迁移;检查 node_modules/.prisma/client/ 中 Prisma Client 的生成状态。
应用策略
- 识别属于 Prisma 的具体问题类别;2. 检查模式或查询中的常见反模式;3. 应用渐进式修复(最小 → 更好 → 完整);4. 通过 Prisma CLI 与测试进行验证。
问题手册
模式设计
常见问题包括关系定义错误导致运行时错误、频繁查询字段缺少索引、模式与数据库之间的枚举同步问题、字段类型不匹配。诊断命令包括 npx prisma validate、npx prisma migrate diff --from-schema-datamodel prisma/schema.prisma --to-schema-datasource prisma/schema.prisma、npx prisma format。修复分为:最小(修正关系注解、补全 @relation 指令)、更好(用 @@index 添加合适索引、优化字段类型)、完整(重构模式实现规范化、添加复合键)。文档给出了带有显式关系、命名、级联行为、索引与 @@map 的用户/文章模式示例。
迁移
常见问题包括团队环境中的迁移冲突、失败迁移导致数据库处于不一致状态、开发中的影子数据库问题、生产部署迁移失败。诊断包括 npx prisma migrate status、查看 prisma/migrations/ 目录以及迁移历史表。修复分为:最小(用 prisma migrate reset 重置开发数据库)、更好(手动修复迁移 SQL、使用 prisma migrate resolve)、完整(压缩迁移、为全新环境创建基线)。安全迁移流程:开发使用 npx prisma migrate dev --name descriptive_name;生产使用 npx prisma migrate deploy(生产绝不使用 migrate dev);生产迁移失败时使用 npx prisma migrate resolve --applied "migration_name" 或 --rolled-back。
查询优化
常见问题包括关系导致的 N+1 查询、过度 include 造成过度获取、大模型缺少 select、缺少索引导致查询缓慢。诊断方式为启用查询日志并在客户端通过 log: [{ emit: 'event', level: 'query' }] 与 prisma.$on('query', ...) 输出查询语句与耗时。修复分为:最小(添加 include 避免 N+1)、更好(用 select 只取所需字段)、完整(复杂聚合使用原始查询、实现缓存)。文档给出从 N+1 反例到 include、select、$queryRaw 的渐进式优化模式。
连接管理
常见问题包括连接池耗尽、"Too many connections" 错误、无服务器环境中的连接泄漏、初始连接缓慢。诊断示例为通过 psql 查询 pg_stat_activity 的当前连接数。修复分为:最小(在 DATABASE_URL 中配置连接限制)、更好(实现正确的连接生命周期管理)、完整(高流量应用使用连接池如 PgBouncer)。文档给出服务端无服务器(Vercel、AWS Lambda)场景下的全局 PrismaClient 复用、优雅关闭(beforeExit 中 $disconnect)以及带 connection_limit 与 pool_timeout 的连接 URL 示例。
事务模式
常见问题包括非原子操作导致数据不一致、并发事务死锁、长事务阻塞读取、嵌套事务混淆。诊断示例为捕获事务错误并检查错误码 P2034(事务冲突)。文档给出顺序操作(数组式 $transaction)、带手动控制的交互式事务(含业务逻辑校验、maxWait、timeout、isolationLevel),以及乐观并发控制(通过 version 字段条件更新与 increment)等模式。
代码审查清单
模式质量方面检查:各模型是否有合适的 @id 与主键;关系是否使用带 fields 和 references 的显式 @relation;是否定义级联行为(onDelete、onUpdate);频繁查询字段是否添加索引;固定值集合是否使用枚举;是否用 @@map 遵循表命名约定。查询模式方面检查:是否存在 N+1;是否用 select 只取必要字段;列表查询是否实现分页;复杂聚合是否使用原始查询;数据库操作是否有适当的错误处理。性能方面检查:连接池是否配置得当;WHERE 子句字段是否有索引;多列查询是否有复合索引;开发环境是否启用查询日志;慢查询是否被识别并优化。迁移安全方面检查:迁移是否在生产部署前测试;模式变更是否向后兼容(不丢数据);迁移脚本是否经过正确性审查;回滚策略是否记录。
应避免的反模式
隐式多对多带来的额外开销(复杂关系应使用显式连接表)、过度 include(不要包含不需要的关系)、忽略连接限制(始终按环境配置连接池大小)、滥用原始查询(尽可能使用 Prisma 查询,仅在复杂场景使用原始查询)、在生产使用 migrate dev。
适用场景
该技能适用于执行上述概览中描述的工作流或操作。
限制
仅在任务明确匹配上述范围时使用该技能;不要将输出视为针对具体环境的验证、测试或专家评审的替代;若缺少必需的输入、权限、安全边界或成功标准,应停止并请求澄清。