Open API 与外部集成
OpenModule 作为 VTJ.PRO 平台对外暴露的 API 接口层，负责 VTJ IDE 客户端（工作台）、第三方集成与核心后端服务之间的通信。它提供了用于基于令牌的认证、DSL 转换、AI 代理桥接以及资源管理的专用端点。
OpenModule 架构
OpenModule 被构建为一个标准的 NestJS 模块，它聚合了来自业务层的多个服务，并通过 OpenController 将它们暴露出来。
数据流与组件交互
下图说明了 OpenController 如何与核心及业务服务交互，以满足外部请求。
外部 API 交互映射
flowchart TD
subgraph External Clients
A[VTJ IDE / Workbench]
B[Third-party Integrations]
end
subgraph OpenModule
C[OpenController]
D[OpenService]
end
subgraph Core & Business Services
E["AuthService (Core)"]
F["DslService (Business)"]
G["AIService (AI)"]
H["OssService (Core)"]
I["TemplateService (Business)"]
end
A -- "REST/WS" --> C
B -- "REST" --> C
C --> D
D -- "Validate Token" --> E
D -- "Fetch/Transform DSL" --> F
D -- "Stream AI Chat" --> G
D -- "Upload/Access Assets" --> H
D -- "Publish Templates" --> I
认证与安全
外部访问采用基于令牌的机制进行安全保护。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 函数与代码库中具体类和方法之间的映射关系。
代码实体空间映射
classDiagram
class OpenController {
+login(dto)
+getDsl(id)
+saveDsl(id, dsl)
+chat(messages)
+upload(file)
}
class OpenService {
+login(username, password)
+getDsl(id)
+saveDsl(id, dsl)
+chat(params)
}
class DslService {
+findOne(id)
+save(entity)
+publishFromDev(appId)
}
class AIService {
+completions(params)
+streamCompletions(params)
}
OpenController --> OpenService : calls
OpenService --> DslService : uses for DSL
OpenService --> AIService : uses for Chat
转换工具
OpenModule 经常使用转换工具来清理数据，然后再将其发送给外部客户端。这确保了内部的数据库字段（如密码或敏感的系统标志）不会暴露。
- DSL 清理 ：在
getDsl返回数据之前，可能会剥离仅与后端存储相关的元数据。 - 资源 URL 解析 ：使用
OssService的配置，将内部的 OSS 路径转换为完整的 URL。
参考资料
- 官网文档：vtj.pro/
- 在线平台：app.vtj.pro/
- 开源仓库：gitee.com/newgateway/...