VTJ：DSL语言规范

引言

本文件面向VTJ平台的DSL（领域特定语言）规范，系统阐述其设计目标、语法规则与数据结构定义，覆盖项目文件（ProjectSchema）、页面文件（PageFile）、区块文件（BlockFile）以及节点数据结构（NodeSchema）。同时，说明DSL与Vue代码之间的双向转换机制、序列化与反序列化流程，给出字段说明、最佳实践与版本兼容性管理策略，帮助开发者在保持数据一致性与可维护性的前提下高效构建低代码应用。

项目结构

VTJ的DSL以"协议定义 + 模型实现 + 解析器 + 渲染器"的分层架构组织：

• 协议层：定义DSL的强类型接口（ProjectSchema、BlockSchema、NodeSchema等），确保跨模块契约稳定。
• 模型层：NodeModel、BlockModel等封装DSL的读写、变更与序列化逻辑，提供事件驱动与状态管理能力。
• 解析层：parseVue将Vue单文件组件（SFC）解析为DSL（BlockSchema），并补全函数体与依赖映射。
• 渲染层：Provider负责加载DSL、解析依赖并创建渲染器，支持按ID或URL加载外部DSL。

graph TB subgraph "协议层" P["ProjectSchema 接口"] B["BlockSchema 接口"] N["NodeSchema 接口"] F["File 接口(PageFile/BlockFile)"] end subgraph "模型层" PM["ProjectModel"] BM["BlockModel"] NM["NodeModel"] PR["PropModel"] EV["EventModel"] DR["DirectiveModel"] end subgraph "解析层" PV["parseVue 解析器"] end subgraph "渲染层" RP["Provider 渲染器"] end P --> PM B --> BM N --> NM F --> PM PM --> BM BM --> NM NM --> PR NM --> EV NM --> DR PV --> BM BM --> RP

核心组件

• 项目模型（ProjectModel）：管理页面与区块的增删改查、事件通知与序列化；支持页面克隆、保存为区块、区块创建与更新等操作。
• 区块模型（BlockModel）：承载DSL的结构化状态（state/computed/watch/methods/lifeCycles等）、节点树与数据源，支持节点移动、克隆、锁定等操作。
• 节点模型（NodeModel）：封装节点属性（PropModel）、事件（EventModel）、指令（DirectiveModel）的读写与序列化，支持层级关系与可见性/锁定控制。
• 解析器（parseVue）：将Vue SFC解析为BlockSchema，遍历DSL中的表达式并进行代码补丁与格式化，最终输出DSL。
• 渲染器（Provider）：根据DSL创建渲染器实例，支持按ID与URL加载外部DSL，统一管理组件库与API。

架构总览

DSL在VTJ中的流转路径如下：

• 设计器侧：通过设计器操作生成/更新DSL，支持手动编辑与保存。
• 解析侧：Vue源码经解析器转换为BlockSchema，补全函数体与依赖映射。
• 模型侧：BlockModel/NodeModel负责DSL的读写、变更与序列化。
• 渲染侧：Provider加载DSL并创建渲染器，支持远程DSL加载与缓存。

sequenceDiagram participant Dev as "设计器" participant Parser as "解析器(parseVue)" participant Model as "模型(BlockModel/NodeModel)" participant Provider as "渲染器(Provider)" Dev->>Parser : "提交Vue源码" Parser->>Parser : "解析SFC/脚本/样式/模板" Parser->>Model : "构造BlockSchema并转为模型" Model-->>Dev : "toDsl() 输出DSL(JSON)" Dev->>Provider : "传入DSL创建渲染器" Provider->>Provider : "加载依赖/按ID/URL获取DSL" Provider-->>Dev : "返回渲染器实例"

详细组件分析

项目文件（ProjectSchema）与文件系统（PageFile/BlockFile）

• ProjectSchema：描述项目的整体元数据、页面与区块集合、依赖、全局配置、国际化与环境变量等。
• PageFile：页面文件，支持目录结构、布局、缓存、隐藏、raw/pure等特性。
• BlockFile：区块文件，支持Schema/UrlSchema/Plugin三种来源，可挂载到项目中复用。

