企业官网建设流程全解析

Wasp 0.12 教程解析：用 PSL 定义数据库实体 Task 并生成迁移

【免费下载链接】waspThe batteries-included full-stack framework for the AI era. Develop JS/TS web apps (React, Node.js, and Prisma) using declarative code that abstracts away complex full-stack features like auth, background jobs, RPC, email sending, end-to-end type safety, single-command deployment, and more.项目地址: https://gitcode.com/GitHub_Trending/wa/wasp

本篇以 Wasp 官方 0.12 版教程的《4. Database Entities》一节为主线，讲解如何在main.wasp文件中使用 Prisma Schema Language（PSL）定义Task实体，以及如何通过wasp db migrate-dev和wasp db studio两个命令完成数据库表结构的变更与验证。读完本文，你将能够独立定义 Wasp 实体、理解{=psl ... psl=}语法块的解析原理，并掌握实体变更后的完整落地流程。

实体是 Wasp 数据模型的基础

实体（Entity）是 Wasp 中最核心的概念之一，它决定了你的应用往数据库里存什么。Wasp 官方教程在构建 Todo App 时，任务（Task）是应用的核心数据，因此第一步就是定义Task实体。

教程给出的定义如下：

// ... entity Task {=psl id Int @id @default(autoincrement()) description String isDone Boolean @default(false) psl=}

这段声明中，entity Task告诉 Wasp 我们要定义一个名为Task的实体（即数据库模型），Wasp 会自动创建一张名为tasks的表；而{=psl ... psl=}是 Wasp 的专属语法——两个psl标签之间的内容会被当作 Prisma Schema Language 来处理。

教程同时点明了底层机制：Wasp 使用 Prisma 作为与数据库对话的桥梁，实体本质上就是 Prisma 数据模型（Prisma model）。你不需要先精通 PSL 就能上手，但了解其结构会非常有帮助。

逐字段理解 Task 模型

上面的 PSL 定义描述了tasks表的三列，官方 Entities 文档（version-0.12 的 Entities 说明）对每个字段做了详细解释：

• id：整型主键。@id将其标记为主键，@default(autoincrement())表示数据库会在插入时自动递增生成，无需手动赋值；
• description：字符串，存放任务的描述文本；
• isDone：布尔值，表示任务是否已完成。@default(false)保证在创建任务时若未显式设置该字段，数据库默认写入false。

waspc 源码中的 PSL 解析

从 waspc（Wasp 编译器，Haskell 编写）的源码结构看，{=psl ... psl=}块的内容由一套完整的 PSL 解析器处理，位于 waspc/src/Wasp/Psl/Parser/ 目录。其中 Model.hs 定义了model解析器，对应model User { id Int @id ... }这类结构，即模型名后跟花括号包裹的字段与块级属性序列。

值得注意的是，Model.hs 中显式枚举了支持的标量类型——String、Boolean、Int、BigInt、Float、Decimal、DateTime、Json等，并注释标明这些类型与 Prisma 官方类型定义一一对应。这解释了为什么教程示例中id Int、description String、isDone Boolean可以直接书写：它们是 waspc 内置认可的 PSL 标量类型，解析器会把它们转换为对应的内部 AST 节点（Psl.Model.String、Psl.Model.Int、Psl.Model.Boolean等），后续再交给 Prisma 生成数据库 DDL。

让数据库结构同步：wasp db migrate-dev

定义实体后，必须让实际数据库的表结构与声明保持一致。教程给出的操作流程是：

1. 如果wasp start进程正在运行，先停止它；
2. 在终端中执行：

wasp db migrate-dev

任何时候修改了实体的定义（增删字段、改类型、加默认值），都需要重新运行这个命令。它的作用是指示 Prisma 创建一份新的数据库迁移脚本（migration），并将其应用到数据库上。

生成的迁移脚本会自动落在项目的migrations/目录下。官方 Entities 文档明确提醒：这个目录应当提交到版本控制系统（git）中，因为迁移脚本是数据库结构演进的完整历史记录。这一点在 Wasp 仓库的示例项目中可以直观看到，例如 kitchen-sink 示例的 migrations 目录 中，每个子目录都以时间戳命名（如20250604115050_uppercase_text_job_request），内含一份.sql迁移文件，根目录还有migration_lock.toml记录锁定的数据库 provider——这正是wasp db migrate-dev反复执行后形成的目录形态。

