TinyEngine 物料自动导入上手指南：新手也能快速落地
本文由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. 整体架构设计 项目采用前后端分离架构，核心交互流程如下： 前端发起导入请求（携带 URL/NPM 信息 / 源码文件）； 后端创建异步任务，根据导入类型执行对应解析逻辑； 调用 LLM 接口提取结构化 API 信息，转换为标准物料格式； 前端通过轮询获取任务进度，实时展示处理状态； 处理完成后，前端提供物料预览与编辑功能，支持保存到数据库。 二、核心功能拆解：从解析到可视化 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 克隆仓库 首先将项目代码克隆到本地，执行以下命令： git clone <仓库地址> # 替换为实际的项目仓库地址 2.2 安装依赖 进入项目根目录后，分别安装后端和前端的依赖包，确保环境一致性： # 1. 安装后端依赖 cd backend npm install # 若使用yarn/pnpm，可替换为yarn install/pnpm install # 2. 安装前端依赖（需新开终端或返回根目录） cd frontend npm install # 同理可替换为对应包管理工具的安装命令 2.3 环境配置 （1）后端配置 复制环境变量模板：进入后端目录，将 .env.example 模板文件复制为实际使用的 .env 文件： cd backend # 若当前不在后端目录需执行此命令 cp .env.example .env # Windows系统可手动复制文件并重命名为.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）前端配置（跨域与端口） 前端需配置代理对接后端服务，确保接口请求正常，步骤如下： 进入前端目录，打开 vite.config.js 文件（路径：frontend/vite.config.js）； 确认或修改以下配置（需与后端 .env 中的配置保持一致）： 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 数据库，执行以下步骤： 打开终端/命令提示符，登录MySQL： mysql -u root -p # 替换root为你的MySQL用户名，回车后输入密码（无密码直接回车） 执行SQL命令创建数据库（指定字符集避免中文乱码）： CREATE DATABASE IF NOT EXISTS lowcode_material CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; （可选）验证数据库创建成功： SHOW DATABASES; # 执行后查看输出列表，确认包含lowcode_material 退出MySQL命令行： exit; 3.2 启动后端服务 # 进入后端目录（若当前不在该目录） cd backend # 启动开发环境服务（使用配置的npm脚本） npm run serve 启动成功标识：终端显示服务监听信息（如 后端服务启动成功，端口：3001）； 验证接口可用性：可通过浏览器访问 http://localhost:3001/api/material/docs，查看简易接口文档。 3.3 启动前端服务 需新开一个终端（避免与后端服务冲突），执行以下命令： # 进入前端目录 cd frontend # 启动开发环境（支持热更新，修改代码后自动刷新） npm run dev 启动成功标识：终端输出 VITE v7.1.7 ready in 300 ms 及访问地址； 访问前端：打开浏览器输入默认地址 http://localhost:8080，即可进入物料管理首页。 4. 启动常见问题排查 MySQL连接失败：检查 .env 中数据库配置（地址、端口、用户名、密码）是否与本地环境一致，确保MySQL服务已启动； LLM接口报错：检查模型配置（API密钥、接口地址、模型名称）是否正确，确保接口可正常访问且有剩余调用额度。 四、核心使用流程 访问前端地址（默认http://localhost:8080），进入物料管理首页； 选择导入方式（URL / NPM / 源码），填写对应信息（如 URL 地址、NPM 包名、上传源码文件）； URL 导入：输入URL地址和API表格CSS选择器； NPM 导入：输入NPM包名和组件名称； 源码导入：上传源码文件（支持单个文件或zip）。 提交后等待任务处理，实时查看进度条（0-100%），进度条支持最小化； 任务成功后，预览生成的物料数据（属性 / 事件 / 插槽），可直接编辑修改或删除； 编辑属性/事件/插槽 删除属性/事件/插槽 删除组件物料 点击 “保存到物料库”，将物料同步至 MySQL 数据库； 在首页通过筛选、搜索功能管理已保存的物料，支持批量导出或删除。 通过组件名称筛选组件物料 通过关键词筛选组件物料 批量删除组件物料 * 批量导出组件物料 导出文件如下（以element-plus的Breadcrumb为例）： [ { "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 官网：https://opentiny.design OpenTiny 代码仓库：https://github.com/opentiny TinyVue 源码：https://github.com/opentiny/tiny-vue TinyEngine 源码： https://github.com/opentiny/tiny-engine 欢迎进入代码仓库 Star🌟TinyEngine、TinyVue、TinyNG、TinyCLI、TinyEditor~ 如果你也想要共建，可以进入代码仓库，找到 good first issue 标签，一起参与开源贡献~
