Wasp 0.14 数据库实体Entity实战用 schema.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本篇是 Wasp 官方 Todo 应用教程的第 4 步对应web/versioned_docs/version-0.14/tutorial/04-entities.md。你将理解 Entity 在 Wasp 中的核心地位学会在schema.prisma中声明数据模型并通过wasp db migrate-dev生成迁移、用wasp db studio可视化查看数据库。读完本文你将掌握定义 Entity → 同步数据库 → 在代码中读写数据的完整闭环为后续编写 Queries 与 Actions 打下数据基础。Entity 是 Wasp 数据模型的第一公民在 Wasp 中Entity 是定义数据库里存什么的方式也是全栈开发中最基础、最重要的概念之一。Wasp 本身并不自研数据库访问层而是直接使用 Prisma ORM 与数据库交互并用一层薄薄的抽象将其嵌入 Wasp 的声明式体系中。因此定义 Entity 的方式就是在schema.prisma文件中定义 Prisma model。关于 Entity 与数据库的关系Entities 文档 的定位非常明确Entity 是你的应用数据模型的根基简而言之一个 Entity 就对应数据库中的一张表、一条 Prisma model 声明。Entity 与 Prisma model两个层次的概念虽然当前一个 Prisma model 就是一个 Wasp Entity两者看起来是同一回事但官方文档特别区分了两个概念详见 Entities 文档 中的 Entity vs Model 说明Wasp Entity是 Wasp 层面更高层的抽象概念Wasp 计划在未来扩展其定义方式和能力Prisma model是 Prisma 层面的概念目前是创建 Entity 的唯一途径。可以这样理解现阶段两者一一对应但随着 Wasp 演进这种关系可能会发展变化。第一步在 schema.prisma 中定义 Task Entityschema.prisma位于项目根目录与main.wasp声明文件同级在 0.14 的项目结构里它紧挨着src/、public/、tsconfig.json等文件当前仓库中 TodoApp 示例的对应文件是 examples/tutorials/TodoAppTs/schema.prisma。既然我们的 Todo 应用核心是任务Task教程要求我们向schema.prisma追加一个Taskmodel// ... model Task { id Int id default(autoincrement()) description String isDone Boolean default(false) }这段声明式的 Prisma Schema Language 代码会让 Wasp 创建一张存储任务的数据表。三个字段分别对应表中的三列字段类型约束含义idIntid default(autoincrement())主键数据库自动生成的自增整数唯一标识每条任务descriptionString—存储任务的文字描述isDoneBooleandefault(false)任务完成状态创建任务时若不指定数据库默认写入false教程对应的补丁文件 web/docs/tutorial/patches/04-entities__prisma-task.patch 展示了这一步的精确 diff仅在已有的datasource db与generator client块之后追加上述 model 即可其余内容保持不变。提示在真实仓库的 TodoApp 示例中随着教程推进到鉴权章节Task最终会与User建立一对多关系user User? relation(...)与userId Int?见 examples/tutorials/TodoAppTs/schema.prisma。当前这一步我们只需要最简单的三个字段。第二步用 wasp db migrate-dev 同步数据库修改 Entity 定义之后数据库本身并不会自动更新。教程给出的标准流程是如果wasp start正在运行先停止它在项目根目录执行wasp db migrate-dev每次修改 Entity 定义后都需要重新运行该命令。它的作用是让 Prisma 对比schema.prisma中的模型与当前数据库状态生成一个新的迁移脚本migration并立即应用到数据库。迁移产物与版本控制迁移脚本会被自动放到项目根目录的migrations/文件夹中。以仓库中的 TodoApp 示例为例定义 Task 后生成的初始迁移位于 examples/tutorials/TodoAppTs/migrations/20240716142600_initial/migration.sql其内容正是我们定义的三个字段-- CreateTable CREATE TABLE Task ( id INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT, description TEXT NOT NULL, isDone BOOLEAN NOT NULL DEFAULT false );请务必把migrations/目录提交进版本控制——它是团队协作时数据库 schema 演进的唯一权威记录也是其他成员或 CI/CD 环境能够重建相同数据库结构的依据。第三步用 wasp db studio 可视化查看数据想直观地看到数据库和新建的Taskentity运行wasp db studio它会在浏览器中打开一个新的 Prisma Studio 页面供你查看和编辑数据库中的数据。点击左侧的Taskentity即可看到id、description、isDone三个字段。此时数据库还没有任何数据但接下来的教程步骤很快就会往里面写入内容。深入原理Wasp 如何读取 schema.prismaWasp 会读取项目根目录的schema.prisma从中提取数据库配置与所有 model 定义再据此生成与数据库交互所需的代码。虽然你可以像在任何 JS/TS 项目中一样使用 Prisma schema但 Wasp 对其中几个块有特定要求详见 Prisma Schema File 文档datasource块datasource db { provider postgresql url env(DATABASE_URL) }provider目前只允许postgresql或sqlite因为 Wasp 仅支持这两种数据库url必须设置为env(DATABASE_URL)Wasp 依赖这个环境变量与你的数据库正确连接。generator块generator client { provider prisma-client-js }Wasp 要求schema.prisma中必须存在一个provider prisma-client-js的 generator 块用于生成可在应用中使用的 Prisma Client 代码你还可以按需添加额外的 generator。model与enum块model块的写法没有额外限制只要是合法的 Prisma schema 代码Wasp 都能识别并自动把其中每个 model 当作一个 Entityenum块同样受支持。例如把布尔型的isDone升级为NotStarted / Doing / Done三种状态的任务枚举时可以直接在 schema 中定义 Prisma enum并在 model 中引用。如果某个特性在 Prisma 层面可用那么在 Wasp 中同样可用。Entity 对应的 TypeScript 类型wasp/entities定义好 Entity 后Wasp 会自动为它生成对应的 TypeScript 类型可以从wasp/entities导入使用import { Task } from wasp/entities const task: Task { ... } // 你也可以为 Entity 编写辅助函数 function getInfoMessage(task: Task): string { const isDoneText task.isDone ? is done : is not done return Task ${task.description} is ${isDoneText}. }这种类型与 Entity 绑定的机制带来两层收益消除重复函数参数与数据库模型共用同一类型不需要手动维护两套定义变更即报错当你修改schema.prisma中的 Entity 时导入的Task类型随之变化凡是使用旧结构的代码都会立刻产生类型错误——这正是类型系统希望我们尽早暴露问题的方式。Entity 类型在客户端代码中同样可用例如在 React 组件里构造任务对象import { Task } from wasp/entities export function ExamplePage() { const task: Task { id: 123, description: Some random task, isDone: false, } return div{task.description}/div }在代码中读写 Entity 的两种方式推荐方式通过 Operations 使用绝大多数场景下你会在OperationsQueries 与 Actions的上下文中操作 Entity详见 Operations 总览。Query 负责读取数据Action 负责创建、修改、删除数据。当你在 Wasp 声明文件0.14 中为main.wasp中把某个 Operation 与entities: [Task]关联后Wasp 会把对应的 Prisma client 以context.entities.Task的形式注入到 Operation 函数中实现类型安全的数据访问。这也是下一个教程步骤编写getTasksQuery将要演示的内容。直接方式使用 Prisma Client如果你需要更细粒度的控制也可以绕过 Operations直接导入并使用 Prisma Client。注意Prisma Client 只能在 Wasp 服务端代码中使用导入方式如下import { prisma } from wasp/server prisma.task.create({ description: Read the Entities doc, isDone: true // almost :) })官方建议优先使用 Wasp 提供的标准机制只有当 Wasp 没有覆盖到某个特性时才退回到直接使用 Prisma Client。另外客户端代码虽然不能使用 Prisma Client 执行数据库操作但可以导入它来获取类型定义尤其是 Prismaenum。小结与下一步至此我们已经完成了 Entity 的完整闭环在schema.prisma中定义Taskmodel运行wasp db migrate-dev生成迁移并同步数据库migrations/记得提交版本控制用wasp db studio直观检查表结构与数据通过wasp/entities拿到与 Entity 绑定的类型在服务端/客户端安全地使用它。下一步我们将基于这个TaskEntity 编写Queries 与 Actions真正把数据用起来——届时你会看到context.entities.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考