Wasp 语言.wasp DSL深入解析声明式配置语言与类型系统全指南【免费下载链接】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/waspWasp本仓库 waspc 编译器与 web 文档所描述的全栈框架的核心创新之一就是它的领域专用语言DSL——.wasp文件。本文以官方文档 language.md 为主体结合仓库中 Type.hs、StdTypeDefinitions.hs、TypeChecker/Internal.hs 等编译源码系统讲解 Wasp 语言的声明语法、完整类型清单以及它在编译管线中的真实处理流程。读完本文你将掌握.wasp文件的写法规范、每种基础类型与领域类型的使用场景并能理解一段 Wasp 声明从源码到类型检查再到代码生成的完整链路。一、Wasp 语言是什么面向全栈的声明式 DSLWasp 语言是你在.wasp文件中书写的内容它是一门声明式declarative、静态类型statically typed的领域专用语言DSL。它不是通用编程语言而更像一种配置语言它更接近 JSON、CSS 或 SQL而不是 JavaScript 或 Python。这意味着你用它来描述一个 Web 应用长什么样、有哪些部分、各部分如何连接而不是逐行编写如何实现的命令式逻辑。实现细节如鉴权、RPC、后台任务、数据库迁移等由 Wasp 编译器负责翻译成真实的 React Node.js Prisma 代码。Wasp 语言非常容易上手可学的真的不多事实上大多数开发者可以在不阅读本页的情况下通过其他文档边用边学但如果你想要更形式化的定义和对底层机制更深的理解本文就是为你准备的。 提示Wasp TS 配置早期预览特性如果你愿意也可以用 TS 来定义 Wasp 配置即使用 main.wasp.tsWasp TS 配置 替代main.wasp文件。这一可选路径在仓库源码中也有体现waspc/src/Wasp/Analyzer.hs的模块注释明确指出历史上负责解析.waspDSL 源码的解析器已被移除转而采用分析 TypeScript 配置文件的方案而原有的类型系统机制Analyzer.TypeChecker、Analyzer.Evaluator、Analyzer.TypeDefinitions被复用。因此本文讲解的声明语法与类型规则无论是.wasp还是 TS 配置方式其背后的类型模型都是一致的。二、声明DeclarationsWasp 语言的绝对核心Wasp 语言的中心是声明declaration。一段 Wasp 代码归根结底就是一堆声明每个声明描述你 Web 应用的一个组成部分。来看官方文档给出的最经典示例app MyApp { title: My app } route RootRoute { path: /, to: DashboardPage } page DashboardPage { component: import { DashboardPage } from src/Dashboard.jsx }上面的例子通过三条声明描述了一个 Web 应用声明作用app MyApp { ... }声明应用本身及其全局配置这里设置了页面标题titleroute RootRoute { ... }声明一条路由路径/指向DashboardPage页面page DashboardPage { ... }声明一个页面其 React 组件从src/Dashboard.jsx导入2.1 声明的通用语法书写声明的语法统一为declaration_type declaration_name declaration_body三个组成部分的含义分别是declaration_typeWasp 提供的声明类型之一例如app、route、page、query、action、job等完整清单见下文领域类型一节。declaration_name由你自行选择的标识符用来命名这条声明。例如上面用MyApp你也可以用foobar、foo_bar或hi3Ho等任何合法标识符。declaration_body声明本身的值/定义其结构必须匹配该声明类型所期望的声明体类型declaration body type。以上面的app声明为例声明类型是app声明名称是MyApp换成任何其他合法标识符都可以声明体是{ title: My app }——一个包含字段title字符串值的字典dict。2.2 类型不匹配会怎样字典的类型必须与app声明类型所要求的声明体类型保持一致。如果提供了别的东西比如把title的值改成little一个不存在的字段名而非合法字段Wasp 编译器就会抛出类型错误type error因为这与app声明体所期望的类型不符。这个类型检查行为在编译器中是真实存在的强制环节在 TypeChecker/Internal.hs 中checkStmt会先查找声明的类型定义lookupDeclType若该声明类型不存在则抛出NoDeclarationType错误随后对声明体表达式做类型推断inferExprType再用checkIsSubTypeOf判断其是否为期望类型的子类型失败则抛出CoercionError。也就是说你的每一条 Wasp 声明在编译期都会经过严格的类型校验。每条声明背后都承载着明确的语义描述了你的 Web 应用应如何行为与运转。而 Wasp 语言中所有其他类型原始类型如string、number复合类型如dict、list枚举类型如DbSystem等其存在的意义都是用来定义这些声明体的。三、Wasp 类型系统全景图Wasp 的类型系统可划分为两大类别基础类型fundamental types与领域类型domain types。基础类型是语言的基本构建块与主流语言中看到的类型非常相似领域类型才是 Wasp 的特别之处——它们建模了 Web 应用的概念如page、route等。3.1 基础类型Fundamental Types基础类型的事实来源source of truth是 waspc/src/Wasp/Analyzer/Type.hs。在源码中Type这个 Haskell 数据类型完整定义了 Wasp 的全部类型data Type DeclType String | EnumType String | DictType (H.HashMap String DictEntryType) | ListType Type | EmptyListType | TupleType (Type, Type, [Type]) | StringType | NumberType | BoolType | ExtImportType | QuoterType String其中DictEntryType又区分了必填字段DictRequired与可选字段DictOptional由dictEntryRequired判断这正是声明体内哪些字段可以省略的类型依据。原始类型Primitive Types类型写法示例说明stringfoo、they said: \hi\字符串字面量支持转义booltrue、false布尔值number12、14.5数字支持整数与小数declaration reference声明引用TaskPage、updateTask引用一条已存在的声明的名称ExtImport外部导入import Foo from src/bar.js、import { Smth } from src/a/b.js从src目录导入代码见下方规则json{json { a: 5, b: [hi] } json}用引号quoter包裹的 JSON 片段ExtImport 的硬性规则官方文档明确规定源码 TypeChecker/Internal.hs 中P.ExtImport n s分支也对其做类型化处理路径必须以src开头其余部分相对src目录解析导入必须是默认导入import Foo或单一命名导入import { Foo }。json 引号Quoter在类型检查器中json与psl两种引号标签目前是硬编码的P.Quoter json对应 JSON、P.Quoter psl对应 Prisma Schema使用其他标签会抛出QuoterUnknownTag错误——这与文档中{json ... json}的语法完全对应。复合类型Composite Types类型写法示例说明dict字典{ a: 5, b: foo }键值对集合键唯一list列表[1, 2, 3]元素类型统一的列表tuple元组(1, bar)、(2, 4, true)定长元组只支持 2、3、4 元列表的类型推断有一个值得注意的边界情况空列表[]因为缺少元素信息而无法确定类型编译器会先赋予它临时的EmptyListType对应源码Type.EmptyListType待类型检查完成后所有出现处都会被替换为合适的ListType。类型检查器中列表类型是其元素类型的统一unify结果字典则会在类型化过程中检查是否存在重复键insertIfUniqueElseThrow重复键直接报错。3.2 领域类型Domain Types领域类型的事实来源是 waspc/src/Wasp/Analyzer/StdTypeDefinitions.hs。该文件通过makeDeclType/makeEnumType两个模板宏把Wasp.AppSpec中的 Haskell 数据类型逐一注册为语言领域类型。从源码看标准类型集合stdTypes依次注册了App、DeploymentMode、Entity、Page、Route、Query、Action、JobExecutor、Job、HttpMethod、Api、ApiNamespace、EmailProvider、Crud——这与官方文档的清单完全吻合且比文档多暴露了一个DeploymentMode枚举用于部署方式配置。声明类型Declaration Types这些声明类型就是你在.wasp文件中可以书写声明时的declaration_type取值声明类型语义app应用根声明配置全局属性如title、auth、db等action定义可写操作mutation如创建、更新、删除数据query定义只读数据查询与 Prisma 实体联动page定义前端页面关联 React 组件route定义页面路由path与tocrud一键声明对某个实体的全套 CRUD 操作job声明后台任务可指定执行器api声明自定义 HTTP API 端点指定 HTTP 方法apiNamespace对一组api端点进行命名空间分组枚举类型Enum Types枚举典型取值含义DbSystem数据库系统选择如 SQLite、PostgreSQLHttpMethodHTTP 方法GET、POST 等供api使用JobExecutor后台任务执行器如 PgBossEmailProvider邮件发送服务商schema.prisma中的模型你可以在.wasp文件中直接引用schema.prisma里定义的模型只需使用模型名即可例如Task。这是因为在分析阶段编译器会把 Prisma schema 解析出的实体声明注入到 AST 中见 Analyzer/README.md 的说明在 Parser 与 TypeChecker 之间还缺少一步根据解析后的schema.prisma注入Entity声明。在 Analyzer.hs 中getEntityDecls正是通过parseEntityStatements把 Prisma schema 转成实体声明、再走类型检查与求值得到实体列表的。关于每个领域类型的更详细说明其声明体类型与语义可分别查阅本仓库 web/docs 中对应的功能文档页。四、从源码看 Wasp 声明的编译管线理解了类型之后我们再从仓库源码看一条 Wasp 声明是如何被加工成最终代码的。分析器Analyzer的处理流程如文首架构图所示可概括为四个阶段Parser将 Wasp 源码解析为Parser.AST抽象语法树。TypeChecker对Parser.AST进行类型检查产出带类型信息的TypeChecker.AST。Evaluator将类型化后的 AST 求值产出声明列表[Decl]。Generator基于[Decl]生成最终的应用代码React/Node/Prisma。对应到代码上类型检查TypeCheckerTypeChecker/Internal.hs 的模块注释揭示了两个阶段——先是声明提升Hoisting Declarations把每条声明语句绑定的名字注册到环境中例如app Todo { ... }会创建绑定(Todo, DeclType app)此时不做类型检查然后是语句类型检查逐条校验声明参数是否符合该声明类型的要求。类型推断规则集中在inferExprType、unify、unifyTypes、checkIsSubTypeOf四个函数中。求值EvaluatorEvaluator.hs 中的evaluate接收类型检查后的 AST逐条执行TD.dtEvaluate即该声明类型对应的求值逻辑最终输出[Decl]声明列表并按照声明名存入绑定表。正是这套声明提升 → 类型检查 → 求值的机制保证了你在.wasp文件中写的每一条声明既静态可验证又能被翻译成真实可运行的代码。这也是 Wasp 号称用声明式代码抽象掉鉴权、后台任务、RPC、邮件发送等复杂全栈特性的底层基石。五、小结与进阶阅读总结一下本文的核心要点Wasp 语言是一门声明式、静态类型的 DSL本质是配置语言语法与 JSON/CSS/SQL 更接近语言的绝对核心是声明语法为declaration_type declaration_name declaration_body类型不匹配会在编译期报错类型系统分基础类型string、bool、number、声明引用、ExtImport、json以及 dict、list、tuple 复合类型与领域类型app、page、route、query、action、job、api、apiNamespace、crud 等声明类型以及 DbSystem、HttpMethod、JobExecutor、EmailProvider 等枚举外加schema.prisma模型引用一条声明从书写到生效会经历Parser → TypeChecker → Evaluator → Generator的完整编译管线。若想继续深入推荐按需阅读本仓库中的以下资源官方版本文档web/versioned_docs/version-0.15/general/language.md类型系统事实来源源码waspc/src/Wasp/Analyzer/Type.hs领域类型定义源码waspc/src/Wasp/Analyzer/StdTypeDefinitions.hs类型检查实现源码waspc/src/Wasp/Analyzer/TypeChecker/Internal.hs求值器实现源码waspc/src/Wasp/Analyzer/Evaluator.hs分析器总览与架构图说明waspc/src/Wasp/Analyzer/README.md【免费下载链接】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），仅供参考