Wasp 语言.wasp详解用声明式领域特定语言描述全栈 Web 应用【免费下载链接】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 官方文档version-0.13 快照中的《Wasp Language (.wasp)》一文系统讲解 Wasp 语言的声明语法、完整类型系统与领域类型清单并结合 waspc 编译器源码Haskell 实现的 Analyzer 类型系统逐条印证每个语言特性的真实定义帮助你从“会写 .wasp 文件”深入到“理解 Wasp 编译器如何解析、类型检查你的声明”。什么是 Wasp 语言Wasp 语言即你在.wasp文件中编写的代码是一种声明式、静态类型的领域特定语言DSL。它不是通用编程语言而更接近一种配置语言——语法上更接近 JSON、CSS 或 SQL而非 JavaScript 或 Python。这意味着它没有控制流、没有函数定义你只需要“声明”应用的各个组成部分剩下的全栈行为路由、认证、数据库、后台任务等由 Wasp 编译器生成和接管。Wasp 官方文档的态度很务实这门语言足够直观简单到你可以不读这篇语言规范、而是在学习其他功能文档时顺带掌握它但如果你想获得更形式化的定义和对内部工作机制的更深理解就需要理解下面两个核心声明declarations与类型系统。声明DeclarationsWasp 代码的唯一组成单元Wasp 语言的中心概念是声明——Wasp 代码在本质上就是一组声明的集合每个声明描述你 Web 应用的一个部分。文档给出的典型示例app MyApp { title: My app } route RootRoute { path: /, to: DashboardPage } page DashboardPage { component: import { DashboardPage } from src/Dashboard.jsx }这个示例用三个声明描述了一个 Web 应用app MyApp { ... }、route RootRoute { ... }和page DashboardPage { ... }。声明的统一写法为declaration_type declaration_name declaration_body三个组成部分的含义declaration_typeWasp 提供的声明类型之一app、route、page等完整清单见下文领域类型一节declaration_name你为该声明选定的标识符如MyApp也可以叫foobar、foo_bar或hi3Hodeclaration_body声明本身的值/定义其类型必须符合所选声明类型期望的声明体类型declaration body type。以app声明为例拆解声明类型app声明名MyApp声明体{ title: My app }——一个包含字符串值字段title的字典dict该字典类型与app声明类型的声明体类型一致。如果你把title改成littleWasp 编译器会给出类型错误因为它不符合app声明体的期望类型。每个声明都有背后明确的语义描述你的 Web 应用应如何表现与运作。而 Wasp 语言中的其余所有类型——基本类型string、number、复合类型dict、list、枚举类型DbSystem等——全部用于定义声明体。完整类型清单Fundamental 类型与 Domain 类型Wasp 的类型系统分为两大类Fundamental 类型基础类型语言的基本构建块与其他主流语言中的概念相似Domain 类型领域类型这是 Wasp 的独特之处——它们对 Web 应用的概念建模如page、route等。基本类型Primitive types类型字面量示例说明stringfoo、they said: \hi\字符串booltrue、false布尔值number12、14.5数字整数或小数declaration referenceTaskPage、updateTask对已存在声明名称的引用ExtImportimport Foo from src/bar.js、import { Smth } from src/a/b.js外部导入引用src目录下的 JS/TS 模块json{json { a: 5, b: [hi] } json}通过引号器quoter内嵌 JSONpsl{psl psl data model syntax psl}通过引号器内嵌 Prisma Schema Language 数据模型语法其中两个值得展开的要点ExtImport 的约束规则路径必须以src开头其余部分相对于src目录解析导入只允许两种形式默认导入import Foo或单个具名导入import { Foo }。引号器Quoter语法{tag ... tag}形式允许在声明体中内嵌其他语法的文本片段目前支持json和psl两种 tagpsl用于直接嵌入 Prisma 的数据模型定义其语法以 Prisma 官方文档为准。复合类型Composite types类型字面量示例说明dict字典{ a: 5, b: foo }键值对集合字段可必填或可选list列表[1, 2, 3]同元素类型的有序集合tuple元组(1, bar)、(2, 4, true)定长混合类型只允许大小为 2、3、4领域类型Domain types这是 Wasp 区别于普通配置格式的关键全部用于描述 Web 应用概念声明类型declaration typesaction——服务端可被页面调用的操作api——暴露给前端的 HTTP 接口apiNamespace——api 的命名空间分组app——应用根声明标题、认证、数据库、部署等配置都挂在这里entity——数据模型实体与schema.prisma联动job——后台任务page——页面绑定 React 组件与路由目标query——服务端只读查询route——URL 路由crud——为实体一键生成增删改查能力枚举类型enum typesDbSystem——数据库系统如 Postgres、SqliteHttpMethod——HTTP 方法JobExecutor——任务执行器EmailProvider——邮件发送提供方每种领域类型的声明体类型与业务含义在 Wasp 文档对应功能章节中逐一展开如 认证 各声明的 body 说明。源码印证类型系统如何落地在 waspc 编译器中以上类型清单并非纸面定义它们与 waspcWasp 编译器Haskell 源码一一对应。原文档标注的“source of truth”在当前仓库中即以下两个文件。类型 ADT所有 Wasp 类型的形式化定义waspc/src/Wasp/Analyzer/Type.hs 定义了全部可能类型的代数数据类型data Type DeclType String -- 声明类型如 app、page | EnumType String -- 枚举类型如 HttpMethod | DictType (H.HashMap String DictEntryType) -- 字典字段可必填/可选 | ListType Type | EmptyListType -- 空列表的临时类型 | TupleType (Type, Type, [Type]) -- 元组固定前两个 可选剩余 | StringType | NumberType | BoolType | ExtImportType | QuoterType String -- {tag ... tag} 引号器几处源码细节直接印证了文档描述元组大小限制TupleType (Type, Type, [Type])的构造形态恰好对应文档中“元组只允许大小为 2、3、4”的规则——前两个元素固定存在第三个之后的剩余类型通过[Type]列表表达至多再容纳两个字典字段的必填/可选区分DictEntryType 分为DictRequired与DictOptional两种这解释了为何app声明体必须提供title而auth、db等字段可以省略——app声明体中不同字段的强制性正是由这一结构决定的EmptyListType是内部机制源码注释说明空列表在类型检查期间被赋予临时类型待typeCheck完成后统一替换为具体ListType属于编译器内部细节对用户透明。领域类型清单stdTypes 注入机制waspc/src/Wasp/Analyzer/StdTypeDefinitions.hs 通过stdTypes集中注册全部标准领域类型stdTypes :: TD.TypeDefinitions stdTypes TD.addDeclType App $ TD.addEnumType DeploymentMode $ TD.addDeclType Entity $ TD.addDeclType Page $ TD.addDeclType Route $ TD.addDeclType Query $ TD.addDeclType Action $ TD.addEnumType JobExecutor $ TD.addDeclType Job $ TD.addEnumType HttpMethod $ TD.addDeclType Api $ TD.addDeclType ApiNamespace $ TD.addEnumType EmailProvider $ TD.addDeclType Crud $ TD.empty源码注释明确说明这些领域类型是**以注入方式而非硬编码进 Analyzer**提供给编译器的目的是让修改和维护 Wasp 语言本身更容易。对照文档的类型清单两者的声明类型action、api、apiNamespace、app、entity、job、page、query、route、crud与枚举类型完全吻合。从源码结构看当前主干还多出一个未在 version-0.13 文档枚举中列出的DeploymentMode枚举用于app声明中的部署配置这体现了文档快照与主干演进之间的正常差异——阅读本文结论时应以文档快照对应的 Wasp 版本行为为准。声明体的真实字段以app和page为例文档提到app声明体是“一个包含title字段字符串值的字典”。而编译器侧的App记录waspc/src/Wasp/AppSpec/App.hs完整呈现了该声明体在类型检查通过后的形态data App App { wasp :: Wasp, -- 声明自身的元数据名字、源位置 title :: String, -- 必填对应文档示例中的 { title: My app } deployment :: Maybe Deployment, head :: Maybe [String], auth :: Maybe Auth, server :: Maybe Server, client :: Maybe Client, db :: Maybe Db, emailSender :: Maybe EmailSender, webSocket :: Maybe WebSocket }title :: String是必填项其余字段均为Maybe——与Type.hs中DictRequired/DictOptional的区分精确对应。这也解释了文档中“把title改成little会报类型错误”的原因title是app字典类型中唯一的必填字段。同理waspc/src/Wasp/AppSpec/Page.hs 表明page声明体只有两个字段data Page Page { component :: ExtImport, -- 必填且必须是 ExtImport 类型 authRequired :: Maybe Bool }component字段类型是ExtImport——这从类型层面印证了 ExtImport 的独立地位它不是普通 string而是专门用于引用src目录下 JS/TS 模块的原始类型编译器据此校验src前缀与“默认导入或单个具名导入”两条规则。声明的编译流水线从 .wasp 文本到类型检查Wasp 声明从文本到语义的完整处理链路在 Analyzer 模块说明 中有一张流水线图即本文开头的 Analyzer 图.wasp文件先由 Parser 解析为 AST再进入类型检查器完成声明体类型校验。README 特别指出了一个容易忽略的环节在 Parser 与 TypeChecker 之间还有一个基于解析后的schema.prisma文件注入entity声明的步骤——也就是说entity类声明并非直接写在.wasp文件里而是由编译器从 Prisma schema 派生并注入这也是psl引号器类型存在的意义所在。小结与延伸阅读掌握declaration_type declaration_name declaration_body三要素、基本类型含 ExtImport 与 json/psl 引号器以及领域类型清单就覆盖了 Wasp 语言的完整语法面语言规范以官方文档为准本文引用的版本快照位于 web/versioned_docs/version-0.13/general/language.md各类型的“source of truth”源码位于 waspc/src/Wasp/Analyzer/Type.hs 与 waspc/src/Wasp/Analyzer/StdTypeDefinitions.hs每种声明类型action、query、api、job、crud 等的声明体字段与行为语义建议在 Wasp 文档对应功能章节中结合本文的类型系统视角继续阅读。【免费下载链接】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 语言（.wasp）详解：用声明式领域特定语言描述全栈 Web 应用
Wasp 语言.wasp详解用声明式领域特定语言描述全栈 Web 应用【免费下载链接】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 官方文档version-0.13 快照中的《Wasp Language (.wasp)》一文系统讲解 Wasp 语言的声明语法、完整类型系统与领域类型清单并结合 waspc 编译器源码Haskell 实现的 Analyzer 类型系统逐条印证每个语言特性的真实定义帮助你从“会写 .wasp 文件”深入到“理解 Wasp 编译器如何解析、类型检查你的声明”。什么是 Wasp 语言Wasp 语言即你在.wasp文件中编写的代码是一种声明式、静态类型的领域特定语言DSL。它不是通用编程语言而更接近一种配置语言——语法上更接近 JSON、CSS 或 SQL而非 JavaScript 或 Python。这意味着它没有控制流、没有函数定义你只需要“声明”应用的各个组成部分剩下的全栈行为路由、认证、数据库、后台任务等由 Wasp 编译器生成和接管。Wasp 官方文档的态度很务实这门语言足够直观简单到你可以不读这篇语言规范、而是在学习其他功能文档时顺带掌握它但如果你想获得更形式化的定义和对内部工作机制的更深理解就需要理解下面两个核心声明declarations与类型系统。声明DeclarationsWasp 代码的唯一组成单元Wasp 语言的中心概念是声明——Wasp 代码在本质上就是一组声明的集合每个声明描述你 Web 应用的一个部分。文档给出的典型示例app MyApp { title: My app } route RootRoute { path: /, to: DashboardPage } page DashboardPage { component: import { DashboardPage } from src/Dashboard.jsx }这个示例用三个声明描述了一个 Web 应用app MyApp { ... }、route RootRoute { ... }和page DashboardPage { ... }。声明的统一写法为declaration_type declaration_name declaration_body三个组成部分的含义declaration_typeWasp 提供的声明类型之一app、route、page等完整清单见下文领域类型一节declaration_name你为该声明选定的标识符如MyApp也可以叫foobar、foo_bar或hi3Hodeclaration_body声明本身的值/定义其类型必须符合所选声明类型期望的声明体类型declaration body type。以app声明为例拆解声明类型app声明名MyApp声明体{ title: My app }——一个包含字符串值字段title的字典dict该字典类型与app声明类型的声明体类型一致。如果你把title改成littleWasp 编译器会给出类型错误因为它不符合app声明体的期望类型。每个声明都有背后明确的语义描述你的 Web 应用应如何表现与运作。而 Wasp 语言中的其余所有类型——基本类型string、number、复合类型dict、list、枚举类型DbSystem等——全部用于定义声明体。完整类型清单Fundamental 类型与 Domain 类型Wasp 的类型系统分为两大类Fundamental 类型基础类型语言的基本构建块与其他主流语言中的概念相似Domain 类型领域类型这是 Wasp 的独特之处——它们对 Web 应用的概念建模如page、route等。基本类型Primitive types类型字面量示例说明stringfoo、they said: \hi\字符串booltrue、false布尔值number12、14.5数字整数或小数declaration referenceTaskPage、updateTask对已存在声明名称的引用ExtImportimport Foo from src/bar.js、import { Smth } from src/a/b.js外部导入引用src目录下的 JS/TS 模块json{json { a: 5, b: [hi] } json}通过引号器quoter内嵌 JSONpsl{psl psl data model syntax psl}通过引号器内嵌 Prisma Schema Language 数据模型语法其中两个值得展开的要点ExtImport 的约束规则路径必须以src开头其余部分相对于src目录解析导入只允许两种形式默认导入import Foo或单个具名导入import { Foo }。引号器Quoter语法{tag ... tag}形式允许在声明体中内嵌其他语法的文本片段目前支持json和psl两种 tagpsl用于直接嵌入 Prisma 的数据模型定义其语法以 Prisma 官方文档为准。复合类型Composite types类型字面量示例说明dict字典{ a: 5, b: foo }键值对集合字段可必填或可选list列表[1, 2, 3]同元素类型的有序集合tuple元组(1, bar)、(2, 4, true)定长混合类型只允许大小为 2、3、4领域类型Domain types这是 Wasp 区别于普通配置格式的关键全部用于描述 Web 应用概念声明类型declaration typesaction——服务端可被页面调用的操作api——暴露给前端的 HTTP 接口apiNamespace——api 的命名空间分组app——应用根声明标题、认证、数据库、部署等配置都挂在这里entity——数据模型实体与schema.prisma联动job——后台任务page——页面绑定 React 组件与路由目标query——服务端只读查询route——URL 路由crud——为实体一键生成增删改查能力枚举类型enum typesDbSystem——数据库系统如 Postgres、SqliteHttpMethod——HTTP 方法JobExecutor——任务执行器EmailProvider——邮件发送提供方每种领域类型的声明体类型与业务含义在 Wasp 文档对应功能章节中逐一展开如 认证 各声明的 body 说明。源码印证类型系统如何落地在 waspc 编译器中以上类型清单并非纸面定义它们与 waspcWasp 编译器Haskell 源码一一对应。原文档标注的“source of truth”在当前仓库中即以下两个文件。类型 ADT所有 Wasp 类型的形式化定义waspc/src/Wasp/Analyzer/Type.hs 定义了全部可能类型的代数数据类型data Type DeclType String -- 声明类型如 app、page | EnumType String -- 枚举类型如 HttpMethod | DictType (H.HashMap String DictEntryType) -- 字典字段可必填/可选 | ListType Type | EmptyListType -- 空列表的临时类型 | TupleType (Type, Type, [Type]) -- 元组固定前两个 可选剩余 | StringType | NumberType | BoolType | ExtImportType | QuoterType String -- {tag ... tag} 引号器几处源码细节直接印证了文档描述元组大小限制TupleType (Type, Type, [Type])的构造形态恰好对应文档中“元组只允许大小为 2、3、4”的规则——前两个元素固定存在第三个之后的剩余类型通过[Type]列表表达至多再容纳两个字典字段的必填/可选区分DictEntryType 分为DictRequired与DictOptional两种这解释了为何app声明体必须提供title而auth、db等字段可以省略——app声明体中不同字段的强制性正是由这一结构决定的EmptyListType是内部机制源码注释说明空列表在类型检查期间被赋予临时类型待typeCheck完成后统一替换为具体ListType属于编译器内部细节对用户透明。领域类型清单stdTypes 注入机制waspc/src/Wasp/Analyzer/StdTypeDefinitions.hs 通过stdTypes集中注册全部标准领域类型stdTypes :: TD.TypeDefinitions stdTypes TD.addDeclType App $ TD.addEnumType DeploymentMode $ TD.addDeclType Entity $ TD.addDeclType Page $ TD.addDeclType Route $ TD.addDeclType Query $ TD.addDeclType Action $ TD.addEnumType JobExecutor $ TD.addDeclType Job $ TD.addEnumType HttpMethod $ TD.addDeclType Api $ TD.addDeclType ApiNamespace $ TD.addEnumType EmailProvider $ TD.addDeclType Crud $ TD.empty源码注释明确说明这些领域类型是**以注入方式而非硬编码进 Analyzer**提供给编译器的目的是让修改和维护 Wasp 语言本身更容易。对照文档的类型清单两者的声明类型action、api、apiNamespace、app、entity、job、page、query、route、crud与枚举类型完全吻合。从源码结构看当前主干还多出一个未在 version-0.13 文档枚举中列出的DeploymentMode枚举用于app声明中的部署配置这体现了文档快照与主干演进之间的正常差异——阅读本文结论时应以文档快照对应的 Wasp 版本行为为准。声明体的真实字段以app和page为例文档提到app声明体是“一个包含title字段字符串值的字典”。而编译器侧的App记录waspc/src/Wasp/AppSpec/App.hs完整呈现了该声明体在类型检查通过后的形态data App App { wasp :: Wasp, -- 声明自身的元数据名字、源位置 title :: String, -- 必填对应文档示例中的 { title: My app } deployment :: Maybe Deployment, head :: Maybe [String], auth :: Maybe Auth, server :: Maybe Server, client :: Maybe Client, db :: Maybe Db, emailSender :: Maybe EmailSender, webSocket :: Maybe WebSocket }title :: String是必填项其余字段均为Maybe——与Type.hs中DictRequired/DictOptional的区分精确对应。这也解释了文档中“把title改成little会报类型错误”的原因title是app字典类型中唯一的必填字段。同理waspc/src/Wasp/AppSpec/Page.hs 表明page声明体只有两个字段data Page Page { component :: ExtImport, -- 必填且必须是 ExtImport 类型 authRequired :: Maybe Bool }component字段类型是ExtImport——这从类型层面印证了 ExtImport 的独立地位它不是普通 string而是专门用于引用src目录下 JS/TS 模块的原始类型编译器据此校验src前缀与“默认导入或单个具名导入”两条规则。声明的编译流水线从 .wasp 文本到类型检查Wasp 声明从文本到语义的完整处理链路在 Analyzer 模块说明 中有一张流水线图即本文开头的 Analyzer 图.wasp文件先由 Parser 解析为 AST再进入类型检查器完成声明体类型校验。README 特别指出了一个容易忽略的环节在 Parser 与 TypeChecker 之间还有一个基于解析后的schema.prisma文件注入entity声明的步骤——也就是说entity类声明并非直接写在.wasp文件里而是由编译器从 Prisma schema 派生并注入这也是psl引号器类型存在的意义所在。小结与延伸阅读掌握declaration_type declaration_name declaration_body三要素、基本类型含 ExtImport 与 json/psl 引号器以及领域类型清单就覆盖了 Wasp 语言的完整语法面语言规范以官方文档为准本文引用的版本快照位于 web/versioned_docs/version-0.13/general/language.md各类型的“source of truth”源码位于 waspc/src/Wasp/Analyzer/Type.hs 与 waspc/src/Wasp/Analyzer/StdTypeDefinitions.hs每种声明类型action、query、api、job、crud 等的声明体字段与行为语义建议在 Wasp 文档对应功能章节中结合本文的类型系统视角继续阅读。【免费下载链接】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），仅供参考