Wasp 数据模型入门v0.13Entity 实体定义、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/waspEntity实体是 Wasp 应用数据模型的地基一个 Entity 就对应数据库中的一个数据模型。本文基于 Wasp v0.13 版本文档 entities.md 展开完整覆盖实体的声明语法{psl ... psl}内嵌 Prisma Schema Language、wasp db migrate-dev迁移工作流、通过 Operations 与 Prisma Client 访问实体的两种方式并结合编译器源码Haskell 实现的 PSL 解析器与实体 AST解释 Wasp 是如何理解你的实体定义、识别主键并支撑自动 CRUD 的。1. Entity 与 PrismaWasp 数据层的底座Wasp 用 Prisma ORM 实现全部数据库功能并在其上覆盖一层薄薄的抽象。核心关系是Wasp Entity 与 Prisma 的数据模型data model一一对应。这带来三个直接结论你不需要先精通 Prisma。Wasp 为 Prisma 的核心能力封装了简单 APIOperations、CRUD 等绝大多数场景不用直接接触 Prisma Client 即可读写数据。定义实体的唯一前置技能是 PSLPrisma Schema Language——Prisma 专门用于声明式定义模型的简单语言。PSL 声明式且直白读到下文示例就能上手无需提前系统学习。数据库能力的边界由 Prisma 决定。需要 Wasp 没有封装的高级能力复杂事务、原始查询等时可以“降级”直接拿 Prisma Client这在 v0.13 中是被官方认可的路径。2. 定义一个 Entityentity Task的完整解剖entity声明即数据库模型声明。以最常见的Task任务为例v0.13 中在项目的.wasp文件如main.wasp中这样写entity Task {psl id Int id default(autoincrement()) description String isDone Boolean default(false) psl}逐条拆解这份声明entity Task告诉 Wasp 我们要定义一个名为Task的实体即数据库模型。Wasp 会自动创建名为tasks复数小写的表这一点在后续 Operations 路由生成中同样生效详见第 5 节源码佐证。{psl ... psl}Wasp 把两个psl标记之间的内容当作PSLPrisma Schema Language处理。也就是说实体定义 Wasp 的entity外壳 原生的 Prisma 模型字段语法Prisma 的属性attribute语义在这里完整保留。上面的 PSL 定义了tasks表的三列字段类型属性含义idIntid default(autoincrement())主键整型。数据库自动生成在上一行自增 1descriptionString无任务描述普通字符串列isDoneBooleandefault(false)完成状态布尔列。创建时不显式设置数据库默认置false几个可以直接复用的 PSL 要点id标记主键字段——Wasp 编译器对它的识别逻辑有源码级证据见第 5 节default(...)提供列级默认值支持autoincrement()、false、now()、uuid()等 Prisma 默认值表达式字段名、类型与 Prisma 保持原样Int、String、Boolean、DateTime、Float、Json等因此你已有的 Prisma 建模经验可以平移过来。一个现实项目里实体长什么样可以参考仓库中示例应用 kitchen-sink 的数据模型 schema.prisma注意该示例属于采用新版schema.prisma文件定义方式的仓库字段语法与 v0.13 内嵌 PSL 完全同构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) }可以看到除单列字段外模型中还出现了关联relation、反向关系列表TaskVote[]与枚举默认值default(PRIVATE)——这些全部是标准 PSL定义方式与Task三字段示例一脉相承。3. 从定义到建表四步工作流定义实体只是第一步v0.13 文档给出的完整落地流程是在.wasp文件中创建/更新实体——即上节的entity声明。运行wasp db migrate-dev。该命令负责把数据库与.wasp文件中的实体定义同步起来实现方式是生成迁移脚本migration scripts它对比目标模型与当前库产出描述差异的 SQL 迁移。迁移脚本会自动落在migrations/目录务必将该目录提交进版本控制——迁移历史是团队协作与部署的基础。在实现 Operations 时用 Wasp 的 JavaScript API 操作数据库——即 Query/Actionv0.13 文档将此留给了 operations 章节。关于第 2、3 步有两条实践边界数据库连接是前提。wasp db migrate-dev需要可连的数据库migrations/目录里每个迁移带时间戳前缀如20231124161113_initial与.sql文件可参考 migrations 目录 与其中的 migration_lock.toml锁定 Prisma 迁移引擎方言。切换数据库系统后必须重新迁移。v0.13 支持 SQLite默认与 PostgreSQL生产部署需 PostgreSQL由于迁移脚本与方言绑定切换系统后要删除旧migrations/并重新wasp db migrate-dev参见同版本 Databases 文档 的 “Migrating from SQLite to PostgreSQL” 一节。4. 使用实体Operations 优先Prisma Client 兜底4.1 在 Operations 中使用实体推荐路径绝大多数时候实体是在OperationsQuery Action的上下文中被使用的——Query 读、Action 写且带有权限public/private语义。v0.13 文档将细节放在了 operations/overview 与 crud。这一路径背后的机制在编译器中可以直接看到实体含其主键字段会被转换成 CRUD 元数据进而生成crud/entityLower/get、crud/tasks/get-all、crud/tasks/create等标准路由。源码测试 CrudTest.hs 固化了这份元数据的确切形状[ name . crudOperationsName, -- tasks operations . object operations, entitiesArray . ([Task] :: String), idFieldName . (id :: String), entityLower . (task :: String), entityUpper . (Task :: String) ]idFieldName来自实体的主键字段entityLower/entityUpper即第 2 节提到的自动复数/单数表名规则的直接体现你只需要声明entity TaskOperations 路由、参数命名都由编译器派生。4.2 直接使用 Prisma Client需要更多控制时当 Wasp 封装的能力不够复杂查询、原生 SQL、特殊事务语义等可以绕过 Operations直接 import Prisma Client。官方建议仍是优先走 Wasp 机制仅在需要 Wasp 未提供的特性时才直接操作 Prisma Client。限制条件Prisma Client 只能在 Wasp 的服务端代码中使用Action、Job、server-only 模块等客户端代码不可用。用法import { prisma } from wasp/server prisma.task.create({ description: Read the Entities doc, isDone: true // almost :) })注意prisma.task——实体模型名Task在这里变为 Prisma Client 上的小驼峰代理task与表名tasks、entityLower: task的命名链完全一致见 4.1 的元数据。TypeScript 版本代码相同类型由生成的 Prisma Client 提供。5. 源码视角Wasp 如何解析你的实体定义结合仓库中 v0.13 编译器Haskellwaspc包的源码结构可以看清entity声明从文本到数据库动作的完整链路1PSL 被当作一等语法解析。Wasp 自带一套 Prisma Schema Language 的 AST、解析器与代码生成器模块布局见 wasp-cli 的 Psl 源码目录Psl/Ast/Model.hs定义了模型 ASTdata Model Model Name Body data Field Field { _name :: String, _type :: FieldType, _typeModifiers :: [FieldTypeModifier], _attrs :: [Attribute] }对照第 2 节的示例id Int id default(autoincrement())会被解析为Field {_name id, _type Int, _attrs [id, default(autoincrement())]}。内置字段类型由 FieldType 枚举覆盖String、Boolean、Int、BigInt、Float、Decimal、DateTime、Json、Bytes另支持UserType关联到其他模型与Unsupported兜底未知类型FieldTypeModifier 则对应[]列表与?可选修饰符。这意味着 v0.13 对实体内部的字段类型、属性做了完整结构化理解而不是简单的字符串透传。2Entity 是一等 AppSpec 构件。Entity.hs 将实体建模为“包裹 PSL 模型体的 newtype”并提供getFields、getIdField等访问器newtype Entity Entity { pslModelBody :: Psl.Model.Body }3主键识别有明确的判定规则。Psl/Util.hs 中findIdField的判定条件就是“字段带有id属性”源码注释原文We define an ID field as a field that has the id attribute同时findIdBlockAttribute支持id复合主键块属性。这个识别结果正是 4.1 中 CRUD 元数据idFieldName字段的来源也解释了为什么每个实体必须有一个可定位的主键——它是 Operations/CRUD 生成按主键读取、更新、删除逻辑的依据。4一个版本演进注记。从源码结构看Entity 的 JSON 反序列化已被有意废弃Entity.hs 的FromJSON直接返回失败信息“entities are now defined via prisma.schema file”。也就是说在 Wasp 后续版本中实体定义从.wasp内嵌 PSL 迁移到了独立的schema.prisma文件当前主干的 examples 各示例 均已如此。阅读 v0.13 文档时请以“entity {psl ... psl}”为准升级后只需把同一份 PSL 内容移入schema.prisma的model块字段与属性语法不变。6. 小结定义entity Task {psl ... psl} Wasp 外壳 原生 PSL表名自动取复数tasksid标记主键default给出列默认值。落库wasp db migrate-dev生成迁移脚本并写入migrations/提交它换数据库系统需删库重建迁移。使用首选 OperationsQuery/Action底层由编译器从实体元数据主键、单复数名派生 CRUD 路由需要细粒度控制时在服务端import { prisma } from wasp/server直接操作 Prisma Client。原理Wasp 编译器对 PSL 做了完整 AST 级解析Psl/Ast/Model.hs并按id/id规则识别主键Psl/Util.hs这是 Operations 与自动 CRUD 能够按实体生成的基础。完成实体定义之后下一步自然是学习如何用 Operations 高效地读写它们继续阅读 v0.13 版 Operations 总览 与 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），仅供参考
Wasp 数据模型入门（v0.13）：Entity 实体定义、Prisma 映射与直接操作指南
Wasp 数据模型入门v0.13Entity 实体定义、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/waspEntity实体是 Wasp 应用数据模型的地基一个 Entity 就对应数据库中的一个数据模型。本文基于 Wasp v0.13 版本文档 entities.md 展开完整覆盖实体的声明语法{psl ... psl}内嵌 Prisma Schema Language、wasp db migrate-dev迁移工作流、通过 Operations 与 Prisma Client 访问实体的两种方式并结合编译器源码Haskell 实现的 PSL 解析器与实体 AST解释 Wasp 是如何理解你的实体定义、识别主键并支撑自动 CRUD 的。1. Entity 与 PrismaWasp 数据层的底座Wasp 用 Prisma ORM 实现全部数据库功能并在其上覆盖一层薄薄的抽象。核心关系是Wasp Entity 与 Prisma 的数据模型data model一一对应。这带来三个直接结论你不需要先精通 Prisma。Wasp 为 Prisma 的核心能力封装了简单 APIOperations、CRUD 等绝大多数场景不用直接接触 Prisma Client 即可读写数据。定义实体的唯一前置技能是 PSLPrisma Schema Language——Prisma 专门用于声明式定义模型的简单语言。PSL 声明式且直白读到下文示例就能上手无需提前系统学习。数据库能力的边界由 Prisma 决定。需要 Wasp 没有封装的高级能力复杂事务、原始查询等时可以“降级”直接拿 Prisma Client这在 v0.13 中是被官方认可的路径。2. 定义一个 Entityentity Task的完整解剖entity声明即数据库模型声明。以最常见的Task任务为例v0.13 中在项目的.wasp文件如main.wasp中这样写entity Task {psl id Int id default(autoincrement()) description String isDone Boolean default(false) psl}逐条拆解这份声明entity Task告诉 Wasp 我们要定义一个名为Task的实体即数据库模型。Wasp 会自动创建名为tasks复数小写的表这一点在后续 Operations 路由生成中同样生效详见第 5 节源码佐证。{psl ... psl}Wasp 把两个psl标记之间的内容当作PSLPrisma Schema Language处理。也就是说实体定义 Wasp 的entity外壳 原生的 Prisma 模型字段语法Prisma 的属性attribute语义在这里完整保留。上面的 PSL 定义了tasks表的三列字段类型属性含义idIntid default(autoincrement())主键整型。数据库自动生成在上一行自增 1descriptionString无任务描述普通字符串列isDoneBooleandefault(false)完成状态布尔列。创建时不显式设置数据库默认置false几个可以直接复用的 PSL 要点id标记主键字段——Wasp 编译器对它的识别逻辑有源码级证据见第 5 节default(...)提供列级默认值支持autoincrement()、false、now()、uuid()等 Prisma 默认值表达式字段名、类型与 Prisma 保持原样Int、String、Boolean、DateTime、Float、Json等因此你已有的 Prisma 建模经验可以平移过来。一个现实项目里实体长什么样可以参考仓库中示例应用 kitchen-sink 的数据模型 schema.prisma注意该示例属于采用新版schema.prisma文件定义方式的仓库字段语法与 v0.13 内嵌 PSL 完全同构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) }可以看到除单列字段外模型中还出现了关联relation、反向关系列表TaskVote[]与枚举默认值default(PRIVATE)——这些全部是标准 PSL定义方式与Task三字段示例一脉相承。3. 从定义到建表四步工作流定义实体只是第一步v0.13 文档给出的完整落地流程是在.wasp文件中创建/更新实体——即上节的entity声明。运行wasp db migrate-dev。该命令负责把数据库与.wasp文件中的实体定义同步起来实现方式是生成迁移脚本migration scripts它对比目标模型与当前库产出描述差异的 SQL 迁移。迁移脚本会自动落在migrations/目录务必将该目录提交进版本控制——迁移历史是团队协作与部署的基础。在实现 Operations 时用 Wasp 的 JavaScript API 操作数据库——即 Query/Actionv0.13 文档将此留给了 operations 章节。关于第 2、3 步有两条实践边界数据库连接是前提。wasp db migrate-dev需要可连的数据库migrations/目录里每个迁移带时间戳前缀如20231124161113_initial与.sql文件可参考 migrations 目录 与其中的 migration_lock.toml锁定 Prisma 迁移引擎方言。切换数据库系统后必须重新迁移。v0.13 支持 SQLite默认与 PostgreSQL生产部署需 PostgreSQL由于迁移脚本与方言绑定切换系统后要删除旧migrations/并重新wasp db migrate-dev参见同版本 Databases 文档 的 “Migrating from SQLite to PostgreSQL” 一节。4. 使用实体Operations 优先Prisma Client 兜底4.1 在 Operations 中使用实体推荐路径绝大多数时候实体是在OperationsQuery Action的上下文中被使用的——Query 读、Action 写且带有权限public/private语义。v0.13 文档将细节放在了 operations/overview 与 crud。这一路径背后的机制在编译器中可以直接看到实体含其主键字段会被转换成 CRUD 元数据进而生成crud/entityLower/get、crud/tasks/get-all、crud/tasks/create等标准路由。源码测试 CrudTest.hs 固化了这份元数据的确切形状[ name . crudOperationsName, -- tasks operations . object operations, entitiesArray . ([Task] :: String), idFieldName . (id :: String), entityLower . (task :: String), entityUpper . (Task :: String) ]idFieldName来自实体的主键字段entityLower/entityUpper即第 2 节提到的自动复数/单数表名规则的直接体现你只需要声明entity TaskOperations 路由、参数命名都由编译器派生。4.2 直接使用 Prisma Client需要更多控制时当 Wasp 封装的能力不够复杂查询、原生 SQL、特殊事务语义等可以绕过 Operations直接 import Prisma Client。官方建议仍是优先走 Wasp 机制仅在需要 Wasp 未提供的特性时才直接操作 Prisma Client。限制条件Prisma Client 只能在 Wasp 的服务端代码中使用Action、Job、server-only 模块等客户端代码不可用。用法import { prisma } from wasp/server prisma.task.create({ description: Read the Entities doc, isDone: true // almost :) })注意prisma.task——实体模型名Task在这里变为 Prisma Client 上的小驼峰代理task与表名tasks、entityLower: task的命名链完全一致见 4.1 的元数据。TypeScript 版本代码相同类型由生成的 Prisma Client 提供。5. 源码视角Wasp 如何解析你的实体定义结合仓库中 v0.13 编译器Haskellwaspc包的源码结构可以看清entity声明从文本到数据库动作的完整链路1PSL 被当作一等语法解析。Wasp 自带一套 Prisma Schema Language 的 AST、解析器与代码生成器模块布局见 wasp-cli 的 Psl 源码目录Psl/Ast/Model.hs定义了模型 ASTdata Model Model Name Body data Field Field { _name :: String, _type :: FieldType, _typeModifiers :: [FieldTypeModifier], _attrs :: [Attribute] }对照第 2 节的示例id Int id default(autoincrement())会被解析为Field {_name id, _type Int, _attrs [id, default(autoincrement())]}。内置字段类型由 FieldType 枚举覆盖String、Boolean、Int、BigInt、Float、Decimal、DateTime、Json、Bytes另支持UserType关联到其他模型与Unsupported兜底未知类型FieldTypeModifier 则对应[]列表与?可选修饰符。这意味着 v0.13 对实体内部的字段类型、属性做了完整结构化理解而不是简单的字符串透传。2Entity 是一等 AppSpec 构件。Entity.hs 将实体建模为“包裹 PSL 模型体的 newtype”并提供getFields、getIdField等访问器newtype Entity Entity { pslModelBody :: Psl.Model.Body }3主键识别有明确的判定规则。Psl/Util.hs 中findIdField的判定条件就是“字段带有id属性”源码注释原文We define an ID field as a field that has the id attribute同时findIdBlockAttribute支持id复合主键块属性。这个识别结果正是 4.1 中 CRUD 元数据idFieldName字段的来源也解释了为什么每个实体必须有一个可定位的主键——它是 Operations/CRUD 生成按主键读取、更新、删除逻辑的依据。4一个版本演进注记。从源码结构看Entity 的 JSON 反序列化已被有意废弃Entity.hs 的FromJSON直接返回失败信息“entities are now defined via prisma.schema file”。也就是说在 Wasp 后续版本中实体定义从.wasp内嵌 PSL 迁移到了独立的schema.prisma文件当前主干的 examples 各示例 均已如此。阅读 v0.13 文档时请以“entity {psl ... psl}”为准升级后只需把同一份 PSL 内容移入schema.prisma的model块字段与属性语法不变。6. 小结定义entity Task {psl ... psl} Wasp 外壳 原生 PSL表名自动取复数tasksid标记主键default给出列默认值。落库wasp db migrate-dev生成迁移脚本并写入migrations/提交它换数据库系统需删库重建迁移。使用首选 OperationsQuery/Action底层由编译器从实体元数据主键、单复数名派生 CRUD 路由需要细粒度控制时在服务端import { prisma } from wasp/server直接操作 Prisma Client。原理Wasp 编译器对 PSL 做了完整 AST 级解析Psl/Ast/Model.hs并按id/id规则识别主键Psl/Util.hs这是 Operations 与自动 CRUD 能够按实体生成的基础。完成实体定义之后下一步自然是学习如何用 Operations 高效地读写它们继续阅读 v0.13 版 Operations 总览 与 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），仅供参考