# student_manage **Repository Path**: yll_zl/student_manage ## Basic Information - **Project Name**: student_manage - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: student - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-04-20 - **Last Updated**: 2026-05-11 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README ## 一、技术栈 - FastAPI - SQLAlchemy 2.0（异步，支持 aiomysql/PyMySQL） - python-dotenv（环境变量管理） - uvicorn（ASGI 服务器） ## 二、快速启动 ### 1. 环境准备 - Python 3.8+ - MySQL 5.7+ / 8.0+ ### 2. 安装依赖 ```bash pip install -r requirements.txt ``` ### 3. 配置环境变量 ```bash # 复制示例配置文件 cp .env.example .env # 编辑 .env 文件，填写 MySQL 连接信息（示例） DATABASE_URL=mysql+aiomysql://用户名:密码@127.0.0.1:3306/数据库名 ``` ### 4. 启动服务 ```bash # 开发环境（热重载） - 新结构 uvicorn app.main:app --reload # 开发环境（热重载） - 旧结构（兼容） uvicorn main:app --reload # 生产环境（可选） uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4 ``` ### 5. 验证启动 - 健康检查接口：GET http://127.0.0.1:8000/health - 成功返回：{"status": "ok"} - Swagger 接口文档：http://127.0.0.1:8000/docs - 可查看所有模块接口并在线调试 ## 三、项目核心配置 ### 1. 数据库配置 - 从环境变量读取数据库连接信息，支持异步 / 同步模式 - 实现 get_db 依赖注入，每个请求自动创建 / 关闭数据库会话，避免连接泄漏 ### 2. 全局异常处理 - 所有接口返回格式统一： - 成功响应：{"code": 0, "message": "success", "data": {}} - 错误响应：{"code": 500, "message": "错误描述"} ### 3. 日志配置 - 使用 logging 模块实现日志输出 - 日志同时输出到 app.log 文件和控制台 ### 4. 路由前缀规范 - 各模块路由前缀严格遵循以下规则： - 学生模块：/students - 成绩模块：/scores - 就业模块：/employments - 班级模块：/classes - 教师模块：/teachers - 统计模块：/statistics ## 四、项目目录结构 ### 4.1 新的MVC分层结构（推荐） ```plaintext student_manage/ ├── app/ # 应用主包 │ ├── __init__.py │ ├── main.py # FastAPI应用入口 │ ├── core/ # 核心配置层 │ │ ├── __init__.py │ │ ├── config.py # 配置管理 │ │ ├── database.py # 数据库连接 │ │ └── logger.py # 日志配置 │ ├── models/ # Model层（数据模型） │ │ ├── __init__.py │ │ ├── base.py # 基础模型 │ │ ├── enums.py # 枚举类型 │ │ ├── events.py # 模型事件监听器 │ │ ├── student.py # 学生模型 │ │ ├── class_model.py # 班级模型 │ │ ├── score.py # 成绩模型 │ │ ├── teacher.py # 教师模型 │ │ └── employment.py # 就业模型 │ ├── schemas/ # Schema层（数据验证） │ │ ├── __init__.py │ │ ├── common.py # 通用Schema │ │ ├── student.py # 学生Schema │ │ ├── class_model.py # 班级Schema │ │ ├── score.py # 成绩Schema │ │ ├── teacher.py # 教师Schema │ │ ├── employment.py # 就业Schema │ │ └── ai_assistant.py # AI助手Schema │ ├── services/ # Service层（业务逻辑） │ │ ├── __init__.py │ │ ├── student_service.py # 学生服务 │ │ ├── class_service.py # 班级服务 │ │ ├── score_service.py # 成绩服务 │ │ ├── teacher_service.py # 教师服务 │ │ ├── employment_service.py# 就业服务 │ │ └── ai_assistant_service.py # AI助手服务 │ ├── api/ # View层（API路由） │ │ ├── __init__.py │ │ ├── student/ # 学生路由 │ │ ├── classes/ # 班级路由 │ │ ├── score/ # 成绩路由 │ │ ├── teacher/ # 教师路由 │ │ ├── employment/ # 就业路由 │ │ ├── statistics/ # 统计路由 │ │ └── ai_assistant/ # AI助手路由 │ ├── utils/ # 工具函数 │ │ └── __init__.py │ └── logs/ # 日志目录 ├── frontend/ # 前端文件 ├── requirements.txt # 依赖包 ├── migrate_imports.py # Import路径迁移脚本 ├── README.md # 项目说明文档 └── .env.example # 环境变量示例 ``` ### 4.2 旧项目结构（保留用于过渡期） ```plaintext ├── main.py # 应用入口，挂载所有子模块路由、配置全局中间件 ├── database.py # 数据库引擎配置、会话依赖（get_db） ├── config.py # 环境变量读取、全局配置项 ├── requirements.txt # 项目依赖清单 ├── .env.example # 环境变量示例文件 ├── app.log # 日志文件（自动生成） ├── docker-compose.yml # Docker快速部署配置（可选） ├── README.md # 项目说明文档 └── api/ # 所有接口模块统一存放（核心软件包） ├── students/ # 学生模块（路由/模型/服务） ├── scores/ # 成绩模块 ├── employment/ # 就业模块 ├── classes/ # 班级模块 ├── teacher/ # 教师模块 ├── statistics/ # 统计模块 └── ai_assistant/ # ai助手模块 ``` ### 4.3 MVC分层说明 #### Model层（app/models/） - **职责**: 数据模型定义，与数据库表映射 - **命名规范**: 使用snake_case，如`student.py`, `class_model.py` - **包含内容**: - `base.py`: 基础模型类 - `enums.py`: 枚举类型定义 - `events.py`: 模型事件监听器 - 各业务模块的模型文件 #### Schema层（app/schemas/） - **职责**: 数据验证和序列化，Pydantic模型 - **命名规范**: 使用snake_case，如`student.py`, `common.py` - **包含内容**: - `common.py`: 通用响应模型 - 各业务模块的Schema定义 - 请求/响应数据验证 #### Service层（app/services/） - **职责**: 业务逻辑处理，数据库操作 - **命名规范**: 使用`_service.py`格式 - **包含内容**: - 各业务模块的服务函数 - CRUD操作 - 业务规则实现 #### View层（app/api/） - **职责**: API路由定义，请求/响应处理 - **命名规范**: 使用snake_case，如`student/`, `classes/` - **包含内容**: - 各业务模块的路由文件 - HTTP请求处理 - 参数验证 #### Core层（app/core/） - **职责**: 核心配置管理 - **包含内容**: - `config.py`: 配置管理 - `database.py`: 数据库连接 - `logger.py`: 日志配置 ## 五、集成规则 - 子模块间相互调用需通过服务层函数实现，避免循环导入（如学生更新同步就业冗余字段） - 所有响应均基于统一的 BaseResponse Pydantic 模型 - 各子模块需正确导出 router 对象，确保 main.py 可正常挂载 ## 六、交付清单 - main.py（应用入口） - database.py（数据库引擎与会话） - config.py（环境变量读取） - requirements.txt（依赖清单） - .env.example（环境变量示例） - docker-compose.yml（可选） - README.md（本文件） - 健康检查接口：GET /health ## 七、协作与测试 - 所有开发人员需确保子模块的 router 对象正确导出，便于主程序集成 - 提供全局测试环境配置，支持运行所有模块的单元测试 ## 八、项目结构重构说明 ### 8.1 重构概述 本项目已从传统的扁平结构重构为符合MVC架构的分层结构，遵循PEP8命名规范。新结构提供了更清晰的代码组织、更好的可维护性和可扩展性。 ### 8.2 重构内容 1. **创建app主包**: 将所有应用代码集中到app目录下 2. **分层架构**: - `core/`: 核心配置（config, database, logger） - `models/`: 数据模型层 - `schemas/`: 数据验证层 - `services/`: 业务逻辑层 - `api/`: API路由层 - `utils/`: 工具函数层 3. **PEP8规范**: 统一命名规范，文件名使用snake_case 4. **模块化拆分**: 将models.py拆分为多个独立的模型文件 ### 8.3 Import路径变更 ```python # Model导入 from app.models import Student, GenderEnum # Schema导入 from app.schemas.student import StudentCreate, StudentUpdate # Service导入 from app.services.student_service import get_student_by_id # Core导入 from app.core.config import Settings from app.core.database import get_db from app.core.logger import logger ``` ### 8.4 迁移指南 1. **运行迁移脚本**: ```bash python migrate_imports.py ``` 该脚本会自动更新大部分import路径 2. **手动检查**: - 检查相对导入（如`from .schemas import`）是否正确 - 验证所有API接口功能正常 - 确保日志和数据库连接正常 3. **测试**: ```bash # 使用新结构启动 uvicorn app.main:app --reload # 访问健康检查 curl http://localhost:8000/ # 查看API文档 # 浏览器访问 http://localhost:8000/docs ``` 4. **清理旧文件**（确认新结构正常后）: ```bash # 删除旧的models.py rm models.py # 删除旧的config.py rm config.py # 删除旧的database.py rm database.py # 删除旧的logger_config.py rm logger_config.py # 删除旧的main.py（如果需要） rm main.py ``` ### 8.5 优势 1. **清晰的分层**: Model、Schema、Service、View各司其职 2. **降低耦合**: 模块间依赖关系更清晰 3. **易于扩展**: 新增模块遵循统一模式 4. **代码复用**: 通用功能集中管理 5. **团队协作**: 统一的代码结构和规范 ### 8.6 注意事项 - 原有的api、models等目录暂时保留，待完成迁移后可删除 - 数据库模型结构未改变，无需数据迁移 - 前端API调用路径保持不变 - 建议在开发环境充分测试后再部署到生产环境 ### 8.7 待完成任务 - [x] 更新所有Router文件的import路径 ✅ - [x] 更新所有Service文件的import路径 ✅ - [x] 更新所有Schema文件的import路径 ✅ - [ ] 测试所有API接口 - [ ] 删除旧的文件和目录 - [ ] 更新相关文档 ## 九、常见问题 ### Q1: 如何在旧结构和新结构之间切换？ A: 通过修改启动命令即可： ```bash # 新结构 uvicorn app.main:app --reload # 旧结构 uvicorn main:app --reload ``` ### Q2: 迁移后如何确保功能正常？ A: 建议按以下步骤验证： 1. 启动服务，检查日志无错误 2. 访问健康检查接口: `GET /` 3. 访问Swagger文档: `http://localhost:8000/docs` 4. 测试各个模块的CRUD接口 5. 检查数据库操作是否正常 ### Q3: 遇到import错误怎么办？ A: 检查以下几点： 1. 确保文件路径正确 2. 检查`__init__.py`文件是否存在 3. 验证模块名是否正确（注意`class_model`不是`class`，因为`class`是Python关键字） 4. 查看详细的错误堆栈信息 ## 十、参考资源 - [FastAPI官方文档](https://fastapi.tiangolo.com/) - [SQLAlchemy 2.0文档](https://docs.sqlalchemy.org/en/20/) - [PEP 8风格指南](https://peps.python.org/pep-0008/) - [MVC架构模式](https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller)