救命！这个低代码工具太香了 ——TinyEngine 物料自动导入上手

OpenTiny社区2025-11-14 17:06

本文由TinyEngine低代码物料导入功能贡献者张筠同学原创。

引言：低代码物料接入的痛点与解决方案

在低代码平台开发中，物料接入是核心环节之一。传统物料接入依赖开发者手动编写符合平台协议的 JSON 配置，不仅效率低下，还容易因人为失误导致兼容性问题 ------ 尤其是面对海量 UI 组件时，重复的人工操作会大幅拖慢开发进度。

为解决这一痛点，我们开发了 TinyEngine 低代码物料自动导入工具，支持通过 URL 爬取、NPM 包解析、源码上传三种方式，自动提取组件的 Props/Events/Slots 等 API 信息，并转换为符合 TinyEngine 协议的标准物料格式。配套的可视化前端实现了 "导入 - 预览 - 编辑 - 保存" 全流程闭环，将物料接入效率大幅度提升。

本文将从项目设计、核心模块实现、项目部署与使用指南等方面，带大家全面了解这个前后端一体化的物料处理方案。

一、项目概览：技术栈与核心架构

1. 技术栈选型

后端技术栈

  • 运行环境：Node.js v20.19.5+（原生支持 fetch 与 ES6 + 语法）
  • 核心依赖：Express（接口服务）、MySQL（物料存储）、Puppeteer（URL 爬取）、LLM SDK（API 提取）
  • 核心能力：多源数据解析、物料协议转换、异步任务管理

前端技术栈

  • 框架：Vue 3.2+（<script setup>语法）
  • 构建工具：Vite 4.0+（高效热更新与跨域代理）
  • UI 组件：OpenTiny Vue（轻量化企业级组件库）
  • 核心能力：动态表单、任务进度可视化、表格编辑、批量数据管理

2. 整体架构设计

项目采用前后端分离架构，核心交互流程如下：

  1. 前端发起导入请求（携带 URL/NPM 信息 / 源码文件）；
  2. 后端创建异步任务，根据导入类型执行对应解析逻辑；
  3. 调用 LLM 接口提取结构化 API 信息，转换为标准物料格式；
  4. 前端通过轮询获取任务进度，实时展示处理状态；
  5. 处理完成后，前端提供物料预览与编辑功能，支持保存到数据库。

二、核心功能拆解：从解析到可视化

1. 多源物料解析（后端核心能力）

依托四大核心模块协同工作，实现URL、NPM、源码三种导入方式的标准化解析，全程自动化完成从原始数据到TinyEngine标准物料的转化。

（1）URL 导入

基于 API生成模块 的URL表格驱动流程，通过Puppeteer模拟浏览器访问目标URL，根据用户指定的CSS选择器精准定位API表格数据，搭配重试机制保障爬取稳定性；获取表格数据后，传递给LLM模型进行结构化处理，生成包含Props/Events/Slots的原始API JSON；随后经 物料转换模块 转化为符合TinyEngine规范的物料格式，最后由 后处理模块 完成组件名标准化（如统一为PascalCase格式）及规则化优化，确保物料一致性。

（2）NPM 导入

接收用户输入的NPM包名与组件名后，后端自动下载对应包资源，通过 文件筛选模块 的NPM类型规则（强制校验index入口文件，提取含组件关键词的核心文件，自动跳过style、utils等非API相关目录及.map文件）完成文件筛选；筛选后的核心文件进入 API生成模块 的文件驱动流程，经LLM解析生成原始API JSON；再通过 物料转换模块 补充组件基本信息、规范Props/Events/Slots定义，最终由 后处理模块 按预设规则优化（无需处理的组件直接保留、表格组件合并列定义等），输出标准物料。

（3）源码导入

用户可上传Vue组件源码文件或ZIP压缩包，后端解压后触发 文件筛选模块 的源码类型处理逻辑------自动识别index.js/ts入口文件及Props/Events定义文件，过滤非API相关内容；筛选后的有效文件进入 API生成模块 执行文件驱动流程，经LLM解析生成原始API JSON；后续通过 物料转换模块 转化为TinyEngine标准格式，再由 后处理模块 清理子项组件冗余片段、统一组件名格式，最终生成可直接使用的标准化物料。