classDiagram class ProjectSchema { +string id +string name +PlatformType platform +PageFile[] pages +BlockFile[] blocks +Dependencies[] dependencies +ApiSchema[] apis +MetaSchema[] meta +ProjectConfig config +UniConfig uniConfig +GlobalConfig globals +I18nConfig i18n +EnvConfig[] env } class PageFile { +string id +string name +string title +FileType type="page" +boolean dir +PageFile[] children +BlockSchema dsl +boolean raw +boolean pure +boolean hidden +boolean layout +boolean cache +Record meta } class BlockFile { +string id +string name +string title +FileType type="block" +string fromType +string urls +string library +BlockSchema dsl } ProjectSchema --> PageFile : "包含" ProjectSchema --> BlockFile : "包含"

区块文件（BlockFile）与区块DSL（BlockSchema）

• BlockSchema：描述区块的结构化状态（state/computed/watch/methods/lifeCycles）、节点树、数据源、props/emits/expose/slots、注入与CSS等。
• BlockModel：提供toDsl()序列化、节点增删改移动、状态/函数/注入/插槽/数据源管理等能力。

节点DSL（NodeSchema）与模型（NodeModel）

• NodeSchema：描述节点的标识、名称、来源、可见性/锁定、属性、事件、指令、子节点与插槽等。
• NodeModel：封装属性（PropModel）、事件（EventModel）、指令（DirectiveModel）的读写与序列化，支持层级关系与可见性/锁定控制。

classDiagram class NodeSchema { +string id +string name +NodeFrom from +boolean locked +boolean invisible +NodeProps props +NodeEvents events +NodeDirective[] directives +NodeChildren children +string|NodeSlot slot } class NodeModel { +toDsl() NodeSchema +update(schema) +setChildren(children) +setSlot(slot) +setProp(name,value,defaultValue) +setEvent(event) +setDirective(dir) +appendChild(node) +insertBefore(node) +insertAfter(node) +movePrev()/moveNext() +lock()/unlock() +setVisible(visible) +dispose() } class PropModel { +setValue(value) +getValue() +static toDsl(props) +static parse(props) } class EventModel { +update(schema) +static toDsl(events) +static parse(events) } class DirectiveModel { +update(schema) +static toDsl(directives) +static parse(directives) } NodeModel --> NodeSchema : "序列化" NodeModel --> PropModel : "属性管理" NodeModel --> EventModel : "事件管理" NodeModel --> DirectiveModel : "指令管理"

DSL与Vue代码的双向转换机制

• 解析流程：parseVue解析SFC，提取样式、脚本与模板，生成BlockSchema，遍历DSL中的表达式进行格式化与补丁，最终输出DSL。
• 反序列化/渲染：Provider根据DSL创建渲染器，支持按ID与URL加载外部DSL，统一管理组件库与API。

sequenceDiagram participant Vue as "Vue源码(SFC)" participant Parser as "parseVue" participant DSL as "BlockSchema" participant Model as "BlockModel/NodeModel" participant Renderer as "Provider.createDslRenderer" Vue->>Parser : "输入源码" Parser->>Parser : "解析模板/脚本/样式" Parser->>DSL : "组装BlockSchema" Parser->>Parser : "遍历表达式并补丁" Parser-->>Model : "new BlockModel(dsl)" Model-->>DSL : "toDsl()" DSL->>Renderer : "传入createDslRenderer" Renderer-->>Renderer : "加载依赖/按ID/URL获取DSL"

序列化与反序列化流程

• ProjectModel.toDsl：清理页面DSL，输出项目级DSL，包含版本与标识。
• BlockModel.toDsl：序列化区块DSL，包含版本戳与节点树。
• NodeModel.toDsl：序列化节点DSL，包含属性、事件与指令。

