这是一份完全通用、无业务耦合、适用于所有 Prisma + TypeScript 项目的企业级官方标准规范，覆盖命名、Schema、调用、迁移、安全、性能全场景，直接照做即可保证项目规范、稳定、可维护。

---

一、命名规范（强制统一）

1. 模型 / 表

• Prisma 模型：大驼峰 User Product Order
• 数据库表名：蛇形命名 @@map("users")
• 代码调用：小驼峰 prisma.user

2. 字段

• 字段名：小驼峰 userId createdAt
• 数据库字段：蛇形命名 @map("user_id")
• 布尔值：前缀 is / has isActive hasPermission

3. 枚举

• 大驼峰 UserStatus OrderType
• 枚举值：全小写 / 蛇形 active pending_payment

4. 关联字段

• 一对多：模型名复数 posts Post[]
• 多对一：模型名单数 user User

---

二、Schema 模型定义规范

1. 主键规范

• 统一使用 id 字段
• 推荐类型：Int / BigInt
• 自增：@default(autoincrement())

prisma

id BigInt @id @default(autoincrement())

2. 必选时间戳（所有表通用）

prisma

createdAt DateTime @default(now())
updatedAt DateTime @updatedAt

3. 软删除规范（禁止物理删除）

prisma

deletedAt DateTime?

4. 约束规范

• 唯一约束：@@unique([field1, field2])
• 普通索引：@@index([field])（高频查询字段）
• 外键关联必须定义 onDelete 策略

5. 关联规范

• 一对多必须双向关联
• 级联删除常用：onDelete: Cascade

prisma

// 一方
posts Post[]

// 多方
user User @relation(fields: [userId], references: [id], onDelete: Cascade)
userId BigInt

6. 可选 / 必填规范

• 业务必填字段：不加？
• 可选字段：加？
• 字符串避免空字符串，优先 null

---

三、Prisma 客户端实例化规范

1. 全局单例（唯一正确写法）

禁止在多个文件中 new PrismaClient ()

typescript

运行

// src/prisma/client.ts
import { PrismaClient } from '@prisma/client'

const globalForPrisma = globalThis as unknown as {
  prisma: PrismaClient | undefined
}

export const prisma = globalForPrisma.prisma ?? new PrismaClient()

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

2. 日志配置（开发环境开启）

typescript

运行

new PrismaClient({
  log: ['query', 'info', 'warn', 'error'],
})

---

四、CRUD 操作通用规范

1. 查询

• 查唯一数据：findUnique（必须用唯一键）
• 查列表数据：findMany
• 查单条任意：findFirst
• 只查需要字段：使用 select
• 关联查询：使用 include

ts

prisma.user.findUnique({
  where: { id },
  select: { id: true, name: true },
  include: { posts: true }
})

2. 创建

• 单条：create
• 批量：createMany
• 唯一键冲突会报错 P2002

3. 更新

• 数字累加必须用 increment（防并发）

ts

data: { count: { increment: 1 } }

• 禁止手动赋值：count: count + 1

4. 删除

• 生产环境：软删除
• 测试 / 本地：delete

ts

prisma.user.update({
  where: { id },
  data: { deletedAt: new Date() }
})

5. 存在则更新 / 不存在则创建（通用最佳实践）

ts

prisma.model.upsert({
  where: { uniqueKey },
  create: { ... },
  update: { ... }
})

---

五、TypeScript 类型安全规范

1. 禁止使用 any，使用 Prisma 自动生成类型
2. BigInt 类型必须加 n：1n
3. 枚举使用官方导出类型

ts

import { UserStatus } from '@prisma/client'

1. 修改 Schema 后必须执行

bash

运行

npx prisma generate

---

六、错误处理规范

捕获 Prisma 标准错误码：

ts

import { Prisma } from '@prisma/client'

try {
  await prisma.user.create(...)
} catch (e) {
  if (e instanceof Prisma.PrismaClientKnownRequestError) {
    switch (e.code) {
      case 'P2002': // 唯一约束冲突
        throw new Error('数据已存在')
      case 'P2025': // 数据不存在
        throw new Error('记录不存在')
    }
  }
}

---

七、数据库迁移（Migrations）规范（最重要）

本地开发

bash

运行

# 创建迁移文件（自动同步表结构）
npx prisma migrate dev --name 描述
# 生成类型
npx prisma generate

生产环境（仅允许这一条）

bash

运行

npx prisma migrate deploy

重置数据库（仅本地测试）

bash

运行

npx prisma migrate reset

---

八、性能规范

1. 禁止无条件 findMany() 查询全表
2. 列表必须分页：skip / take
3. 高频查询字段必须建索引
4. 避免 N+1 查询，使用 include
5. 批量操作优先使用 createMany / updateMany

---

九、安全规范

1. 生产环境禁止打印 SQL 日志
2. 禁止直接暴露 Prisma 给前端
3. 用户输入必须校验后传入
4. 禁止使用 deleteMany 无条件清空表

---

十、绝对禁止行为（黑名单）

1. ❌ 生产环境执行 migrate reset
2. ❌ 生产环境使用 prisma db push
3. ❌ 手动修改数据库表结构
4. ❌ 多处创建 new PrismaClient()
5. ❌ 物理删除业务数据
6. ❌ 查询不使用 select 直接返回全字段

---

核心极简总结（5 条万能规则）

1. 改模型 → 必执行 generate
2. 查唯一 → 用 findUnique
3. 数字累加 → 用 increment
4. 实例化 → 全局单例
5. 生产上线 → 只执行 migrate deploy