2. 可视化操作闭环（前端核心能力）

（1）动态导入表单

根据用户选择的导入类型（URL/NPM/ 源码），自动切换对应表单：

  • URL 导入：展示 URL 输入框与表格 CSS 选择器输入框；
  • NPM 导入：展示包名与组件名输入框；
  • 源码导入：展示文件上传组件（支持单个文件与 ZIP 包）。

（2）任务进度可视化

  • 提交导入请求后，展示进度条实时更新处理进度（0-100%）；
  • 处理中任务支持最小化为右侧悬浮卡片，不影响其他操作，点击可重新打开模态框查看详情；
  • 任务状态实时反馈（处理中 / 成功 / 失败），失败时显示具体错误信息。

（3）物料预览与编辑

任务处理成功后，通过表格展示生成的物料列表，支持：

  • 主表展示基础信息（组件名、导入类型、导入时间等）；
  • 展开行查看子表（属性 / 事件 / 插槽），支持编辑字段值、删除无效项；
  • 编辑后实时提交更新，确保数据同步到后端。

（4）物料库管理

提供完整的物料管理功能：

  • 筛选与搜索：按组件名精确筛选、关键词模糊搜索；
  • 批量操作：批量导出选中物料为 JSON 文件、批量删除无用物料；
  • 分页控制：默认 10 条 / 页，支持自定义每页显示数量。

三、项目部署

1. 环境要求

环境/工具 版本要求 说明
Node.js v20.19.5 及以上 支持fetch、ES6+语法，前后端通用，建议使用官网长期支持版确保兼容性
前端框架 Vue 3.2+ 前端采用<script setup>语法开发，需确保依赖版本符合要求
构建工具 Vite 4.0+ 负责前端项目构建、热更新及跨域代理配置，当前项目实际使用v7.1.7版本
数据库 MySQL 8.0 及以上 用于存储物料数据，需提前本地安装并启动
依赖服务 LLM接口（如DeepSeek/Qwen/OpenAI） 后端核心依赖，需准备支持JSON输出的大模型接口及对应API密钥、接口地址

2. 安装与配置

2.1 克隆仓库

首先将项目代码克隆到本地，执行以下命令：

bash 复制代码 
git clone <仓库地址>  # 替换为实际的项目仓库地址

2.2 安装依赖

进入项目根目录后，分别安装后端和前端的依赖包，确保环境一致性：

bash 复制代码 
# 1. 安装后端依赖
cd backend
npm install  # 若使用yarn/pnpm，可替换为yarn install/pnpm install

# 2. 安装前端依赖（需新开终端或返回根目录）
cd frontend
npm install  # 同理可替换为对应包管理工具的安装命令

2.3 环境配置

（1）后端配置

  1. 复制环境变量模板 ：进入后端目录，将 .env.example 模板文件复制为实际使用的 .env 文件：

    bash 复制代码 
    cd backend  # 若当前不在后端目录需执行此命令
cp .env.example .env  # Windows系统可手动复制文件并重命名为.env

  2. 编辑.env文件参数 ：用文本编辑器打开 .env 文件，根据本地环境和实际资源信息填写以下关键配置（替换占位符内容）：

    env 复制代码 
    # 服务器配置
SERVER_PORT=3001                  # 后端服务端口，默认3001，可按需修改
CORS_ALLOW_ORIGIN=http://localhost:8080 # 前端地址，需与前端端口保持一致，解决跨域问题

# 数据库配置（需与本地MySQL环境匹配）
MYSQL_HOST=localhost       # MySQL服务地址，本地默认localhost
MYSQL_PORT=3306            # MySQL端口，默认3306
MYSQL_USER=root            # MySQL用户名，替换为你的实际用户名
MYSQL_PASSWORD=your_password    # MySQL密码，替换为你的实际密码（无密码则留空）
MYSQL_DATABASE=lowcode_material # 数据库名，需后续手动创建该库