用 wasp db studio 验证 Task 表

迁移应用成功后，教程建议运行以下命令查看数据库：

wasp db studio

该命令会在浏览器中打开 Prisma 的可视化管理页面，可以查看和编辑数据库中的数据。此时点击Task表，就能看到刚生成的三个字段（id、description、isDone）——虽然此时库里还没有任何数据，但表结构已经就位，为后续教程中的查询和操作（Operations）做好了准备。

官方文档中展示的这一界面截图位于 web/static/img/todo-app-db-studio-task-entity.png，呈现的正是 Db Studio 中Task实体三个字段的状态，与本文流程一一对应。

后续如何使用实体

教程的结尾提示：数据库里还没有数据，但马上就会改变——接下来的章节将定义操作（Operations）来读写Task实体。结合 version-0.12 的 Entities 文档，实体的完整工作流可以归纳为四步：

1. 在.wasp文件中创建或更新实体定义；
2. 运行wasp db migrate-dev同步数据库模型，它通过生成迁移脚本完成同步；
3. 将自动生成的migrations/目录提交进版本控制；
4. 在实现操作（Query 与 Action）时使用 Wasp 的 JavaScript API 访问数据库。

绝大多数场景下，实体都会在 Query 和 Action 这类操作（Operations）的上下文中被使用。如果需要对数据库做更底层的控制，也可以在 Wasp 的服务端代码中直接导入并使用 Prisma Client：

import { prisma } from 'wasp/server' prisma.task.create({ description: "Read the Entities doc", isDone: true // almost :) })

需要注意：Prisma Client 只能在 Wasp 的服务端代码中使用，官方建议优先使用 Wasp 提供的常规机制，仅在 Wasp 没有提供所需能力时才直接使用 Prisma Client。

版本演进：从 {=psl} 内联定义到 schema.prisma

教程示例基于 Wasp 0.12 的写法（app TodoApp { wasp: { version: "^0.12.0" } }），实体直接内联在main.wasp的{=psl ... psl=}块中。值得注意的是，仓库中的最新示例项目已经演进到将数据模型外置到根目录的schema.prisma文件中。例如 TodoAppTs 示例的 schema.prisma：

model Task { id Int @id @default(autoincrement()) description String isDone Boolean @default(false) user User? @relation(fields: [userId], references: [id]) userId Int? }

字段定义与 0.12 教程中的Task实体完全同源（id自增主键、description字符串、isDone默认false），只是扩展了与User的关系字段，并将 datasource 与 generator 配置一并声明在文件中。TodoAppTs 的 main.wasp.ts 中也不再内联 PSL，而是通过query(getTasks, { entities: ["Task"] })等声明把操作与实体关联起来。如果你正在阅读新版 Wasp 文档，这个迁移方向值得了解：实体定义的方式从"内嵌在 wasp 文件里"变成了"独立的 Prisma 模式文件"，但wasp db migrate-dev同步数据库的核心流程不变。

小结

• 实体用entity Task {=psl ... psl=}定义，块内是标准 PSL 语法，由 waspc 的 PSL 解析器（waspc/src/Wasp/Psl/Parser/Model.hs）解析为内部 AST，最终由 Prisma 落成数据库表；
• 每次修改实体定义后必须停止wasp start并运行wasp db migrate-dev生成并应用迁移，migrations/目录需纳入版本控制；
• wasp db studio提供浏览器中的可视化数据管理页面，可用于验证Task表结构；
• 实体主要通过 Query/Action 操作访问，必要时可在服务端代码中直接导入prisma客户端做更底层的操作。

【免费下载链接】waspThe batteries-included full-stack framework for the AI era. Develop JS/TS web apps (React, Node.js, and Prisma) using declarative code that abstracts away complex full-stack features like auth, background jobs, RPC, email sending, end-to-end type safety, single-command deployment, and more.项目地址: https://gitcode.com/GitHub_Trending/wa/wasp