# sql_to_fastapi_LLM_generator
**Repository Path**: ncepu-bj/sql_to_fastapi_LLM_generator
## Basic Information
- **Project Name**: sql_to_fastapi_LLM_generator
- **Description**: 通过大模型来生成基于fastapi框架的标准RESTful风格的分层接口项目
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 3
- **Forks**: 0
- **Created**: 2025-08-27
- **Last Updated**: 2026-01-10
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# SQL_To_FastAPI 一款基于大模型的企业级智能代码生成器
**基于大语言模型的智能SQL转FastAPI代码生成器**
*智能解析SQL数据库结构，智能理解和分析业务，生成企业级高质量的FastAPI RESTful API项目*
## 🎯 项目简介
本项目是一个基于大语言模型（LLM）的智能代码生成器，专门将企业数据库表结构SQL文件，转换为完整的企业级FastAPI RESTful API项目。生成的目标项目满足FastAPI框架的最佳实践，目标项目代码包含基本表的数据操作接口，真正能够开箱即用；代码符合企业级标准、并自动生成API文档；
企业可以在此目标项目基础上，快速增加完善业务逻辑和流程，快速部署上线生产环境。
### 🛠️ 技术路线与实现策略
本项目包含**两个部分技术实现策略**，针对不同复杂度的代码生成需求采用最适合的技术方案：
**🔧 1 基础代码部分 - 基础数据操作代码**：
- **主要技术**：代码模板技术
- **适用场景**：基本表的CRUD数据操作接口代码生成
- **优势**：高效稳定，代码质量可控，适合标准化的数据操作逻辑
**🚀 2 务逻辑代码部分 - 智能代码生成**：
- **主要技术**：大语言模型 + 提示词工程 + 上下文工程 + 轻量级模板技术
- **适用场景**：智能代码生成，基于大模型进行代码生成
- **核心技术**：大语言模型 + 提示词工程 + 上下文工程 + 轻量级模板技术
- **适用场景**：复杂业务逻辑代码、工作流程、业务规则处理
- **优势**：智能理解业务需求，生成个性化的复杂业务代码
这种**模板为主+LLM为辅**的混合技术架构，既保证了基础代码的稳定性和质量，又为未来复杂业务逻辑生成提供了强大的AI能力支撑。
### ✨ 核心特性
- 🧠 **智能SQL解析**: 全面解析MySQL DDL，自动提取表结构、字段类型、约束关系等完整信息
- 📊 **完整业务代码生成**: 自动生成SQLAlchemy模型、Pydantic schemas、服务层和API路由层
- 🏗️ **企业级架构**: 标准三层架构，包含完整的异常处理、数据验证、事务管理和日志系统
- � **生产就绪**: 一键生成完整可运行的FastAPI项目，包含依赖管理和部署配置
- 🔍 **代码质量保障**: 内置语法验证、类型检查和最佳实践规范
- 🌏 **多数据库支持**: 支持MySQL、PostgreSQL等主流数据库
- 📦 **模块化设计**: 清晰的代码组织结构，易于扩展和维护
### 🏗️ 系统架构
```
SQL表结构 → 智能解析 → 模型生成 → 业务逻辑 → API路由 → 完整项目
↓ ↓ ↓ ↓ ↓ ↓
DDL解析 表结构分析 ORM映射 服务层代码 RESTful API 可运行项目
```
## 🚀 快速开始
### 环境要求
- Python 3.13+
- 支持的数据库：MySQL、PostgreSQL（更多数据库支持开发中）
### 安装步骤
1. **克隆项目**
```bash
git clone https://github.com/your-repo/sql_to_fastapi_generator.git
cd sql_to_fastapi_generator
```
2. **创建虚拟环境**
```bash
# 使用conda（推荐）
conda create -n sql_to_fastapi python=3.13
conda activate sql_to_fastapi
# 或使用venv
python -m venv venv
source venv/bin/activate # Linux/Mac
# 或 venv\Scripts\activate # Windows
```
3. **安装依赖**
```bash
pip install -r requirements.txt
```
### 基本使用
#### 方式一：交互式使用（推荐新手）
1. **准备SQL文件**
```sql
-- 将你的MySQL DDL保存到 input/ 目录
-- 支持复杂表结构：外键关系、索引、约束等
-- 例如: input/my_database.sql
-- 用户表
CREATE TABLE users (
id INT PRIMARY KEY AUTO_INCREMENT,
username VARCHAR(50) NOT NULL UNIQUE,
email VARCHAR(100) NOT NULL,
password VARCHAR(255) NOT NULL,
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME ON UPDATE CURRENT_TIMESTAMP
);
-- 订单表(示例业务关系)
CREATE TABLE orders (
id INT PRIMARY KEY AUTO_INCREMENT,
user_id INT NOT NULL,
total_amount DECIMAL(10,2) NOT NULL,
status ENUM('pending', 'paid', 'shipped', 'delivered') DEFAULT 'pending',
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
FOREIGN KEY (user_id) REFERENCES users(id)
);
```
> 字段插入兼容性与特殊处理说明
- JSON 字段：请传入对象类型（dict 或 list），不要传 JSON 字符串。示例：`{"extra": 1}` 应作为对象传递，而不是 `"{\"extra\":1}"`。将 JSON 作为字符串传入会导致 SQL 1064 语法错误（常见现象是 SQL 中出现额外的引号和转义符）。
- BLOB/BINARY/VARBINARY：请传入 `bytes/bytearray`，不要传普通字符串。示例：`b"hello"`。如需存文本请使用 `TEXT/VARCHAR`。
- BIT：长度为 1 的 BIT 字段建议使用布尔值（`True/False`、`"1"/"0"`）；长度>1 的 BIT 字段请使用 `bytes` 或整型位串，例如 `b"\x01"`。
- SET：请传入列表（数组）形式，值必须属于 DDL 中定义的集合。示例：`["paid", "shipped"]`。系统会在入库时转换为逗号分隔字符串。
- ENUM：请传入枚举值的字符串，注意大小写需与定义一致。示例：`"pending"`。
- TIME：使用 `"HH:MM:SS"` 字符串，或 Python `datetime.time/timedelta` 对象。避免使用占位字符串 `"string"`。
- DATE/DATETIME/TIMESTAMP：传 Python `date/datetime` 或符合格式的字符串（如 `"YYYY-MM-DD"`、`"YYYY-MM-DD HH:MM:SS"`）。
- GEOMETRY/POINT：暂不支持直接插入，请传 `null` 或跳过该字段；如需存储，请在业务层按数据库要求构造 WKT/GeoJSON 后再入库。
- YEAR：建议传入四位年份整型（如 `2025`），不建议使用 `0` 作为占位。
- 默认占位值说明：示例请求中的 `"string"`、空列表 `[]`、`b""` 仅为占位，实际调用时需替换为符合类型的有效值。
- 常见 1064 错误排查：若在报错 SQL 中出现 `'{\"...\"}'` 等转义字符串，通常是将 JSON/二进制以字符串传入导致。请按上述类型规范修正。
示例（正确类型的插入载荷片段）：
```json
{
"enum_field": "pending",
"set_field": ["paid", "shipped"],
"json_field": {"additionalProp1": {}},
"bit_field": true,
"binary_field": "base64: aGVsbG8=",
"time_field": "00:00:00",
"point_field": null
}
```
2. **运行生成器**
```bash
# 基本使用 - 交互式选择SQL文件
python start.py
# 系统会自动检测input目录中的SQL文件并提供选择
```
#### 方式二：参数化使用（推荐批处理和自动化）
**🔧 支持的命令行参数：**
| 参数 | 简写 | 说明 | 示例 |
|------|------|------|------|
| `--input` | `-i` | 指定SQL文件路径 | `-i "input/users.sql"` |
| `--output-dir` | `-o` | 指定输出目录 | `-o "my_projects"` |
| `--quiet` | `-q` | 静默模式（无控制台输出） | `-q` |
| `--help` | `-h` | 显示帮助信息 | `-h` |
**📋 使用示例：**
```bash
# 1. 查看所有可用参数
python start.py --help
# 2. 指定SQL文件生成项目
python start.py --input "input/my_database.sql"
# 3. 指定SQL文件和输出目录
python start.py --input "input/users_orders.sql" --output-dir "projects/ecommerce"
# 4. 静默模式生成（适合脚本调用）
python start.py --input "input/blog.sql" --output-dir "output/blog_api" --quiet
# 5. 使用相对路径
python start.py -i "./input/test_schema.sql" -o "./custom_output"
# 6. 使用绝对路径
python start.py -i "D:/sql_files/company.sql" -o "D:/generated_projects"
```
**💡 参数化使用的优势：**
- ✅ **批处理支持**：可以集成到构建脚本中
- ✅ **自动化友好**：支持CI/CD流水线调用
- ✅ **无交互运行**：适合服务器环境和脚本化场景
- ✅ **自定义输出**：可以指定任意输出目录
- ✅ **静默模式**：便于日志分析和错误处理
**🚨 注意事项：**
- SQL文件必须存在且格式正确（支持 `.sql`, `.mysql`, `.ddl` 扩展名）
- 输出目录会自动创建，如不存在系统将自动创建目录结构
- 项目名称自动使用SQL文件名（不包含扩展名）
- 静默模式下仍会生成完整的日志文件到 `logs/` 目录
**📝 批处理脚本示例：**
```bash
# Windows批处理脚本 (generate_all.bat)
@echo off
echo 正在生成用户管理系统...
python start.py -i "schemas/users.sql" -o "projects/user_system" -q
echo 正在生成订单管理系统...
python start.py -i "schemas/orders.sql" -o "projects/order_system" -q
echo 正在生成博客系统...
python start.py -i "schemas/blog.sql" -o "projects/blog_system" -q
echo 所有项目生成完成！
```
```bash
# Linux/Mac脚本 (generate_all.sh)
#!/bin/bash
echo "正在生成用户管理系统..."
python start.py -i "schemas/users.sql" -o "projects/user_system" -q
echo "正在生成订单管理系统..."
python start.py -i "schemas/orders.sql" -o "projects/order_system" -q
echo "正在生成博客系统..."
python start.py -i "schemas/blog.sql" -o "projects/blog_system" -q
echo "所有项目生成完成！"
```
3. **查看生成结果**
```
output/generated_project/
├── app/
│ ├── models/ # SQLAlchemy模型 (ORM映射)
│ │ ├── __init__.py
│ │ ├── user.py # 用户模型
│ │ └── order.py # 订单模型
│ ├── schemas/ # Pydantic数据模型 (API数据验证)
│ │ ├── __init__.py
│ │ ├── user.py # 用户数据模型
│ │ └── order.py # 订单数据模型
│ ├── services/ # 业务逻辑层 (服务类)
│ │ ├── __init__.py
│ │ ├── user_service.py # 用户业务逻辑
│ │ └── order_service.py # 订单业务逻辑
│ ├── api/ # FastAPI路由层 (API端点)
│ │ ├── __init__.py
│ │ ├── user.py # 用户API路由
│ │ └── order.py # 订单API路由
│ ├── core/ # 核心配置和工具
│ │ ├── config.py # 配置管理
│ │ ├── database.py # 数据库连接
│ │ └── exceptions.py # 异常处理
│ └── main.py # FastAPI应用入口
├── requirements.txt # 项目依赖
├── .env.example # 环境变量模板
├── README.md # 项目说明
└── start.py # 项目启动脚本
```
4. **启动生成的项目**
```bash
cd output/generated_project
# 安装依赖
pip install -r requirements.txt
# 配置数据库
cp .env.example .env
# 编辑.env文件，配置数据库连接
# 本地运行请修改.env 文件中 HOST=0.0.0.0改为localhost
# 启动应用
python start.py
# 访问API文档: http://localhost:8000/docs
```
## 📚 详细文档
- 🏗️ [系统架构设计](./docs/enterprise_architecture_design.md) - 完整的系统架构和设计原理
- � [使用指南](./docs/README.md) - 详细的使用说明和配置指南
- 🧪 [测试报告](./tests/TEST_REPORT.md) - 完整的测试结果和覆盖率报告
- 📝 [项目状态](./docs/PROJECT_STATUS.md) - 项目当前状态和开发计划
## 🧪 测试与质量保证
### 运行完整测试套件
```bash
# 运行所有测试
python -m pytest tests/ -v
# 运行特定测试模块
python -m pytest tests/test_generation_engine.py -v # 生成引擎测试
python -m pytest tests/test_phase1_integration.py -v # 集成测试
# 运行覆盖率测试
python -m pytest tests/ --cov=src --cov-report=html
```
### 🎯 测试覆盖范围
- **单元测试**: 所有核心模块的功能测试
- **集成测试**: 端到端生成流程测试
- **代码质量测试**: 生成代码的语法和质量验证
- **性能测试**: 大型项目生成性能基准测试
## 🎨 项目技术亮点
### 🧠 智能SQL解析引擎
- **完整DDL解析**: 支持复杂的MySQL DDL语句，包括表结构、约束、索引、外键关系
- **字段类型映射**: 智能映射SQL数据类型到Python/SQLAlchemy类型
- **业务语义识别**: 自动识别常见业务字段（ID、时间戳、状态字段等）
- **关系分析**: 自动分析表间关系和外键依赖
### 🎯 企业级代码生成
- **分层架构**: 严格的三层架构设计，模型层、服务层、API层职责清晰
- **代码质量**: 生成符合PEP8规范的高质量Python代码
- **类型安全**: 完整的类型注解，支持mypy静态类型检查
- **异常处理**: 完善的异常处理机制和错误信息
## 🤝 参与贡献
我们欢迎所有形式的贡献，共同打造更好的智能代码生成工具！
### 🎯 贡献方式
1. 🐛 **报告Bug**: 在Issues中详细描述问题和复现步骤
2. 💡 **功能建议**: 提出新功能想法和改进建议
3. 📖 **改进文档**: 完善项目文档、添加使用示例
4. 💻 **代码贡献**: 提交Pull Request，改进核心功能
5. 🧪 **测试支持**: 编写测试用例，提高代码覆盖率
6. 🌍 **国际化**: 添加多语言支持和翻译
### 🛠️ 开发流程
```bash
# 1. Fork本仓库到你的GitHub账号
# 2. 克隆你的Fork仓库
git clone https://github.com/your-username/sql_to_fastapi_LLM_generator.git
cd sql_to_fastapi_LLM_generator
# 3. 创建功能分支
git checkout -b feature/your-feature-name
# 4. 配置开发环境
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -r requirements.txt
pip install -r requirements-dev.txt # 开发依赖
# 5. 运行测试确保环境正常
python -m pytest tests/ -v
# 6. 进行开发和测试
# ... 你的代码修改 ...
# 7. 运行代码格式化和检查
black src/ tests/
isort src/ tests/
mypy src/
# 8. 提交更改
git add .
git commit -m "Add: 你的功能描述"
# 9. 推送到你的Fork仓库
git push origin feature/your-feature-name
# 10. 创建Pull Request到主仓库
```
### 📋 贡献指南
- **代码规范**: 遵循PEP 8，使用Black格式化，添加类型注解
- **测试要求**: 新功能需要包含对应的测试用例
- **文档更新**: 重要功能需要更新相关文档
- **commit信息**: 使用清晰的commit message格式
- **兼容性**: 确保与Python 3.9+兼容
### 🏆 贡献者认可
优秀贡献者将获得：
- 项目README中的贡献者列表展示
- 特殊贡献者徽章
- 项目核心开发者邀请机会
## 📜 许可证
本项目采用 [MIT 许可证](LICENSE)。
### 🙏 致谢与支持
### 🛠️ 开源技术栈
- **FastAPI** ⚡: 现代化的Python Web框架，高性能API开发首选
- **SQLAlchemy** 🗃️: 强大的Python ORM工具，数据库操作的艺术
- **Pydantic** ✅: 优雅的数据验证库，确保API数据质量
- **Jinja2** 📝: 灵活的模板引擎，支持高质量代码模板生成
### 👥 社区贡献者
感谢所有为本项目贡献代码、文档、测试和建议的开发者们！
### 📞 技术支持与交流
- 📧 **邮箱支持**: [project@example.com](mailto:project@example.com)
- 🐛 **Issue跟踪**: [GitHub Issues](https://github.com/your-repo/sql_to_fastapi_generator/issues)
- 📖 **在线文档**: [项目Wiki](https://github.com/your-repo/sql_to_fastapi_generator/wiki)
---
**🌟 如果这个项目对你有帮助，请给我们一个Star！**
**Made with ❤️ by SQL to FastAPI Generator Team**
*让智能代码生成更简单高效*