Wasp 数据模型基石全面掌握 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 框架中 Entities实体为核心系统讲解用 Prisma Schema 语言在schema.prisma文件中定义数据库模型这一整套建模流程从 Entity 与 Prisma model 的关系、字段类型与主键设计到wasp db migrate-dev迁移命令、OperationsQueries/Actions中的实体用法再到wasp/entities与wasp/server提供的类型安全 API。读完本文你将能够在 Wasp 项目中独立完成数据模型的定义、迁移、查询与更新并理解其类型系统如何从建模阶段一路保障到运行时。EntityWasp 数据模型的基础在 Wasp 中Entity实体是应用数据模型的基石简单来说一个 Entity 就对应数据库中的一张表。Wasp 没有自创一套建模语法而是直接采用优秀的 Prisma ORM 来实现全部数据库功能并在其上叠加了一层轻量抽象。这意味着你只需要在项目根目录的schema.prisma文件中用 Prisma Schema 语言定义模型Wasp 就能自动识别并接管这些模型。Wasp 项目的根目录结构如下. ├── main.wasp.ts ... ├── package.json ├── public ├── schema.prisma ├── src ├── tsconfig.json ├── tsconfig.src.json ├── tsconfig.wasp.json └── vite.config.tsPrisma Schema 语言是一种专门为定义模型而设计的声明式 DSL语法直观、易于上手下文会通过完整示例讲解无需提前精通它。Entity 与 Prisma model 的关系一个很容易混淆的概念是Wasp Entity与Prisma model是否完全相同在当前版本中在schema.prisma中定义一个 Prismamodel是创建 Wasp Entity 的唯一方式两者一一对应。但 Entity 是 Wasp 层面的更高层抽象Wasp 官方明确表示未来会扩展 Entity 的定义方式和能力。因此可以这样理解——Entity 是 Wasp 的概念model 是 Prisma 的概念现阶段所有 Prisma model 都是 Entity反之亦然但随着 Wasp 的演进二者关系可能继续演化。这一薄抽象层的设计在仓库中也有体现Wasp 直接读取用户项目根目录的 schema.prisma并在此基础上生成类型安全的数据访问代码。定义一个 Entity以 Task 为例假设你要为待办事项应用定义 Task 实体在schema.prisma中写如下模型model Task { id String id default(uuid()) description String isDone Boolean default(false) }这段声明告诉 Wasp创建一张存储任务的tasks表包含三个字段即三个列字段类型说明idString主键。由数据库自动生成随机唯一 IDUUID。descriptionString存储任务描述的字符串。isDoneBoolean任务完成状态。创建时若不显式赋值数据库默认置为false。Prisma 默认把模型名映射为复数表名所以model Task对应tasks表。扩展更多字段类型与主键策略如果你希望使用自增整数主键或更丰富的字段类型可以参考仓库中 kitchen-sink 示例的 schema.prisma。该示例项目Wasp 官方用来覆盖各种功能的厨房水槽演示展示了多种建模模式model User { id Int id default(autoincrement()) address String? tasks Task[] votes TaskVote[] } model Task { id Int id default(autoincrement()) description String isDone Boolean default(false) user User relation(fields: [userId], references: [id]) userId Int votes TaskVote[] visibility TaskVisibility default(PRIVATE) } model TaskVote { id String id default(cuid()) user User relation(fields: [userId], references: [id]) userId Int task Task relation(fields: [taskId], references: [id]) taskId Int }从中可以看到主键策略灵活既可用Int id default(autoincrement())自增整数也可用String id default(uuid())或String id default(cuid())生成随机字符串 ID可选字段String?表示字段可空如用户的address关系建模通过relation(fields: [userId], references: [id])与反向的tasks Task[]建立一对多关系级联查询实体间通过外键字段相互关联后续在查询中可以include关联数据。使用 Entity 类型的类型安全 API定义好模型后Wasp 会自动为每个 Entity 生成对应的 TypeScript 类型你可以从wasp/entities导入使用。例如在服务端函数中import { Task } from wasp/entities const task: Task { ... } // 你也可以定义操作实体类型的函数 function getInfoMessage(task: Task): string { const isDoneText task.isDone ? is done : is not done return Task ${task.description} is ${isDoneText}. }在getInfoMessage中使用Task类型就把参数类型与Task实体绑定在了一起。这种耦合消除了重复定义即使你修改了实体函数签名也会跟着更新——如果改动导致类型不匹配TypeScript 会抛出类型错误而这恰恰是你要的效果在编译期就暴露模型变更带来的影响。Entity 类型在包括客户端代码在内的所有位置都可用import { Task } from wasp/entities export function ExamplePage() { const task: Task { id: some-uuid-1234, description: Some random task, isDone: false, } return div{task.description}/div }同样的类型安全机制在这里也生效修改schema.prisma中的 Task 实体会同步改变导入的Task类型一旦你的任务对象定义过期就会立刻收到类型错误提醒。在仓库的 kitchen-sink 示例中这一用法随处可见例如 queries.ts 和 actions.ts 都通过import { type Task } from wasp/entities获取实体类型并在函数签名中直接引用。在 Operations 中使用 Entities大多数时候你会在OperationsQueries 与 Actions的上下文中使用 Entity。Operations 是 Wasp 中读写数据的机制Queries 负责读取数据Actions 负责修改数据新增或更新。通过 context.entities 访问实体Wasp 会把你在main.wasp.ts或拆分后的*.wasp.ts规格文件中声明的实体注入到 Operation 的context.entities中。以 kitchen-sink 的 queries.ts 为例export const getTasks (async (_args, context) { if (!context.user) { throw new HttpError(401); } const Task context.entities.Task; const tasks await Task.findMany({ where: { user: { id: context.user.id } }, orderBy: { id: asc }, include: { user: { include: { auth: { include: { identities: true } } } }, }, }); return tasks; }) satisfies GetTasksvoid;关键点在于context.entities.Task就是 Prisma Client 的委托模型支持findMany、findUnique、count、create、update等完整 CRUD 方法Wasp 会把 Operation 声明时列出的实体见下文自动装配进context通过include可以按需加载关联数据如任务所属的用户及其认证信息访问控制逻辑如HttpError(401)由你在 Operation 内部自行实现Wasp 不会替你默认拦截。在 main.wasp.ts 中声明实体依赖要让某个 Operation 获得实体访问权必须在 Wasp 规格文件中通过entities选项声明。以 kitchen-sink 的 operations.wasp.ts 为例export const operationsSpec: Spec [ query(getTasks, { entities: [Task] }), query(getNumTasks, { entities: [Task], auth: false }), query(getTask, { entities: [Task] }), action(createTask, { entities: [Task] }), action(updateTaskIsDone, { entities: [Task] }), action(deleteCompletedTasks, { entities: [Task] }), ];entities: [Task]数组中的每个字符串都必须与schema.prisma中的模型名一一对应。声明之后context.entities.Task就会自动可用。同样的机制也适用于 jobs 和 apis例如 jobs.wasp.ts 中的action(requestUppercaseText, { entities: [UppercaseTextRequest] })。使用 Prisma Client 直接操作实体如果 Wasp 提供的机制不足以满足需求例如需要更底层的控制你也可以在服务端代码中直接导入并使用 Prisma Client。它只能用于 Wasp 服务端代码导入方式如下import { prisma } from wasp/server prisma.task.create({ data: { description: Read the Entities doc, isDone: true, }, })注意Prisma Client 不能用于客户端代码但客户端仍可以导入prisma/client来获取类型定义尤其是enum详见 Prisma Schema File 文档。Wasp 官方建议优先使用框架提供的机制即context.entities与 Operations仅当确实需要 Prisma 独有的能力时才直接使用 Prisma Client。在 kitchen-sink 的 crud.ts 中可以看到两种风格的对比——CRUD 操作同样基于context.entities.Task实现并配合satisfies tasks.GetQuery...等类型标注获得端到端类型安全export const crudGetAllTasks (async (args, context) { if (!context.user) { throw new HttpError(401, You must be logged in to view tasks.); } return context.entities.Task.findMany({ where: { user: { id: context.user.id } }, orderBy: { id: desc }, select: { id: true, description: true, user: { include: { auth: true } } }, }); }) satisfies tasks.GetAllQuery{}, {};从模型到数据库wasp db migrate-dev 工作流定义或修改 Entity 后需要把模型同步到数据库。Wasp 提供的标准工作流分为四步在schema.prisma文件中创建/更新 Entity运行wasp db migrate-dev该命令会为数据库与schema.prisma中的 Entity 定义同步生成迁移脚本迁移脚本会自动放置在migrations/目录下务必把该目录提交到版本控制团队协作与生产部署都依赖它在实现 Operations 时使用 Wasp 的 JavaScript API 操作数据库。仓库中每个示例项目都带有真实的迁移目录可供参考例如 kitchen-sink 的 migrations 目录中包含从20230404165422_initial到20251127110727_add_on_after_email_verified_hook_call_count的完整演进历史展示了 Wasp 如何为模型的每一步变更生成 SQL 迁移。schema.prisma 的 Wasp 专属约束虽然 Wasp 大体上允许你像使用普通 Prisma 项目一样书写 schema但存在几条 Wasp 专属规则必须遵守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 中必须存在provider prisma-client-js的 generator 块用于生成可在应用中使用的 Prisma Client 代码你可以按需追加其他 generator。model 块与 enum 块模型块的写法与标准 Prisma 完全一致——只要是合法的 Prisma schema就能在 Wasp 中工作。当应用复杂到需要更精确的领域表达时可以用 Prismaenum。例如把 Task 的布尔isDone升级为三态状态enum TaskStatus { NotStarted Doing Done } model Task { ... state TaskStatus default(NotStarted) }enum 的可用性取决于数据库的兼容性但规则很简单只要 Prisma 支持Wasp 就支持。在服务端代码中可以直接从prisma/client导入 enum 使用import { TaskState } from prisma/client; import { Task } from wasp/entities; import { type GetTasks } from wasp/server/operations; export const getTasks: GetTasksvoid, Task[] async (args, context) { return context.entities.Task.findMany({ orderBy: { id: asc }, where: { NOT: { state: TaskState.Done } }, }); };客户端同样可以导入 enum 做展示判断kitchen-sink 示例的 schema.prisma 中就定义了TaskVisibility与UppercaseTextRequestState两个 enum并在代码中直接引用。注释与预览特性三斜线注释///仅支持放在字段前导位置不支持放在行尾Wasp 官方在 issue #3041 中跟踪该限制Prisma 的预览特性通过 generator 块的previewFeatures启用例如 PostgreSQL 扩展支持postgresqlExtensions可用于pgvector、pg_trgm等场景datasource db { provider postgresql url env(DATABASE_URL) extensions [pgvector(map: vector)] } generator client { provider prisma-client-js previewFeatures [postgresqlExtensions] }更多细节可参考 Wasp 文档的 Prisma Schema File 完整说明。下一步从数据模型走向 Operations现在你已经掌握了如何定义 Wasp Entity——数据模型的核心。接下来需要让这些模型真正发挥作用Wasp 的 OperationsQueries 与 Actions就是围绕 Entities 读写数据的机制Queries 负责读取Actions 负责变更。你可以继续阅读 Operations 概览了解如何在 Operation 中通过context.entities对实体执行 CRUD从而把静态的数据模型转化为可运行的应用逻辑。【免费下载链接】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），仅供参考