Open API 与外部集成

OpenModule 作为 VTJ.PRO 平台对外暴露的 API 接口层，负责 VTJ IDE 客户端（工作台）、第三方集成与核心后端服务之间的通信。它提供了用于基于令牌的认证、DSL 转换、AI 代理桥接以及资源管理的专用端点。

OpenModule 架构

OpenModule 被构建为一个标准的 NestJS 模块，它聚合了来自业务层的多个服务，并通过 OpenController 将它们暴露出来。

数据流与组件交互

下图说明了 OpenController 如何与核心及业务服务交互，以满足外部请求。

外部 API 交互映射

认证与安全

外部访问采用基于令牌的机制进行安全保护。OpenController 提供了一个登录端点，返回一个访问令牌，该令牌必须包含在后续请求的请求头中。

• 登录逻辑：OpenService 中的 login 方法通过 UserService 验证用户凭据，然后通过 AuthService 生成一个 JWT。
• 令牌验证：OpenController 中的大多数端点都受到守卫（guard）或内部检查的保护，这些检查会验证 Authorization 请求头。

主要 API 功能

1. DSL 转换与检索

Open API 为 VTJ IDE 提供了专用的端点，用于检索应用模式（DSL）。这涉及将数据库实体转换为 @vtj/core 期望的格式。

• getDsl：检索特定应用或文件的 DSL。它利用 DslService 从 DslEntity 获取数据。
• saveDsl：允许 IDE 将更改持久化回服务器。它处理版本控制，并区分 dev 和 prod 环境。

2. AI 代理聊天桥接

OpenModule 充当 AI 交互的代理，特别是针对低代码助手。

• chat：一个桥接到 AIService 的端点。它支持流式响应，以便在 IDE 中实时提供代码生成建议。
• 提示词处理：它将上下文特定信息（例如当前 DSL 状态）传递给 AIService，以确保大语言模型拥有生成准确代码所需的元数据。

3. 模板发布

第三方开发者或高级用户可以通过 Open API 将本地项目作为平台模板发布。

• publishTemplate：该函数接收项目负载，进行验证，并调用 TemplateService 来创建新的 TemplateEntity。

4. OSS 与文件管理

该 API 提供对对象存储服务（OSS）的受控访问，用于上传低代码项目中使用的资源（图片、图标）。

• upload：封装 OssService，处理文件的多部分上传，并返回一个公开的 URL。

实现细节：OpenService

OpenService 类封装了外部集成的业务逻辑。

方法	角色	目标实体/服务
login	对外部客户端进行认证	AuthService, UserEntity
getApp	获取应用元数据	LowcodeAppService, AppEntity
getDsl	检索 DSL 模式	DslService, DslEntity
saveDsl	更新 DSL 模式	DslService
publish	触发项目部署	DslService.publishFromDev
chat	代理 AI 请求	AIService

代码实体映射

下图展示了逻辑 API 函数与代码库中具体类和方法之间的映射关系。

代码实体空间映射

转换工具

OpenModule 经常使用转换工具来清理数据，然后再将其发送给外部客户端。这确保了内部的数据库字段（如密码或敏感的系统标志）不会暴露。

• DSL 清理：在 getDsl 返回数据之前，可能会剥离仅与后端存储相关的元数据。
• 资源 URL 解析：使用 OssService 的配置，将内部的 OSS 路径转换为完整的 URL。

参考资料

• 官网文档：https://vtj.pro/
• 在线平台：https://app.vtj.pro/
• 开源仓库：https://gitee.com/newgateway/vtj