# DataExtract

**Repository Path**: jinoy/DataExtract

## Basic Information

- **Project Name**: DataExtract
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-14
- **Last Updated**: 2026-08-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DataExtract Pro

轻量级数据提取与转换工具 —— 从多种数据源提取、加工、导出数据的一站式前端工具。

## 项目概况

DataExtract Pro 是一个纯前端（Vue 3）数据加工工具，支持从 JSON、API 接口、SQL 数据库、Excel/CSV 文件四种数据源提取数据，通过可视化配置完成字段映射、数据清洗、过滤排序等加工流程，最终导出为 Excel、CSV、PDF、JSON、TXT、Markdown 等多种格式。

**核心价值**：无需写代码，通过可视化界面完成「取数 → 清洗 → 导出」全流程，适用于运营报表、数据迁移、接口调试等场景。

### 技术栈

| 分类 | 技术 |
|------|------|
| 前端框架 | Vue 3.4 + Vite 5 |
| 状态管理 | Pinia 2 |
| UI 组件库 | Element Plus 2.6 |
| 表格组件 | VxeTable 4.6（大数据量虚拟滚动） |
| 路由 | Vue Router 4（Hash 模式） |
| JSON 解析 | jsonpath-plus（支持点号路径 + JSONPath） |
| Excel 解析 | xlsx (SheetJS) |
| 导出引擎 | xlsx / jspdf + jspdf-autotable / file-saver |
| 日期处理 | dayjs |
| 后端服务（SQL 查询） | Node.js + Express + mysql2 + pg |

### 项目结构

```
DataExtract/
├── src/
│   ├── components/
│   │   ├── DataInput/          # 数据输入模块
│   │   │   ├── index.vue       # 输入模式切换入口
│   │   │   ├── PasteInput.vue  # JSON 粘贴输入
│   │   │   ├── ApiInput.vue    # API 接口请求
│   │   │   ├── SqlInput.vue    # SQL 数据库查询
│   │   │   ├── FileInput.vue   # Excel/CSV 文件导入
│   │   │   └── PaginationConfig.vue  # 分页配置
│   │   ├── DataProcess/        # 数据加工模块
│   │   │   ├── index.vue       # 加工配置入口
│   │   │   ├── FieldConfig.vue # 字段配置
│   │   │   ├── FieldProcessorDialog.vue  # 字段处理器
│   │   │   ├── FilterConfig.vue  # 过滤配置
│   │   │   ├── SortConfig.vue    # 排序配置
│   │   │   ├── RulePickerDialog.vue    # 规则模板选择
│   │   │   └── PathExplorerDialog.vue  # 路径探索器
│   │   └── DataOutput/         # 数据输出模块
│   │       ├── index.vue       # 输出配置入口
│   │       ├── DataPreview.vue # 数据预览
│   │       ├── OutputConfig.vue      # 导出配置
│   │       └── ExportPreviewDialog.vue  # 导出预览
│   ├── engine/                 # 核心引擎
│   │   ├── jsonPath.js         # JSON 路径解析
│   │   ├── pagination.js       # 分页抓取引擎
│   │   ├── fieldProcessor.js   # 字段处理器（11种）
│   │   └── exporter.js         # 多格式导出引擎
│   ├── stores/                 # Pinia 状态管理
│   │   ├── dataInput.js        # 数据输入状态
│   │   ├── dataProcess.js      # 数据加工状态
│   │   ├── dataOutput.js       # 数据输出状态
│   │   ├── template.js         # 模板管理
│   │   ├── rule.js             # 规则库
│   │   └── history.js          # 历史记录
│   ├── views/                  # 页面视图
│   │   ├── MainView.vue        # 主工作台
│   │   ├── TemplateView.vue    # 模板管理页
│   │   └── HistoryView.vue     # 历史记录页
│   ├── router/index.js         # 路由配置
│   ├── styles/global.css       # 全局样式
│   └── main.js                 # 应用入口
├── server/                     # SQL 查询后端服务
│   ├── index.js                # Express 服务器
│   └── package.json
├── vite.config.js              # Vite 配置（含代理）
└── package.json
```

