🛠️ 多功能 SQL 查询工具（客户端）

一个功能丰富、交互友好的现代化 SQL 开发环境

📋 目录

项目简介
功能特性
技术栈
快速开始
环境配置
项目结构
使用指南
API 集成
开发指南
贡献指南
许可证

🎯 项目简介

Qoder 是一个专为数据分析师、数据库管理员和开发人员设计的现代化 SQL 编辑器。它提供了一个轻量级、响应式的 SQL 开发环境，支持语法高亮、智能提示、查询执行和结果展示等核心功能。

🎨 界面预览

暗黑主题：专为长时间编码设计的护眼界面
响应式布局：完美适配桌面和移动设备
实时反馈：即时的查询执行状态和错误提示

✨ 功能特性

🔥 核心功能

🖊️ 高级代码编辑器
- 基于 Monaco Editor，提供 VS Code 级别的编辑体验
- 完整的 SQL 语法高亮和错误提示
- 智能代码补全和快捷模板
- 支持代码格式化和多光标编辑
⚡ 智能查询执行
- 支持完整 SQL 查询和选中代码片段执行
- 快捷键支持：Ctrl+Enter 或 F5
- 实时执行时间统计
- 详细的错误信息显示
📊 强大的结果展示
- 表格形式展示查询结果，支持大数据量
- 智能分页：10/25/50/100 行每页
- 横向滚动支持，完美处理宽表格
- NULL 值和未定义值的特殊显示
🌲 多数据源树形管理
- 树形展示数据源，支持分类管理
- 支持多级分类（生产环境、测试环境、开发环境等）
- 数据源勾选功能，支持多选并行查询
- 实时刷新数据源列表
🔀 多数据源并行查询
- 同时查询多个数据源，提高效率
- 每个数据源的结果在独立标签页中展示
- 显示每个数据源的执行时间和状态
- 完善的错误信息展示和状态指示
📑 多标签页结果管理
- 每个数据源的查询结果在独立标签页展示
- 成功/失败状态的颜色区分
- 支持关闭单个或所有标签页
- 标签页支持上下左右滚动浏览

🛠️ 高级功能

📋 多种复制功能
- 点击表头复制所有字段名（逗号分隔）
- 点击行按钮复制整行 JSON 数据
- 点击任意单元格复制该单元格内容
- 智能处理 NULL 和 UNDEFINED 值
📤 数据导出
- 单数据源导出：支持 Excel 格式导出当前查询结果
- 多数据源 ZIP 导出：一键导出所有数据源结果为压缩包
- 自动生成带时间戳的文件名，避免覆盖
- 支持大数据量导出，包含错误信息的智能处理
⬍ 灵活布局系统
- 专注编辑器模式：编辑器占满整个界面，专注编写 SQL
- 分屏模式：编辑器和结果区域并排，可自由调整比例
- 专注结果模式：结果区域占满整个界面，专注查看数据
- 可拖拽分隔条调整高度比例，设置自动保存
🔄 双模式支持
- 模拟数据模式：内置示例数据，无需后端服务
- 真实 API 模式：连接真实数据库服务，支持多数据源
- 一键切换，实时状态检测
🌐 API 连接管理
- 自动检测 API 连接状态
- 详细的连接错误信息
- 手动重连功能
- 超时和重试机制

🔧 技术栈

前端框架

React 19.1.1 - 最新的 React 框架
Vite 7.1.2 - 极速构建工具
Monaco Editor 0.52.2 - VS Code 编辑器内核

开发工具

ESLint 9.33.0 - 代码质量检查
CSS3 - 现代化样式，支持响应式设计
Fetch API - 原生网络请求

构建配置

ES6+ Modules - 现代 JavaScript 模块系统
Hot Reload - 开发时热更新
Tree Shaking - 自动移除未使用代码

🚀 快速开始

环境要求

Node.js >= 16.0.0
npm >= 8.0.0 或 yarn >= 1.22.0

安装步骤

克隆项目

git clone https://github.com/schrodingerfish/qoder.git
cd qoder

安装依赖

npm install
# 或
yarn install

配置环境变量

cp .env.example .env.local

启动开发服务器

npm run dev
# 或
yarn dev

访问应用 打开浏览器访问 http://localhost:5173

📦 构建生产版本

# 构建生产版本
npm run build

# 预览生产版本
npm run preview

# 代码质量检查
npm run lint

⚙️ 环境配置

项目支持多种环境配置文件，按优先级排序：

.env.local - 本地配置（优先级最高，不提交到版本控制）
.env.development - 开发环境配置
.env.production - 生产环境配置
.env - 通用配置（优先级最低）

配置项说明

