如何在Blitz.js中使用Prisma：数据库建模、迁移与自动CRUD完整教程

如何在Blitz.js中使用Prisma：数据库建模、迁移与自动CRUD完整教程

【免费下载链接】blitz⚡️ The Missing Fullstack Toolkit for Next.js项目地址: https://gitcode.com/gh_mirrors/bl/blitz

🚀Blitz.js 是专为 Next.js 打造的全栈开发工具包（The Missing Fullstack Toolkit for Next.js），它把 Prisma 作为官方数据库层深度集成进来——从数据库建模、Prisma 迁移（migrate）到自动 CRUD 接口，一条命令流就能跑通。本教程面向新手，带你从零走完「建模 → 迁移 → 自动 CRUD → 种子数据」的完整流程。

一、为什么 Blitz.js 和 Prisma 是"天生一对"

在 Blitz.js 项目里，数据库工作被封装在独立的db/目录中，开箱即用的结构如下（以官方示例应用 apps/web/ 为例）：

• db/schema.prisma：数据模型定义（Prisma Schema）
• db/index.ts：全局 Prisma 客户端入口
• db/seeds.ts：种子数据脚本（可选）

Blitz 对 Prisma 做了两层增强：

1. 客户端增强：enhancePrisma会包装PrismaClient，保证服务端全局单例，并额外提供db.$reset()方法，一键重置开发数据库（生产环境会自动拦截，防止误删数据）。核心实现见 packages/blitz/src/utils/enhance-prisma.ts
2. CLI 命令透传：所有 Prisma 命令都可以用blitz prisma 子命令调用，实现见 packages/blitz/src/cli/commands/prisma.ts

二、快速创建应用：一条命令生成数据库骨架

全局安装 CLI 后，用以下命令创建新应用：

npm install -g blitz blitz new my-app cd my-app blitz dev

blitz new会自动生成db/schema.prisma（默认使用 SQLite，零配置）、迁移目录db/migrations/和示例种子脚本，你可以直接在 packages/generator/templates/app/db/ 查看官方模板生成的初始数据库文件。

打开 apps/web/db/schema.prisma 看看默认模型的样子：

• datasource声明数据库类型与连接地址
• generator client声明生成 Prisma Client
• model User定义了id、email（唯一约束）、hashedPassword、role等字段，并通过@relation关联Session与Token表

💡 提示：默认 SQLite 方便本地开发；上线建议切换 Postgres（官方模板中也有说明，见 apps/toolkit-app/db/schema.prisma 末尾的注释）。

三、数据库建模：3 分钟读懂 schema.prisma

Prisma Schema 采用"模型即表、字段即列"的直观语法。以 apps/web/db/schema.prisma 中的User模型为例，几个新手常问的点：

手动建模：直接编辑db/schema.prisma，然后运行迁移（见下一节）。

自动建模：更推荐用代码生成器，一条命令即可把模型写入 schema 文件：

blitz generate model Post title:String body:String? published:Boolean

生成器会解析字段参数、把新模型追加到 schema，并在完成后询问你是否立即执行prisma migrate dev——整个流程实现在 packages/generator/src/generators/model-generator.ts。

四、执行迁移：把模型同步到数据库

Blitz 把 Prisma 迁移命令统一收口到blitz prisma下：

blitz prisma migrate dev --name init

这条命令会：① 生成迁移 SQL 到db/migrations/；② 更新本地数据库结构；③ 重新生成 Prisma Client。以 integration-tests/auth/db/migrations/ 目录为例，每次迁移都会形成一个带时间戳的独立子目录，便于版本追溯。

其他常用命令速查：

• blitz prisma generate—— 重新生成 Prisma Client（改了 schema 后必跑）
• blitz prisma format—— 格式化 schema 文件
• blitz prisma studio—— 可视化查看/编辑数据
• blitz db seed—— 运行种子数据（实现见 packages/blitz/src/cli/commands/db.ts）

五、接入 db 并编写 CRUD 接口

Blitz 的 RPC 架构下，数据库操作都写在src/queries/（读）和src/mutations/（写）中，它们通过import db from "db"拿到增强后的 Prisma 客户端。全局单例的构造逻辑在 apps/web/db/index.ts：

const EnhancedPrisma = enhancePrisma(PrismaClient) const prisma = new EnhancedPrisma()

读数据（Query）—— 一行代码就是完整 CRUD 的 Read：

const users = await db.user.findMany()

完整示例见 apps/web/src/queries/getUsers.ts，其中ctx.session.$authorize()还顺带完成了登录鉴权。

写数据（Mutation）—— Create 同样是标准 Prisma 调用：

const user = await db.user.create({data: {name: input.name, email: input.email}})

参考 apps/web/src/mutations/createUser.ts。

六、让 Blitz 自动生成完整 CRUD 代码

手写 Query/Mutation 之后，还可以让生成器一步到位——针对某个模型批量生成查询、变更文件和对应页面：

blitz generate queries Post blitz generate mutations Post

相关生成器源码位于 packages/generator/src/generators/（如 queries-generator.ts、mutations-generator.ts），官方模板可直接对照 packages/generator/templates/queries/ 与 packages/generator/templates/mutations/ 查看生成结果。

七、种子数据：快速填充测试数据

db/seeds.ts会在blitz db seed时执行。官方示例 apps/toolkit-app/db/seeds.ts 展示了两个关键点：

• await db.$reset()：重置数据库后再灌数据（仅开发环境可用）
• db.user.create({...})：用标准 Prisma API 插入测试账号

八、常见问题 FAQ

Q1：改了 schema 后页面报错怎么办？A：运行blitz prisma generate重新生成客户端，再执行一次blitz prisma migrate dev。

Q2：db.$reset()为什么在报错？A：它是开发环境专用的重置方法，生产环境调用会被主动拦截（见 packages/blitz/src/utils/enhance-prisma.ts）。

Q3：默认数据库可以换吗？A：可以。把schema.prisma中datasource的provider与url改为 Postgres 等即可，随后正常执行迁移。

九、总结

掌握「schema.prisma 建模 →blitz prisma migrate dev迁移 → 生成器自动 CRUD」这条主线，你就能在 Blitz.js 中高效完成全栈数据层开发。接下来可以阅读 CONTRIBUTING.md 了解如何参与项目贡献，或在apps/目录下对照各示例应用（如 apps/web/、apps/toolkit-app/）动手实践。⚡️

【免费下载链接】blitz⚡️ The Missing Fullstack Toolkit for Next.js项目地址: https://gitcode.com/gh_mirrors/bl/blitz