# LLM模型配置（必填，替换为实际可用的大模型信息）
OPENAI_MODEL=deepseek-reasoner            # 模型名称，如deepseek-reasoner、Qwen3-32B等
OPENAI_API_KEY=your_api_key_here          # 模型API密钥，从对应平台获取
OPENAI_BASE_URL=https://api.deepseek.com/v1 # 模型接口地址，按实际平台填写

# 默认路径配置（系统自动创建，无需手动操作）
DEFAULT_OUTPUT_DIR=output-log       # 最终物料JSON输出目录
DEFAULT_SCHEMA_LOG_DIR=schema-log   # 转换过程日志目录
DEFAULT_API_LOG_DIR=raw-api-log     # 原始API JSON日志目录
（2）前端配置（跨域与端口）

前端需配置代理对接后端服务，确保接口请求正常，步骤如下：

  1. 进入前端目录，打开 vite.config.js 文件（路径：frontend/vite.config.js）；

  2. 确认或修改以下配置（需与后端 .env 中的配置保持一致）：

    javascript 复制代码 
    import { defineConfig } from 'vite'; 
import vue from '@vitejs/plugin-vue'; 

export default defineConfig({
  plugins: [vue()],
  server: {
    port: 8080, // 前端端口，默认8080，需与后端CORS_ALLOW_ORIGIN中的端口一致
    proxy: {
      // 代理所有/api前缀的请求到后端服务
      '/api': {
        target: 'http://localhost:3001', // 后端服务地址，与SERVER_PORT一致
        changeOrigin: true, // 开启跨域适配
      }
    }
  }
});
    • 若修改了前端端口或后端服务端口，需同步更新对应配置。

3. 快速启动

前后端服务需按特定顺序启动，核心顺序：启动MySQL服务 → 创建项目数据库 → 启动后端服务 → 启动前端服务，具体步骤如下：

3.1 启动MySQL服务并创建项目数据库

（1）启动MySQL服务

根据本地操作系统，执行对应启动命令：

  • Windows：通过"服务"管理器找到"MySQL"服务，右键点击"启动"；
  • macOS（Homebrew安装） ：打开终端执行 brew services start mysql；
  • Linux（系统服务，以Ubuntu为例） ：执行 sudo systemctl start mysql（其他发行版按对应命令操作）。
（2）手动创建项目数据库

项目需使用预先创建的 lowcode_material 数据库，执行以下步骤：

  1. 打开终端/命令提示符，登录MySQL：

    bash 复制代码 
    mysql -u root -p  # 替换root为你的MySQL用户名，回车后输入密码（无密码直接回车）

  2. 执行SQL命令创建数据库（指定字符集避免中文乱码）：

    sql 复制代码 
    CREATE DATABASE IF NOT EXISTS lowcode_material 
CHARACTER SET utf8mb4 
COLLATE utf8mb4_unicode_ci;

  3. （可选）验证数据库创建成功：

    sql 复制代码 
    SHOW DATABASES;  # 执行后查看输出列表，确认包含lowcode_material

  4. 退出MySQL命令行：

    sql 复制代码 
    exit;

3.2 启动后端服务

bash 复制代码 
# 进入后端目录（若当前不在该目录）
cd backend

# 启动开发环境服务（使用配置的npm脚本）
npm run serve
  • 启动成功标识：终端显示服务监听信息（如 后端服务启动成功，端口：3001）；
  • 验证接口可用性：可通过浏览器访问 http://localhost:3001/api/material/docs，查看简易接口文档。

3.3 启动前端服务

需新开一个终端（避免与后端服务冲突），执行以下命令：

bash 复制代码 
# 进入前端目录
cd frontend

# 启动开发环境（支持热更新，修改代码后自动刷新）
npm run dev
  • 启动成功标识：终端输出 VITE v7.1.7 ready in 300 ms 及访问地址；
  • 访问前端：打开浏览器输入默认地址 http://localhost:8080，即可进入物料管理首页。

