# Excel_TO_Json

**Repository Path**: liaoxp27/excel_to_json

## Basic Information

- **Project Name**: Excel_TO_Json
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-07-29
- **Last Updated**: 2025-08-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Excel 转 JSON 转换器

一个基于Flask的Web应用，用于将Excel文件转换为JSON格式数据，支持多种Excel格式和自定义工作表选择。

## 功能特点
- 支持多种Excel格式：.xls, .xlsx, .xlsm, .xltx, .xltm
- 提供直观的Web界面，无需命令行操作
- 支持通过名称或索引选择工作表
- 自动处理中文等非ASCII字符
- 实时显示转换结果，支持格式化输出
- 同时保留命令行转换功能

## 设计思路

### 整体架构
本项目采用前后端分离的简单架构：
- **前端**：HTML/CSS构建的单页面应用，提供文件上传和参数设置界面
- **后端**：Flask框架处理文件上传、Excel解析和JSON转换
- **核心逻辑**：独立的Excel转JSON转换模块，可同时被Web界面和命令行调用

### 数据流程
1. 用户上传Excel文件并设置工作表参数
2. 后端验证文件格式并生成唯一文件名
3. 调用转换模块解析Excel内容
4. 将转换结果以JSON格式返回给前端显示
5. 同时保存JSON文件到服务器本地

### 关键技术点
- 文件安全处理：使用UUID生成唯一文件名，避免中文和特殊字符问题
- 错误处理机制：完善的异常捕获和用户友好提示
- 兼容性设计：支持多种Excel格式和工作表选择方式
- 可扩展性：核心转换逻辑与界面分离，便于功能扩展

## 环境要求
- Python 3.7+
- 依赖包：flask, pandas, openpyxl, xlrd

## 安装步骤

1. 克隆或下载本项目到本地
2. 安装依赖包：
   ```bash
   pip install -r requirements.txt
   ```

## 使用方法

### 一键启动（推荐）
以下是针对不同操作系统的详细启动步骤，即使您没有编程经验，只需按照步骤操作即可成功运行。

#### Windows系统
**准备工作：**
1. 确保已安装Python 3.8或更高版本
   - 若未安装：访问 <mcurl name="Python官网" url="https://www.python.org/downloads/"></mcurl>，下载并安装Python
   - 安装时务必勾选 **"Add Python to PATH"** 选项（非常重要！）
2. 确保电脑已连接互联网（首次启动需要下载必要组件）

**启动步骤：**
1. 找到下载或解压后的项目文件夹
2. 双击文件夹中的 `<mcfile name="start.bat" path="d:\work\trae\excel_to_json_converter\start.bat"></mcfile>` 文件
3. 首次启动会出现命令窗口，自动下载所需组件（请耐心等待，不要关闭窗口）
4. 当看到 **"Running on http://127.0.0.1:5000"** 字样时，表示启动成功
5. 系统会自动打开浏览器窗口，显示工具界面

**常见问题：**
- 双击后窗口一闪而过：通常是Python未安装或未勾选"Add Python to PATH"，请重新安装Python
- 提示"pip不是内部或外部命令"：Python安装时未添加到系统路径，请重新安装并勾选相应选项

#### Linux系统
**准备工作：**
1. 确保电脑已连接互联网
2. 打开终端（常用方法：按下 `Ctrl + Alt + T` 组合键）

**启动步骤:**
1. **安装Python环境**（仅首次使用需要）：
   在终端中复制粘贴以下命令并按Enter键：
   ```bash
   sudo apt update && sudo apt install -y python3 python3-pip
   ```
   *提示：输入密码时屏幕不会显示字符，这是正常现象，输入完成后按Enter即可*

2. **进入项目文件夹**：
   在终端中输入以下命令（请将`/path/to/excel_to_json_converter`替换为您实际的文件夹路径）：
   ```bash
   cd /path/to/excel_to_json_converter
   ```
   *例如：如果文件在桌面上，命令可能是：`cd ~/Desktop/excel_to_json_converter`*

3. **赋予脚本执行权限**：
   在终端中复制粘贴以下命令并按Enter键：
   ```bash
   chmod +x start.sh
   ```

4. **运行启动脚本**：
   在终端中复制粘贴以下命令并按Enter键：
   ```bash
   ./start.sh
   ```

5. **访问工具**：
   启动成功后，打开浏览器，在地址栏输入：<mcurl name="应用界面" url="http://127.0.0.1:5000"></mcurl> 并按Enter键

**常见问题：**
- 提示"Permission denied"：请确保已执行步骤3赋予权限
- 提示"Command not found"：请检查Python是否安装成功
- 启动后无法访问网页：请检查终端中是否显示"Running on http://127.0.0.1:5000"

### 手动启动