## 功能说明

### 1. 数据输入（4 种数据源）

#### 1.1 JSON 粘贴
- 直接粘贴 JSON 文本，自动解析
- 支持嵌套对象和数组

#### 1.2 API 接口请求
- 支持 GET / POST / PUT / DELETE 方法
- 请求头、请求参数可视化配置
- **参数自动解析**：粘贴 `key1=val1&key2=val2` 格式的 query string，一键转为 key-value 表单
- URL 输入框失焦时自动从 URL 提取参数
- 请求体支持 JSON / form-data
- 超时时间、重试次数可配置
- **分页抓取**：支持页码分页（page-based），可配置页码参数名、页大小参数名、起始页码（0 或 1 开始）、总条数路径、列表路径、最大页数、请求间隔
- **CORS 绕过**：开发模式通过 Vite 代理转发请求，勾选「CORS 代理」即可绕过浏览器跨域限制

#### 1.3 SQL 数据库查询
- 支持 **MySQL** 和 **PostgreSQL**
- 数据库连接配置（类型 / 主机 / 端口 / 库名 / 用户名 / 密码）
- 测试连接功能
- SQL 编辑器 + 一键格式化
- 查询结果预览（前 5 行）
- 安全限制：仅允许 SELECT / WITH 语句，最多返回 10000 行，30 秒超时

#### 1.4 Excel/CSV 文件导入
- 拖拽上传 `.xlsx` / `.xls` / `.csv`
- 文件头魔数校验，自动识别真实文件格式
- CSV 专用解析（纯文本路径，支持 UTF-8 / GBK 自动识别）
- 多 Sheet 选择（Excel 多表时自动列出）
- 数据预览（前 5 行）
- 大文件使用 dense 模式节省内存
- 文件大小限制 50MB，格式异常时给出针对性修复建议

### 2. 数据加工

#### 2.1 路径配置
- 配置数据列表的 JSON 路径（如 `data.list`）
- 路径探索器：树形可视化查看 JSON 结构
- 路径验证 + 自动字段检测

#### 2.2 字段配置
- 自动检测嵌套对象的字段（支持多级路径如 `user.address.city`）
- 字段别名设置
- 字段选择 / 排序（拖拽）
- 每个字段可配置多个处理器（管线式执行）

#### 2.3 字段处理器（11 种）

| 处理器 | 说明 | 示例 |
|--------|------|------|
| 前缀添加 | 在值前添加文本 | `¥` + `100` → `¥100` |
| 后缀添加 | 在值后添加文本 | `90` + `%` → `90%` |
| 字符串拼接 | 模板拼接多字段 | `{value}-{field1}` |
| 数值运算 | 四则运算 + 取模 | `10000` / `100` → `100` |
| 日期格式化 | 时间戳/日期字符串转格式 | `1786672221321` → `2026-08-14` |
| 条件映射 | 状态码映射为文本 | `1` → `待审核` |
| 子串提取 | 正则/位置截取 | 手机号脱敏 `138****1234` |
| 默认值 | 空值填充 | 空 → `未知` |
| 去除空格 | 首尾空格清理 | ` abc ` → `abc` |
| 大小写转换 | upper / lower / capital | `abc` → `ABC` |

#### 2.4 过滤配置
- 支持多条件 AND / OR 组合
- 操作符：等于 / 不等于 / 大于 / 小于 / 大于等于 / 小于等于 / 包含 / 不包含 / 为空 / 不为空

#### 2.5 排序配置
- 多字段排序
- 升序 / 降序

#### 2.6 规则库
- 内置 8 条常用规则（时间戳转日期、状态映射、分转元、手机号脱敏等）
- 支持保存自定义规则到规则库
- 规则按分类组织，支持搜索
- 规则持久化到 localStorage