4. 启动常见问题排查

  • MySQL连接失败 ：检查 .env 中数据库配置（地址、端口、用户名、密码）是否与本地环境一致，确保MySQL服务已启动；
  • LLM接口报错：检查模型配置（API密钥、接口地址、模型名称）是否正确，确保接口可正常访问且有剩余调用额度。

四、核心使用流程

  1. 访问前端地址（默认 http://localhost:8080），进入物料管理首页；

  1. 选择导入方式（URL / NPM / 源码），填写对应信息（如 URL 地址、NPM 包名、上传源码文件）；

    • URL 导入：输入URL地址和API表格CSS选择器；
    • NPM 导入：输入NPM包名和组件名称；
    • 源码导入：上传源码文件（支持单个文件或zip）。
  1. 提交后等待任务处理，实时查看进度条（0-100%），进度条支持最小化；
  1. 任务成功后，预览生成的物料数据（属性 / 事件 / 插槽），可直接编辑修改或删除；
  • 编辑属性/事件/插槽
  • 删除属性/事件/插槽
  • 删除组件物料
  1. 点击 "保存到物料库"，将物料同步至 MySQL 数据库；
  1. 在首页通过筛选、搜索功能管理已保存的物料，支持批量导出或删除。
  • 通过组件名称筛选组件物料
  • 通过关键词筛选组件物料
  • 批量删除组件物料

* 批量导出组件物料

导出文件如下（以element-plus的Breadcrumb为例）：

json 复制代码 
[
  {
    "npm": {
      "package": "element-plus",
      "exportName": "ElBreadcrumb"
    },
    "icon": "breadcrumb",
    "name": {
      "zh_CN": "面包屑"
    },
    "tags": [
      "导航",
      "面包屑"
    ],
    "group": "element-plus",
    "schema": {
      "slots": {
        "default": {
          "label": {
            "zh_CN": "默认内容"
          },
          "description": {
            "zh_CN": "自定义默认内容"
          }
        }
      },
      "events": {},
      "properties": [
        {
          "name": "0",
          "label": {
            "zh_CN": "基础属性"
          },
          "content": [
            {
              "cols": 12,
              "type": "ArrayItemConfigurator-test",
              "label": {
                "text": {
                  "zh_CN": "分隔符"
                }
              },
              "widget": {
                "props": {
                  "placeholder": "请输入分隔符"
                },
                "component": "InputConfigurator"
              },
              "disabled": false,
              "property": "separator",
              "readOnly": false,
              "required": false,
              "description": {
                "zh_CN": "分隔符"
              },
              "defaultValue": "/",
              "labelPosition": "left"
            },
            {
              "cols": 12,
              "type": "unknown",
              "label": {
                "text": {
                  "zh_CN": "图标分隔符"
                }
              },
              "widget": {
                "props": {
                  "placeholder": "请输入图标名称"
                },
                "component": "InputConfigurator"
              },
              "disabled": false,
              "property": "separatorIcon",
              "readOnly": false,
              "required": false,
              "description": "图标分隔符组件",
              "defaultValue": null,
              "labelPosition": "left"
            }
          ],
          "description": {
            "zh_CN": "组件核心功能相关的配置，包括 separator、 separatorIcon 等核心属性"
          }
        }
      ]
    },
    "devMode": "proCode",
    "doc_url": "",
    "version": "",
    "category": "element-plus",
    "keywords": [
      "Breadcrumb",
      "面包屑",
      "导航"
    ],
    "snippets": [
      {
        "icon": "breadcrumb",
        "name": {
          "zh_CN": "面包屑"
        },
        "schema": {
          "children": [
            {
              "props": {
                "to": "/home"
              },
              "children": [
                {
                  "props": {
                    "text": "首页"
                  },
                  "componentName": "Text"
                }
              ],
              "componentName": "ElBreadcrumbItem"
            },
            {
              "props": {
                "to": "/list"
              },
              "children": [
                {
                  "props": {
                    "text": "列表页"
                  },
                  "componentName": "Text"
                }
              ],
              "componentName": "ElBreadcrumbItem"
            },
            {
              "props": {},
              "children": [
                {
                  "props": {
                    "text": "详情页"
                  },
                  "componentName": "Text"
                }
              ],
              "componentName": "ElBreadcrumbItem"
            }
          ]
        },
        "category": "element-plus",
        "screenshot": "",
        "snippetName": "ElBreadcrumb"
      }
    ],
    "component": "ElBreadcrumb",
    "configure": {
      "loop": true,
      "styles": true,
      "isModal": false,
      "isLayout": false,
      "isPopper": false,
      "condition": true,
      "framework": "Vue",
      "shortcuts": {
        "properties": [
          "separator"
        ]
      },
      "isNullNode": false,
      "contextMenu": {
        "actions": [
          "copy",
          "remove",
          "insert",
          "updateAttr",
          "bindEvent"
        ],
        "disable": []
      },
      "isContainer": true,
      "nestingRule": {
        "childWhitelist": "ElBreadcrumbItem",
        "parentWhitelist": "",
        "ancestorWhitelist": "",
        "descendantBlacklist": ""
      },
      "clickCapture": false,
      "rootSelector": ""
    },
    "description": "面包屑导航组件，用于显示当前页面在系统层级 结构中的位置"
  }
]