flowchart TD Start(["开始"]) --> Clean["清理页面DSL(移除设计架构)"] Clean --> Build["构建ProjectSchema对象"] Build --> AddFlags["添加项目标识与版本"] AddFlags --> ReturnProj["返回ProjectSchema"] subgraph "区块序列化" BStart["BlockModel.toDsl"] --> BAttrs["收集正常属性"] BAttrs --> BNodes["递归序列化节点树"] BNodes --> BVersion["设置版本戳"] BVersion --> BReturn["返回BlockSchema"] end

语法示例与字段说明（概览）

• ProjectSchema关键字段：平台、页面集合、区块集合、依赖、全局配置、国际化、环境变量等。
• BlockSchema关键字段：状态、计算属性、侦听器、方法、生命周期、注入、暴露、插槽、节点树、数据源、CSS等。
• NodeSchema关键字段：标识、名称、来源、可见性/锁定、属性、事件、指令、子节点、插槽等。
• PageFile/BlockFile关键字段：类型、来源类型（Schema/UrlSchema/Plugin）、资源URL、库名、DSL等。

最佳实践

• 使用BlockModel/NodeModel提供的setter方法管理状态与节点，避免直接修改底层DSL导致的不一致。
• 在设计器中启用事件通知，确保变更传播至渲染器与持久化层。
• 对表达式进行统一格式化与补丁，减少运行时错误。
• 区块与页面的fromType选择应明确来源，便于后续加载与维护。
• 使用版本戳与标识字段保证序列化一致性与可追溯性。

依赖分析

• 协议层接口为上层提供稳定的契约，模型层基于协议实现具体行为。
• 解析器依赖协议与模型，将Vue源码转换为DSL。
• 渲染器依赖模型与协议，负责加载与渲染DSL。
• 设计器通过SchemaWidget展示DSL并支持手动编辑与保存。

graph LR Proto["协议接口(Node/Block/Project/File)"] --> Model["模型(Node/Block/Project)"] Model --> Parser["解析器(parseVue)"] Parser --> DSL["BlockSchema/NodeSchema"] DSL --> Provider["渲染器(Provider)"] Designer["设计器(SchemaWidget)"] --> Model Designer --> Provider

性能考虑

• 表达式遍历与格式化：解析器对DSL中的表达式进行统一格式化与补丁，建议在批量处理时采用异步遍历，避免阻塞UI线程。
• 事件通知：模型层通过事件系统通知变更，建议在批量更新时使用静默模式（silent）减少事件风暴。
• 渲染器加载：Provider支持按ID与URL加载DSL并带缓存，建议合理利用缓存降低重复请求。
• 序列化清理：ProjectModel在序列化时清理页面DSL，避免冗余数据影响传输与存储。

故障排除指南

• 手动编辑DSL风险提示：设计器SchemaWidget在保存时会弹窗确认，避免因手动修改导致页面无法加载。
• 解析错误：parseVue在编译校验失败或样式解析错误时会返回错误列表，需根据错误定位修复。
• 运行时加载失败：Provider在按URL加载DSL失败时会返回空，需检查网络与服务端响应。

结论

VTJ的DSL通过协议层定义清晰的数据契约，结合模型层的读写与序列化能力、解析器的双向转换机制以及渲染器的动态加载，形成了从设计到运行的完整闭环。遵循本文档的字段说明、最佳实践与版本管理策略，可在保证数据一致性与可维护性的前提下，高效构建与演进低代码应用。

附录

• 设计器渲染示例：设计器中通过createRenderer创建渲染器，支持传入DSL与组件库。
• 项目与区块模型文档：涵盖文件类型系统、事件驱动架构与序列化格式。

参考资料

VTJ.PRO 是一个开源的、AI 驱动的 Vue 3 企业级应用开发平台。它通过 AI 智能体与可视化编排实现高效开发，并支持导出标准 Vue 代码以避免平台锁定。更多信息请访问：

• 📘 官方文档：vtj.pro/
• 🌐 在线平台：app.vtj.pro/
• 📦 开源仓库：gitee.com/newgateway/...