协议定义
引言
本文件面向VTJ平台的协议与数据交换规范，系统化梳理项目文件格式、页面文件结构、区块文件规范、物料协议、版本管理与向后兼容策略，并提供协议转换示例、安全与错误处理建议，以及插件开发者与第三方集成的使用指南。目标是帮助读者在不深入源码的情况下，准确理解并正确使用VTJ协议。
项目结构
VTJ协议相关的核心位于@vtj/core包的protocols目录，涵盖共享类型、资产协议、数据模型与序列化约定；同时，项目模型与设计器框架负责协议到运行时的转换与加载。
graph TB
subgraph "协议与模型"
PIndex["protocols/index.ts"]
PSchemas["schemas/*"]
PAssets["assets/*"]
PShared["shared/*"]
end
subgraph "核心导出"
CIndex["@vtj/core/src/index.ts"]
Version["version.ts"]
Constants["constants.ts"]
end
subgraph "模型与运行时"
ModelProject["models/project.ts"]
DesignerAssets["designer/framework/assets.ts"]
end
CIndex --> PIndex
PIndex --> PSchemas
PIndex --> PAssets
PIndex --> PShared
PSchemas --> ModelProject
PAssets --> DesignerAssets
Version --> CIndex
Constants --> CIndex
核心组件
- 协议导出入口：统一导出共享类型、资产协议、数据模式与服务插件，便于上层按需引入。
- 版本与常量：提供核心版本号与内置物料、组件、标签等常量，保障一致性与兼容性。
- 数据模型：ProjectModel承载项目级DSL与文件管理，提供序列化、事件与协作锁机制。
- 设计器资产加载：根据区块来源（Schema/UrlSchema/Plugin）动态获取DSL或物料描述。
架构总览
下图展示了协议层到模型层再到设计器加载的关键交互路径，体现“协议定义—序列化—运行时加载”的闭环。
sequenceDiagram
participant Dev as "开发者"
participant Core as "@vtj/core 协议层"
participant Model as "ProjectModel"
participant Designer as "设计器框架"
participant Provider as "Provider/Service"
Dev->>Core : 引入协议与类型
Core-->>Dev : 导出协议与常量
Dev->>Model : 构造/更新项目模型
Model-->>Dev : 序列化为DSL(JSON)
Dev->>Designer : 传递DSL/文件描述
Designer->>Provider : 按来源获取DSL或物料
Provider-->>Designer : 返回DSL/物料描述
Designer-->>Dev : 渲染与预览
详细组件分析
项目模型与文件协议
- ProjectSchema：项目级DSL根结构，包含平台类型、页面与区块清单、依赖、API与元数据、国际化、环境变量、版本标记与全局标识等。
- PageFile/BlockFile：页面与区块的文件描述，支持目录、布局、隐藏、纯组件、缓存、路由元信息、UniApp专属配置等。
- BlockSchema：区块DSL，包含节点树、状态、生命周期、方法、计算属性、侦听器、样式、属性/事件/插槽定义、数据源与转换缓存等。
- 序列化与事件：ProjectModel提供序列化为DSL的能力，并发出项目变更、页面/区块变更、发布与出码等事件，便于设计器与引擎联动。
classDiagram
class ProjectSchema {
+string id
+string name
+PlatformType platform
+PageFile[] pages
+BlockFile[] blocks
+ApiSchema[] apis
+MetaSchema[] meta
+ProjectConfig config
+UniConfig uniConfig
+GlobalConfig globals
+I18nConfig i18n
+EnvConfig[] env
+string __VERSION__
+string __BASE_PATH__
+string __UID__
}
class PageFile {
+string id
+string name
+string title
+FileType type="page"
+boolean dir
+boolean layout
+string icon
+PageFile[] children
+boolean mask
+boolean hidden
+boolean raw
+boolean pure
+boolean cache
+Record meta
+boolean needLogin
+Record style
}
class BlockFile {
+string id
+string name
+string title
+FileType type="block"
+string category
+MarketInstallInfo market
+string fromType
+boolean preset
+string urls
+string library
+BlockSchema dsl
}
class BlockSchema {
+string id
+string name
+boolean locked
+BlockInject[] inject
+BlockState state
+BlockWatch[] watch
+string css
+string|BlockProp[] props
+string|BlockEmit[] emits
+string[] expose
+string|BlockSlot[] slots
+NodeSchema[] nodes
+string __VERSION__
+string __TEMPLATE_ID__
}
ProjectSchema --> PageFile : "包含"
ProjectSchema --> BlockFile : "包含"
BlockFile --> BlockSchema : "dsl"
BlockFile --> PageFile : "扩展"
物料协议与插件描述
- Material：物料描述，包含版本、名称、库名、分类、组件描述、排序、是否隐藏等。
- MaterialDescription：组件描述，包含名称、别名、父组件、图标、文档、分类、属性、事件、插槽、片段、父子限制、来源、所属包等。
- MaterialProp/MaterialSetter/MaterialEvent/MaterialSlot：属性、设置器、事件、插槽的协议定义。
- 插件示例：apps/plugin/src/material.json展示了属性、事件、插槽与片段的典型配置。
classDiagram
class Material {
+string version
+string name
+string library
+MaterialCategory[] categories
+MaterialDescription[] components
+number order
+boolean hidden
}
class MaterialDescription {
+string name
+string alias
+string parent
+string icon
+string label
+string doc
+number|string categoryId
+MaterialProp[] props
+MaterialEvent[] events
+MaterialSlot[] slots
+Partial~NodeSchema~ snippet
+boolean|string[] parentIncludes
+boolean|string[] childIncludes
+boolean hidden
+NodeFrom from
+string id
+string package
}
class MaterialProp {
+string name
+string label
+string title
+JSONValue defaultValue
+string|MaterialSetter|MaterialSetter[] setters
+string[]|Option[] options
+DataType[] type
}
Material --> MaterialDescription : "components"
MaterialDescription --> MaterialProp : "props"
协议转换与加载流程
- 设计器按来源加载区块：当from.type为Schema/UrlSchema时，从缓存或远端获取DSL；当from.type为Plugin时，加载插件物料并注入组件映射。
- 文件导入/读取：设计器提供文件读取与JSON解析的工具函数，捕获读取与解析错误，保障协议转换的健壮性。
flowchart TD
Start(["开始"]) --> FromType{"区块来源类型"}
FromType --> |Schema| LoadCache["检查缓存/获取DSL"]
FromType --> |UrlSchema| LoadRemote["按URL获取DSL"]
FromType --> |Plugin| LoadPlugin["加载插件物料"]
LoadCache --> Done["返回DSL/物料"]
LoadRemote --> Done
LoadPlugin --> Inject["注入组件映射"] --> Done
Done --> End(["结束"])
版本管理与向后兼容
- 版本号：@vtj/core提供版本号常量，用于标识当前协议版本。
- 升级策略：提供升级版本的工具函数，支持主/次/补丁级升级，确保版本格式为x.y.z。
- 协议标记：项目与区块DSL均包含版本标记字段，便于解析器识别与兼容处理。
flowchart TD
VStart(["当前版本"]) --> Parse["解析为三段式(x.y.z)"]
Parse --> Valid{"格式有效?"}
Valid --> |否| Throw["抛出格式错误"]
Valid --> |是| Upgrade{"升级类型"}
Upgrade --> |major| Major["主版本+1, 次/补丁=0"]
Upgrade --> |minor| Minor["次版本+1, 补丁=0"]
Upgrade --> |patch| Patch["补丁+1"]
Major --> VOut["输出新版本"]
Minor --> VOut
Patch --> VOut
安全性与错误处理
- 文件读取与JSON解析：统一使用异步读取与try/catch捕获，错误信息明确，便于定位问题。
- 编译校验：解析器对脚本与Vue SFC进行编译校验，收集模板与语法错误，提升协议转换质量。
- 权限与协作锁：项目模型提供锁定机制，配合路由守卫与认证系统，防止并发修改。
sequenceDiagram
participant UI as "UI/设计器"
participant FS as "文件系统"
participant Parser as "解析器"
UI->>FS : 读取文件
FS-->>UI : 文本内容
UI->>Parser : JSON.parse/编译校验
Parser-->>UI : 成功/错误信息
UI-->>UI : 错误提示与回退
依赖分析
- 协议导出：@vtj/core统一导出协议与模型，便于上层按需使用。
- 协议内部耦合：协议层内部通过schemas与assets解耦，便于扩展与维护。
- 运行时依赖：设计器框架依赖协议层的DSL与物料描述，结合Provider/Service完成加载与渲染。
graph LR
CoreIndex["@vtj/core/src/index.ts"] --> Protocols["protocols/index.ts"]
Protocols --> Schemas["schemas/*"]
Protocols --> Assets["assets/*"]
Schemas --> Models["models/project.ts"]
Assets --> Designer["designer/framework/assets.ts"]
性能考量
- 缓存策略：设计器对Schema/UrlSchema来源的DSL进行缓存，减少重复请求与解析开销。
- 序列化优化：ProjectModel在序列化时清理不必要的DSL字段，降低存储与传输体积。
- 侦听与计算：BlockSchema的watch/computed需谨慎使用，避免过度计算影响渲染性能。
故障排查指南
- 文件读取失败：检查文件路径与权限，确认读取回调与错误回调均已处理。
- JSON解析错误：核对文件编码与格式，确保为合法JSON；解析异常时查看错误消息定位问题。
- 协议转换错误：使用编译校验工具检查模板与脚本语法，关注错误位置与类型。
- 版本升级异常：确认版本格式为x.y.z，升级类型为major/minor/patch之一。
结论
VTJ协议以@vtj/core为核心，围绕项目与区块DSL、文件协议、物料协议与版本管理形成完整体系。通过序列化与事件驱动，协议在设计器与运行时之间建立稳定桥梁；通过缓存、校验与错误处理机制，保障转换过程的可靠性与可维护性。插件与第三方集成可依据本文档的协议定义与示例，快速完成数据转换与扩展开发。
附录
字段定义与约束速查
- 项目协议（ProjectSchema）
- 关键字段：id、name、platform、pages、blocks、apis、meta、config、uniConfig、globals、i18n、env、VERSION、BASE_PATH、UID
- 约束：platform枚举限定；pages/blocks为数组；i18n包含locale/fallbackLocale/messages；env为键值对数组
- 页面协议（PageFile）
- 关键字段：id、name、title、type="page"、dir、layout、icon、children、mask、hidden、raw、pure、cache、meta、needLogin、style
- 约束：children为PageFile数组；style遵循UniApp pages.json风格
- 区块协议（BlockFile）
- 关键字段：id、name、title、type="block"、category、market、fromType、preset、urls、library、dsl
- 约束：fromType枚举限定；urls在Plugin场景支持多文件
- 区块DSL（BlockSchema）
- 关键字段：id、name、locked、inject、state、lifeCycles、methods、computed、watch、css、props、emits、expose、slots、nodes、dataSources、transform、VERSION、TEMPLATE_ID
- 约束：props/emits/slots支持字符串或对象形式；watch支持深拷贝与立即执行
- 物料协议（Material/MaterialDescription）
- 关键字段：version、name、library、categories、components、order、hidden；components包含props/events/slots/snippet/parentIncludes/childIncludes/from等
- 约束：props支持setter与options；events/slots支持参数列表
协议转换示例（步骤说明）
- 从Schema到DSL：设计器根据BlockFile.fromType选择加载路径，Schema/UrlSchema走缓存或远程获取，Plugin走插件物料加载。
- 从文件到协议：使用文件读取工具读取JSON，解析为协议对象；若失败则记录错误并提示修复。
- 项目序列化：ProjectModel将可序列化属性抽取并清理DSL字段，输出带版本标记的项目DSL。
插件开发者与第三方集成指南
- 插件物料描述：参考apps/plugin/src/material.json，定义属性、事件、插槽与片段，确保setters与options配置完整。
- 协议一致性：严格遵守协议字段与类型，避免自定义扩展破坏向后兼容。
- 版本管理：遵循升级策略，确保版本格式与升级类型正确。
- 错误处理：在读取与解析阶段加入健壮的错误捕获与提示，提升集成稳定性。
参考资料
VTJ.PRO 是一个开源的、AI 驱动的 Vue 3 企业级应用开发平台。它通过 AI 智能体与可视化编排实现高效开发，并支持导出标准 Vue 代码以避免平台锁定。更多信息请访问：
- 📘 官方文档：vtj.pro/
- 🌐 在线平台：app.vtj.pro/
- 📦 开源仓库：gitee.com/newgateway/…