结尾

TinyEngine 低代码物料自动导入工具的核心目标，是通过「自动化解析 + 可视化操作」的闭环设计，解决了低代码物料接入的效率瓶颈与兼容性难题。无论是 URL 爬取、NPM 解析还是源码上传，工具都力求简化全流程操作，让开发者无需关注底层协议细节与格式转换逻辑，即可快速将各类 UI 组件无缝转化为符合 TinyEngine 标准的可用物料，让低代码物料接入从繁琐的手动配置，转变为高效、省心的一站式操作。

关于OpenTiny

欢迎加入 OpenTiny 开源社区。添加微信小助手：opentiny-official 一起参与交流前端技术～

OpenTiny 官网：opentiny.design

OpenTiny 代码仓库：github.com/opentiny

TinyVue 源码：github.com/opentiny/ti...

TinyEngine 源码： github.com/opentiny/ti...

欢迎进入代码仓库 Star🌟TinyEngine、TinyVue、TinyNG、TinyCLI、TinyEditor~ 如果你也想要共建，可以进入代码仓库，找到 good first issue 标签，一起参与开源贡献~

相关推荐
努力学前端Hang1 小时前
移动端跨平台开发深度解析：UniApp、Taro、Flutter 与 React Native 对比
前端·javascript·react native·react.js
前端九哥1 小时前
🚫循环里写return，浏览器当场沉默！
前端·javascript
亲爱的马哥2 小时前
填鸭表单！开箱即用的开源问卷调查系统！
java·前端·低代码·产品经理
米诺zuo2 小时前
nextjs文件路由、路由组
前端·next.js
加个鸡腿儿2 小时前
锚点跳转-附带CSS样式 & 阻止页面刷新技术方案
前端·javascript·css
dragon7252 小时前
FutureProvider会刷新两次的问题研究
前端·flutter
天蓝色的鱼鱼2 小时前
Next.js路由全解析：Pages Router 与 App Router，你选对了吗？
前端·next.js
xun_xing2 小时前
基于Nextjs15的学习手记
前端·javascript·react.js
NocoBase2 小时前
7 款最佳自托管 AI 工具，快速构建业务应用
低代码·开源·资讯
热门推荐
01GitHub 镜像站点02UV安装并设置国内源03安娜的档案(Anna’s Archive) 镜像网站/国内最新可访问入口（持续更新）04综合整理：pdf预览显示：你尝试预览的文件可能对你的计算机有害。如果你信任此文件以及其来源，请打开此文件以看其内容，如何解决以正常预览文件05Linux下V2Ray安装配置指南06BongoCat - 跨平台键盘猫动画工具07Labelme从安装到标注：零基础完整指南08智能库存管理的需求预测模型：从业务痛点到落地代码的完整实践09NVIDIA显卡驱动、CUDA、cuDNN 和 TensorRT 版本匹配指南10jdk21下载、安装（Windows、Linux、macOS）