### 3. 数据输出

#### 3.1 数据预览
- VxeTable 虚拟滚动表格（支持大数据量）
- 原生 HTML 表格兜底渲染
- 搜索过滤
- 调试面板（字段数、数据条数、路径状态实时查看）

#### 3.2 导出格式

| 格式 | 说明 |
|------|------|
| Excel (.xlsx) | 带表头，自动列宽 |
| CSV | 支持 UTF-8 BOM / 自定义分隔符 |
| PDF | 支持横向/纵向、页眉页脚 |
| JSON | 键值对格式 |
| TXT | 自定义分隔符 |
| Markdown | 表格格式 |

#### 3.3 导出配置
- 空值处理：保留 / 填充默认值 / 过滤空行
- 文件名自定义
- 表头导出开关
- 编码选择（UTF-8 / GBK）
- 导出前预览（字段覆盖率统计）

### 4. 模板管理
- 保存当前配置为模板（含数据输入、加工、输出全量配置）
- 模板列表管理（加载 / 删除 / 重命名）
- 模板持久化到 localStorage

### 5. 历史记录
- 自动记录每次操作
- 支持回溯查看

## 部署说明

### 环境要求

- **Node.js** >= 16（推荐 18 LTS 或更高）
- **npm** >= 8 或 **pnpm** / **yarn**

### 前端部署

#### 开发模式

```bash
# 安装依赖
npm install

# 启动开发服务器（默认端口 5173）
npm run dev
```

开发服务器启动后自动打开浏览器，访问 `http://localhost:5173`。

#### 生产构建

```bash
# 构建生产包
npm run build

# 预览构建结果
npm run preview
```

构建产物输出到 `dist/` 目录，可直接部署到任意静态文件服务器（Nginx / Apache / Vercel / Netlify 等）。

#### Nginx 部署示例

```nginx
server {
    listen 80;
    server_name your-domain.com;
    root /path/to/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    # SQL 后端代理（如需）
    location /api/sql/ {
        proxy_pass http://localhost:3456;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

### 后端部署（SQL 查询服务）

SQL 数据库查询功能需要后端代理服务，前端纯静态部署无法直连数据库。

```bash
# 进入后端目录
cd server

# 安装依赖
npm install

# 启动服务（默认端口 3456）
npm start
```

后端服务启动后，前端通过 Vite 代理（开发模式）或 Nginx 代理（生产模式）将 `/api/sql` 请求转发到 `http://localhost:3456`。

> 如不使用 SQL 查询功能，无需启动后端服务，其他功能（JSON 粘贴、API 请求、Excel/CSV 导入）均为纯前端实现。

### Vite 代理配置

开发模式下，`vite.config.js` 已配置两个代理：

| 代理路径 | 目标 | 用途 |
|----------|------|------|
| `/api/proxy` | 动态目标 | CORS 绕过，转发 API 请求 |
| `/api/sql` | `http://localhost:3456` | SQL 查询后端服务 |

## 使用指南

### 快速开始

1. 启动前端服务：`npm run dev`
2. （可选）启动 SQL 后端：`cd server && npm install && npm start`
3. 打开浏览器访问 `http://localhost:5173`

### 典型使用流程

```
选择数据源 → 配置参数 → 获取数据 → 配置路径 → 字段映射 → 数据加工 → 预览验证 → 导出文件
```

#### 示例：从 API 提取数据并导出 Excel

1. **数据输入**：选择「接口请求」模式
2. 填入 API URL，配置请求方法和参数
3. 如需分页，开启分页配置，设置页码参数名和起始页码
4. 点击「发送请求」获取数据
5. **数据处理**：配置列表路径（如 `data.list`），点击「验证路径」
6. 系统自动检测字段，调整字段别名和处理器
7. 如需过滤/排序，在对应面板配置
8. **数据输出**：查看数据预览确认无误
9. 选择导出格式为 Excel，点击「导出」

