# saas-python **Repository Path**: uesugi-java/saas-python ## Basic Information - **Project Name**: saas-python - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-12-18 - **Last Updated**: 2025-12-18 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # saas-Python 基于FastAPI的Web开发框架，专门用于访问达梦数据库。 ## 🚀 项目特性 - **FastAPI框架**: 高性能的现代Python Web框架，支持异步处理 - **达梦数据库支持**: 原生支持达梦数据库访问，使用DBPython驱动 - **安全认证**: JWT认证和密码加密，保障API安全 - **自动文档**: 自动生成Swagger和ReDoc API文档 - **分层架构**: 清晰的分层架构设计（API层、业务逻辑层、数据访问层） - **配置管理**: 灵活的环境配置管理，支持多环境部署 - **统一响应**: 标准化的API响应格式，便于前端处理 - **错误处理**: 完善的错误处理机制和异常捕获 - **日志记录**: 详细的日志记录系统，支持文件和控制台输出 - **CORS支持**: 跨域资源共享配置 - **数据库连接池**: 高效的数据库连接池管理 - **文件上传**: 支持图片上传和结果保存 - **批量处理**: 支持批量图片检测 ## 📁 项目结构 ``` saas-python/ ├── app/ # 主应用目录 │ ├── api/ # API路由层 │ │ ├── dependencies.py # 依赖注入 │ │ └── v1/ # API版本1 │ │ ├── api.py # API路由注册 │ │ └── endpoints/ # API端点 │ │ ├── health.py # 健康检查 │ │ └── users.py # 用户管理 │ ├── config/ # 配置管理 │ │ ├── database.py # 数据库配置 │ │ └── settings.py # 应用配置 │ ├── database/ # 数据库相关 │ │ ├── connection.py # 数据库连接管理 │ │ ├── models/ # 数据模型 │ │ │ ├── base.py # 基础模型 │ │ │ └── user.py # 用户模型 │ │ └── repositories/ # 数据访问层 │ │ └── base.py # 基础仓储类 │ ├── logic/ # 业务逻辑层 │ │ └── services/ # 业务服务 │ │ └── user_service.py # 用户服务 │ ├── middlewares/ # 中间件 │ │ ├── cors.py # CORS中间件 │ │ ├── error_handler.py # 错误处理中间件 │ │ └── logging.py # 日志中间件 │ ├── schemas/ # Pydantic模型 │ │ ├── base.py # 基础Schema │ │ ├── response.py # 响应Schema │ │ └── user.py # 用户Schema │ ├── utils/ # 工具类 │ │ ├── datetime.py # 日期时间工具 │ │ ├── file.py # 文件工具 │ │ ├── http.py # HTTP工具 │ │ ├── response.py # 响应工具 │ │ ├── security.py # 安全工具 │ │ └── thread_task_manager.py # 线程任务管理 │ ├── logs/ # 日志文件 │ │ └── app.log # 应用日志 │ └── main.py # 应用入口 ├── uploads/ # 上传文件目录 ├── results/ # 检测结果图片目录 ├── logs/ # 日志文件目录 ├── requirements.txt # 生产环境依赖 ├── requirements-dev.txt # 开发环境依赖 ├── env.example # 环境变量示例 ├── test_main.http # HTTP测试文件 └── READBE.md # 项目说明 ``` ## 🛠️ 快速开始 ### 1. 环境准备 确保你的系统已安装： - **Python 3.8+** - **达梦数据库服务器** (推荐版本 8.0+) - **Git** (用于版本控制) ### 2. 克隆项目 ```bash git clone cd saas-python ``` ### 3. 创建虚拟环境 ```bash # 创建虚拟环境 python -m venv .venv # 激活虚拟环境 # Windows .venv\Scripts\activate # Linux/Mac source .venv/bin/activate ``` ### 4. 安装依赖 ```bash # 安装生产环境依赖 pip install -r requirements.txt # 安装开发环境依赖（可选） pip install -r requirements-dev.txt ``` ### 5. 配置环境变量 ```bash # 复制环境变量示例文件 cp env.example .env ``` 编辑 `.env` 文件，配置你的环境： ```env # 应用配置 APP_NAME=saas-Python APP_VERSION=1.0.0 DEBUG=true # 服务器配置 HOST=0.0.0.0 PORT=8000 # 数据库配置 DB_HOST=localhost DB_PORT=3306 DB_USERNAME=root DB_PASSWORD=root@123 DB_DATABASE=MYSQL DB_CHARSET=utf8 DB_POOL_SIZE=10 DB_MAX_OVERFLOW=20 DB_POOL_TIMEOUT=30 DB_POOL_RECYCLE=3600 # 日志配置 LOG_LEVEL=INFO LOG_FILE=logs/app.log # 安全配置 SECRET_KEY=your-secret-key-here-change-this-in-production ALGORITHM=HS256 ACCESS_TOKEN_EXPIRE_MINUTES=30 # CORS配置 CORS_ORIGINS=["*"] CORS_METHODS=["*"] CORS_HEADERS=["*"] # 文件存储配置 UPLOAD_DIR=uploads RESULT_DIR=results MAX_FILE_SIZE=10485760 ALLOWED_IMAGE_TYPES=["image/jpeg", "image/png", "image/webp"] ``` ### 6. 运行应用 ```bash # 开发模式运行（自动重载） uvicorn app.main:app --reload --host 0.0.0.0 --port 8000 # 生产模式运行 uvicorn app.main:app --host 0.0.0.0 --port 8000 # 后台运行（Linux/Mac） nohup uvicorn app.main:app --host 0.0.0.0 --port 8000 > app.log 2>&1 & ``` ### 7. 访问应用 启动成功后，你可以访问以下地址： - **应用主页**: http://localhost:8000 - **Swagger API文档**: http://localhost:8000/docs - **ReDoc API文档**: http://localhost:8000/redoc - **健康检查**: http://localhost:8000/health ## 📚 API接口文档 ### 基础接口 #### 根路径 - **GET** `/` - 获取应用基本信息 #### 健康检查 - **GET** `/health` - 应用健康检查 - **GET** `/api/v1/health/` - API健康检查 - **GET** `/api/v1/health/db` - 数据库健康检查 ### 用户管理接口 #### 获取用户列表 ```http GET /api/v1/users/?skip=0&limit=100 ``` **参数说明：** - `skip`: 跳过的记录数（默认：0） - `limit`: 返回的记录数（默认：100，最大：1000） #### 获取指定用户 ```http GET /api/v1/users/{user_id} ``` #### 创建用户 ```http POST /api/v1/users/create Content-Type: application/json { "username": "testuser", "email": "test@example.com", "password": "password123", "full_name": "Test User" } ``` #### 更新用户 ```http POST /api/v1/users/edit?user_id={user_id} Content-Type: application/json { "username": "updateduser", "email": "updated@example.com", "full_name": "Updated User" } ``` #### 删除用户 ```http GET /api/v1/users/{user_id} ``` ## 🧪 测试 ### 使用HTTP测试文件 项目提供了 `test_main.http` 文件，你可以使用支持HTTP文件的IDE（如IntelliJ IDEA、VS Code等）直接运行测试： ```http # 测试根路径 GET http://127.0.0.1:8000/ Accept: application/json ### # 测试健康检查 GET http://127.0.0.1:8000/health Accept: application/json ### # 测试API健康检查 GET http://127.0.0.1:8000/api/v1/health/ Accept: application/json ### # 测试数据库健康检查 GET http://127.0.0.1:8000/api/v1/health/db Accept: application/json ``` ### 使用pytest进行单元测试 ```bash # 安装测试依赖 pip install -r requirements-dev.txt # 运行所有测试 pytest # 运行测试并显示详细输出 pytest -v # 运行测试并生成覆盖率报告 pytest --cov=app --cov-report=html # 运行特定测试文件 pytest tests/test_users.py # 运行特定测试函数 pytest tests/test_users.py::test_create_user ``` ## 🔧 开发指南 ### 添加新的数据模型 1. 在 `app/database/models/` 目录下创建新的模型文件 2. 继承 `BaseModel` 类 3. 定义表结构和字段 **示例：** ```python # app/database/models/product.py from sqlalchemy import Column, Integer, String, DateTime from app.database.models.base import BaseModel class Product(BaseModel): __tablename__ = "products" id = Column(Integer, primary_key=True, index=True) name = Column(String(100), nullable=False) description = Column(String(500)) price = Column(Integer, nullable=False) ``` ### 添加新的API端点 1. 在 `app/api/v1/endpoints/` 目录下创建新的端点文件 2. 在 `app/api/v1/api.py` 中注册路由 3. 创建对应的Schema和Service **示例：** ```python # app/api/v1/endpoints/products.py from fastapi import APIRouter, Depends from sqlalchemy.orm import Session from app.api.dependencies import get_db from app.schemas.response import ResponseModel router = APIRouter() @router.get("/", response_model=ResponseModel) def get_products(db: Session = Depends(get_db)): """获取产品列表""" # 实现逻辑 pass ``` ### 添加新的业务逻辑 1. 在 `app/logic/services/` 目录下创建新的服务类 2. 实现业务逻辑方法 3. 在API端点中调用服务 **示例：** ```python # app/logic/services/product_service.py from sqlalchemy.orm import Session class ProductService: def get_products(self, db: Session, skip: int = 0, limit: int = 100): """获取产品列表""" # 实现业务逻辑 pass ``` ## 🚀 部署 ### Docker部署 1. 创建 `Dockerfile`： ```dockerfile FROM python:3.9-slim # 安装系统依赖 RUN apt-get update && apt-get install -y \ libgl1-mesa-glx \ libglib2.0-0 \ libsm6 \ libxext6 \ libxrender-dev \ libgomp1 \ && rm -rf /var/lib/apt/lists/* WORKDIR /app # 复制依赖文件 COPY requirements.txt . # 安装Python依赖 RUN pip install --no-cache-dir -r requirements.txt # 复制应用代码 COPY . . # 创建必要的目录 RUN mkdir -p models uploads results logs # 暴露端口 EXPOSE 8000 # 启动命令 CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"] ``` 2. 构建和运行： ```bash # 构建镜像 docker build -t saas-python . # 运行容器 docker run -d -p 8000:8000 --name saas-app saas-python # 使用docker-compose（推荐） docker-compose up -d ``` ### 生产环境配置 1. **安全配置**： - 设置 `DEBUG=false` - 使用强密码的 `SECRET_KEY` - 配置生产环境的数据库连接 - 限制CORS策略 2. **性能优化**： - 调整数据库连接池大小 - 配置日志级别为 `WARNING` 或 `ERROR` - 使用反向代理（如Nginx） 3. **监控和日志**： - 配置日志文件轮转 - 设置应用监控 - 配置健康检查 ### 使用Gunicorn部署 ```bash # 安装gunicorn pip install gunicorn # 运行应用 gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000 ``` ## 🔍 故障排除 ### 常见问题 1. **数据库连接失败** - 检查达梦数据库服务是否启动 - 验证数据库连接参数 - 确认防火墙设置 2. **端口被占用** ```bash # Windows netstat -ano | findstr :8000 # Linux/Mac lsof -i :8000 ``` 5. **依赖安装失败** ```bash # 升级pip python -m pip install --upgrade pip # 清理缓存 pip cache purge ``` ### 日志查看 ```bash # 查看应用日志 tail -f logs/app.log # 查看错误日志 grep "ERROR" logs/app.log # 实时监控日志 tail -f logs/app.log | grep -E "(ERROR|WARNING)" ``` ## 🤝 贡献指南 我们欢迎所有形式的贡献！ ### 贡献流程 1. **Fork 项目** 2. **创建功能分支** (`git checkout -b feature/AmazingFeature`) 3. **提交更改** (`git commit -m 'Add some AmazingFeature'`) 4. **推送到分支** (`git push origin feature/AmazingFeature`) 5. **打开 Pull Request** ### 代码规范 - 遵循PEP 8代码风格 - 添加适当的注释和文档字符串 - 编写单元测试 - 确保所有测试通过 ### 提交信息规范 使用清晰的提交信息： ``` feat: 添加用户认证功能 fix: 修复数据库连接池问题 docs: 更新API文档 style: 格式化代码 refactor: 重构用户服务 test: 添加用户测试用例 ``` ## 📄 许可证 本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。 ## 📞 联系方式 如有问题或建议，请通过以下方式联系： - 📧 **邮箱**: [your-email@example.com] - 🐛 **提交Issue**: [GitHub Issues](https://github.com/your-repo/issues) - 💬 **讨论**: [GitHub Discussions](https://github.com/your-repo/discussions) - 📖 **文档**: [项目Wiki](https://github.com/your-repo/wiki) ## 🙏 致谢 感谢以下开源项目的支持： - [FastAPI](https://fastapi.tiangolo.com/) - 现代、快速的Web框架 - [SQLAlchemy](https://www.sqlalchemy.org/) - Python SQL工具包 - [Pydantic](https://pydantic-docs.helpmanual.io/) - 数据验证库 - [达梦数据库](https://www.dameng.com/) - 国产数据库 --- **saas-Python** - 让达梦数据库开发更简单！ 🚀 *如果这个项目对你有帮助，请给我们一个 ⭐️*