### Web界面使用（推荐）
1. 启动应用：
   ```bash
   python app.py
   ```
2. 打开浏览器访问：http://127.0.0.1:5000
3. 点击"选择文件"按钮上传Excel文件
4. （可选）输入工作表名称或索引（默认为0）
5. 点击"上传并转换"按钮
6. 查看转换结果

### 命令行使用
```bash
python excel_to_json.py <输入Excel文件> <输出JSON文件> [--sheet 工作表名称或索引]
```

#### 参数说明
- `input_file`: 输入Excel文件的路径（必填）
- `output_file`: 输出JSON文件的路径（必填）
- `--sheet`: 可选参数，指定工作表名称或索引，默认为0

#### 命令行示例
```bash
# 转换第一个工作表
python excel_to_json.py data.xlsx output.json

# 转换指定工作表
python excel_to_json.py data.xlsx output.json --sheet "用户数据"
```

## 项目结构
```
excel_to_json_converter/
├── app.py              # Flask应用入口
├── excel_to_json.py    # 核心转换逻辑
├── requirements.txt    # 项目依赖
├── README.md           # 项目说明文档
├── templates/
│   └── index.html      # Web界面模板
├── start.bat           # Windows一键启动脚本
├── start.sh            # Linux一键启动脚本
└── uploads/            # 文件上传和转换结果存储目录
```

## API文档

### 接口概览
本项目提供以下API接口，支持外部系统集成Excel转JSON功能：

#### 文件上传与转换接口
- **URL**: `/upload`
- **方法**: `POST`
- **描述**: 上传Excel文件并转换为JSON格式
- **请求参数**:
  - `file`: Excel文件 (multipart/form-data格式)
  - `sheet` (可选): 工作表名称或索引，默认为0
- **成功响应**:
  ```json
  {
    "success": true,
    "message": "文件上传并转换成功",
    "data": {
      "file_name": "原始文件名.xlsx",
      "json_path": "/uploads/xxx.json",
      "data": [转换后的JSON数据]
    }
  }
  ```
- **错误响应**:
  ```json
  {
    "success": false,
    "message": "错误描述信息",
    "error_code": "ERROR_CODE"
  }
  ```
- **状态码**:
  - 200: 成功
  - 400: 请求参数错误
  - 413: 文件过大
  - 500: 服务器内部错误

#### 获取转换结果接口
- **URL**: `/results/<file_id>`
- **方法**: `GET`
- **描述**: 获取指定文件ID的转换结果
- **路径参数**:
  - `file_id`: 文件唯一标识符
- **成功响应**:
  ```json
  {
    "success": true,
    "data": [转换后的JSON数据]
  }
  ```

## 开发指南

### 开发环境搭建
1. **克隆代码库**:
   ```bash
   git clone <repository-url>
   cd excel_to_json_converter
   ```

2. **创建虚拟环境**:
   ```bash
   # Windows
   python -m venv venv
   venv\Scripts\activate
   
   # Linux/Mac
   python3 -m venv venv
   source venv/bin/activate
   ```

3. **安装开发依赖**:
   ```bash
   pip install -r requirements.txt
   pip install -r requirements-dev.txt  # 包含测试和代码质量工具
   ```

### 项目架构详解
本项目采用分层架构设计，主要包含以下模块：

1. **应用层** (`app.py`): Flask应用入口，路由注册
2. **路由层** (`routes/`): API接口定义
3. **服务层** (`services/`): 业务逻辑实现
   - `file_service.py`: 文件上传和管理
   - `converter_service.py`: Excel转JSON核心逻辑
4. **工具层** (`utils/`): 通用工具函数
5. **数据层** (`models/`): 数据模型定义

### 代码规范
- 遵循PEP 8编码规范
- 使用类型注解提高代码可读性
- 关键函数需添加文档字符串
- 复杂逻辑需编写单元测试

### 测试指南
1. **运行单元测试**:
   ```bash
   pytest tests/ -v
   ```

2. **测试覆盖率**:
   ```bash
   pytest --cov=app tests/
   ```

### 贡献流程
1. Fork本仓库
2. 创建特性分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'Add some amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 打开Pull Request

## 注意事项
- 文件大小限制：最大支持16MB的Excel文件
- 工作表选择：留空则默认使用第一个工作表
- 转换结果：会同时显示在页面和保存到uploads目录
- 支持的格式：.xls, .xlsx, .xlsm, .xltx, .xltm

## 故障排除
- **服务器启动失败**：检查端口是否被占用或依赖是否安装完整
- **文件上传失败**：检查文件格式和大小是否符合要求
- **转换失败**：检查Excel文件格式是否规范，避免复杂格式如合并单元格
- **中文显示问题**：确保使用最新版本的依赖包