# API 服务器地址
VITE_API_BASE_URL=http://localhost:3000

# API 请求超时时间（毫秒）
VITE_API_TIMEOUT=30000

# 是否启用认证功能
VITE_ENABLE_AUTH=false

# 开发模式开关
VITE_DEV_MODE=true

⚠️ 注意：在 Vite 项目中，只有以 VITE_ 为前缀的环境变量才能在前端代码中访问。

📁 项目结构

qoder/
├── public/                 # 静态资源目录
├── src/                   # 源代码目录
│   ├── components/        # React 组件
│   │   ├── QueryResult.jsx    # 查询结果展示组件
│   │   └── SqlEditor.jsx      # SQL 编辑器组件
│   ├── config/           # 配置文件
│   │   └── api.js            # API 配置管理
│   ├── services/         # 服务层
│   │   └── sqlApi.js         # SQL API 服务
│   ├── styles/           # 样式文件
│   │   ├── components/       # 组件样式
│   │   └── global/          # 全局样式
│   ├── App.jsx           # 主应用组件
│   └── main.jsx          # 应用入口文件
├── .env.example          # 环境变量示例
├── package.json          # 项目配置文件
├── vite.config.js        # Vite 构建配置
└── README.md            # 项目说明文档

核心模块说明

🎯 组件层 (`src/components/`)

SqlEditor.jsx - 基于 Monaco Editor 的 SQL 编辑器，支持布局切换
QueryResult.jsx - 查询结果展示，支持分页、复制、导出等功能
DatasourceTree.jsx - 数据源树形组件，支持多级分类和多选
QueryTabs.jsx - 多标签页组件，管理多数据源查询结果

🔧 服务层 (`src/services/`)

sqlApi.js - SQL 查询服务，支持模拟数据和真实 API 两种模式
datasourceApi.js - 数据源管理 API，支持树形展示、多数据源查询和 ZIP 导出

⚙️ 配置层 (`src/config/`)

api.js - API 配置管理，包含端点、超时、认证等配置

📖 使用指南

基本操作

编写 SQL 查询
- 在编辑器中输入 SQL 语句
- 支持语法高亮和智能提示
- 可以选中部分代码执行
执行查询
- 点击"执行查询"按钮
- 使用快捷键 Ctrl+Enter 或 F5
- 选中代码后执行仅运行选中部分
查看结果
- 结果以表格形式展示
- 支持分页浏览和横向滚动
- 显示执行时间和影响行数

高级功能

📋 数据复制功能

复制字段名：点击表头的"复制字段"按钮
复制行数据：点击每行的"复制"按钮，获取 JSON 格式数据
复制单元格：直接点击任意数据单元格

📤 数据导出

单数据源导出：点击"导出 Excel"按钮，下载当前查询结果
多数据源 ZIP 导出：点击"📦 导出为 ZIP"按钮，一键导出所有数据源结果
自动生成带时间戳的文件名，避免覆盖
包含错误信息的智能处理

🌲 数据源管理

切换到真实 API 模式：点击右上角"模拟数据"按钮切换模式
查看数据源树：左侧边栏显示按分类组织的数据源
选择数据源：勾选需要查询的数据源（支持多选）
展开/折叠分类：点击分类前的箭头图标

🔀 多数据源查询

选择多个数据源后执行查询
每个数据源的结果在独立标签页中展示
显示执行时间、状态和详细错误信息
支持关闭单个或所有标签页

⬍ 布局切换

专注编辑器模式：点击"📝"按钮，编辑器占满整个界面
分屏模式：点击"⬍"按钮，编辑器和结果区域并排显示
专注结果模式：点击"📊"按钮，结果区域占满整个界面
在分屏模式下可拖拽分隔条调整高度比例

🔄 模式切换

模拟数据模式：使用内置示例数据，适合演示和测试
真实 API 模式：连接实际的数据库服务，支持多数据源功能

快捷键

快捷键	功能
`Ctrl+Enter`	执行查询
`F5`	执行查询
`Ctrl+/`	切换注释
`Ctrl+D`	选择下一个相同词
`Alt+↑/↓`	移动行

🔌 API 集成

后端 API 要求

项目需要后端提供以下 API 端点：

1. 健康检查

GET /api/health
响应: 200 OK

2. 执行 SQL 查询

POST /api/execute-sql
Content-Type: application/json

请求体:
{
  "query": "SELECT * FROM users LIMIT 10;",
  "database": "mine",
  "options": {
    "timeout": 30000,
    "format": "json",
    "includeMetadata": true,
    "maxRows": 10000
  }
}

成功响应:
{
  "success": true,
  "data": [...],
  "rowCount": 10,
  "message": "查询成功",
  "executionTime": 150
}