#### 示例：从 Excel 文件提取并清洗数据

1. **数据输入**：选择「Excel/CSV」模式
2. 拖拽上传 `.xlsx` 文件
3. 选择 Sheet，预览数据，点击「确认导入」
4. **数据处理**：系统自动识别字段
5. 为需要清洗的字段添加处理器（如去除空格、默认值填充）
6. **数据输出**：预览确认后导出

#### 示例：从 MySQL 查询数据并导出

1. 启动后端服务：`cd server && npm install && npm start`
2. **数据输入**：选择「SQL 查询」模式
3. 选择数据库类型（MySQL），填写连接信息
4. 点击「测试连接」确认连通
5. 输入 SQL 语句（仅支持 SELECT），点击「执行查询」
6. 后续加工和导出流程同上

### CORS 绕过说明

在开发模式下遇到 API 请求跨域（CORS error）时：

1. 在 API 输入面板勾选「CORS 代理」开关
2. 请求会通过 Vite dev server 的 `/api/proxy` 代理转发
3. 目标 URL 作为 `url` 参数传递给代理

> 此功能仅在开发模式（`npm run dev`）下有效。生产环境请在 Nginx 或后端服务中配置 CORS。

## API 文档（SQL 后端服务）

### POST /api/sql/query

执行 SQL 查询。

**请求体：**

```json
{
  "type": "mysql",
  "host": "localhost",
  "port": 3306,
  "database": "mydb",
  "username": "root",
  "password": "123456",
  "sql": "SELECT * FROM users LIMIT 100"
}
```

**成功响应：**

```json
{
  "success": true,
  "data": [{ "id": 1, "name": "张三" }],
  "total": 1,
  "fields": ["id", "name"]
}
```

**失败响应：**

```json
{
  "success": false,
  "error": "SQL 语句仅允许 SELECT 或 WITH"
}
```

### POST /api/sql/test

测试数据库连接。

**请求体：** 同上（不含 `sql` 字段）

**响应：**

```json
{
  "success": true,
  "message": "MySQL 连接成功"
}
```

### 安全限制

- SQL 语句仅允许 `SELECT` 和 `WITH`（正则校验，忽略大小写）
- 查询结果最多返回 10000 行
- 连接超时 30 秒
- 全局启用 CORS

## 开发说明

### 添加自定义字段处理器

在 `src/engine/fieldProcessor.js` 的 `processorRegistry` 中添加：

```javascript
const processorRegistry = {
  // ... 已有处理器
  myProcessor: (value, config) => {
    // 处理逻辑
    return newValue
  }
}
```

同时在 `processorTypes` 数组中添加配置项，即可在 UI 中使用。

### 添加导出格式

在 `src/engine/exporter.js` 中添加导出函数，并在 `exportData` 的 switch 中注册。

## 常见问题

### 数据预览空白

1. 打开数据预览面板右上角的「调试」开关
2. 检查 `processedData.length` 是否 > 0、`selectedFieldCount` 是否 > 0
3. 若 `selectedFieldCount = 0`，点击黄色警告中的「自动识别字段并重载」按钮

### Excel 上传报错

1. 确保文件是真正的 Excel/CSV 格式（非 txt/html 改后缀）
2. 推荐使用 `.xlsx` 格式（比 `.xls` 解析更稳定）
3. 大文件建议先另存为 CSV 再上传
4. 文件大小不超过 50MB

### API 请求 CORS 报错

1. 开发模式下勾选「CORS 代理」
2. 生产环境在 Nginx 或后端配置 CORS 头

### SQL 查询无法连接

1. 确认后端服务已启动：`cd server && npm start`
2. 检查数据库连接参数是否正确
3. 确认数据库允许从本机 IP 连接
4. 检查防火墙是否放行数据库端口

## License

MIT