错误响应:
{
  "success": false,
  "error": "SQL语法错误",
  "message": "详细错误信息",
  "metadata": {...}
}

3. Excel 导出

POST /api/export-excel
Content-Type: application/json

请求体:
{
  "timestamp": "2025-08-23 14:30:00.000",
  "query": "SELECT * FROM users LIMIT 10;",
  "database": "mine",
  "filename": "query_result",
  "options": {}
}

响应: Excel 文件流
Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

4. 获取数据源树形结构

GET /api/datasource/tree

响应示例：

[
    {
        "id": "category_1",
        "label": "生产环境",
        "type": "category",
        "children": [
            {
                "id": "datasource_1",
                "label": "主业务数据库",
                "type": "datasource",
                "datasourceCode": "main_business",
                "description": "主要业务系统数据库"
            }
        ]
    }
]

5. 多数据源并行查询

POST /api/datasource/multi-query
Content-Type: application/json

请求体:
{
  "query": "SELECT * FROM users LIMIT 10",
  "datasourceCodes": ["main_business", "order_db"],
  "options": {
    "timeout": 30000,
    "format": "json",
    "includeMetadata": true,
    "maxRows": 10000
  }
}

成功响应：

{
  "success": true,
  "message": "多数据源查询完成: 成功 2/2, 失败 0/2",
  "totalExecutionTime": 1250,
  "results": [
    {
      "datasourceCode": "main_business",
      "datasourceName": "主业务数据库",
      "success": true,
      "data": [...],
      "rowCount": 10,
      "executionTime": 850
    },
    {
      "datasourceCode": "order_db",
      "datasourceName": "订单数据库",
      "success": true,
      "data": [...],
      "rowCount": 8,
      "executionTime": 920
    }
  ]
}

6. 多数据源 ZIP 导出

POST /api/export-multi-datasource-excel
Content-Type: application/json

请求体:
{
  "query": "SELECT * FROM users",
  "datasourceCodes": ["main_business", "order_db"],
  "fileNamePrefix": "multi_export",
  "options": {
    "timeout": 30000,
    "maxRows": 10000
  }
}

响应： ZIP 文件流 Content-Type: application/zip

错误处理

系统提供完善的错误处理机制：

网络错误：自动重试和超时处理
SQL 错误：详细的语法错误信息
服务器错误：状态码映射和用户友好的错误消息

🛠️ 开发指南

开发环境设置

安装开发依赖

npm install

启动开发服务器

npm run dev

代码检查

npm run lint

代码规范

使用 ESLint 进行代码质量检查
采用函数式组件和 React Hooks
遵循现代 JavaScript ES6+ 语法
使用 CSS3 和现代布局技术

调试技巧

使用浏览器开发者工具查看网络请求
检查控制台日志获取详细错误信息
使用 React Developer Tools 调试组件状态

性能优化

组件懒加载和代码分割
查询结果虚拟滚动（大数据量）
API 请求缓存和防抖
图片和资源优化

🤝 贡献指南

我们欢迎所有形式的贡献！

贡献方式

报告问题
- 在 GitHub Issues 中报告 Bug
- 提供详细的重现步骤和环境信息
功能建议
- 在 Issues 中提出新功能建议
- 详细描述功能的使用场景和价值
代码贡献
- Fork 项目到您的 GitHub 账户
- 创建功能分支进行开发
- 提交 Pull Request

开发流程

Fork 项目

git clone https://github.com/schrodingerfish/qoder.git
cd qoder
git checkout -b feature/your-feature-name

开发和测试

npm install
npm run dev
# 进行开发和测试

提交代码

git add .
git commit -m "feat: add your feature description"
git push origin feature/your-feature-name

创建 Pull Request
- 在 GitHub 上创建 Pull Request
- 详细描述修改内容和测试情况

代码提交规范

使用 Conventional Commits 规范：

feat: 新功能
fix: 修复问题
docs: 文档更新
style: 代码格式修改
refactor: 代码重构
test: 测试相关
chore: 构建过程或辅助工具变动

📞 联系我们

问题反馈：GitHub Issues
邮件联系：[email protected]
讨论社区：GitHub Discussions

📄 许可证

本项目采用 MIT 许可证。

如果这个项目对您有帮助，请给我一个 ⭐️

Made with ❤️ by SchrodingerFish

Name		Name	Last commit message	Last commit date
Latest commit History 8 Commits
public		public
src		src
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
eslint.config.js		eslint.config.js
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
vite.config.js		vite.config.js

License

SchrodingerFish/Qoder

Folders and files

Latest commit

History

Repository files navigation