diff --git a/README.md b/README.md new file mode 100644 index 0000000..985772d --- /dev/null +++ b/README.md @@ -0,0 +1,267 @@ +# 学生管理系统 - 后端说明文档 + +## 一、项目简介 + +本项目是一个基于 **Spring Boot + MyBatis-Plus** 开发的学生管理系统后端，提供班级管理、学生信息管理等核心功能，支持分页查询、条件筛选、增删改查等操作，前后端分离架构，适配前端 Vue 项目。 + +## 二、技术栈 + +| 技术 | 版本 | 说明 | +| ----------------- | ------ | ---------------------------------- | +| Spring Boot | 2.7.x | 快速开发框架 | +| MyBatis-Plus | 3.5.x | MyBatis 增强工具 | +| MySQL | 8.0 | 关系型数据库 | +| Lombok | 1.18.x | 简化 Java 代码（getter/setter 等） | +| Spring Validation | 2.7.x | 参数校验（后续优化用） | + +## 三、项目结构 + +```plaintext +src/ +├── main/ +│ ├── java/ +│ │ └── com/example/studentmanagement/ +│ │ ├── StudentManagementApplication.java // 启动类 +│ │ ├── common/ // 公共类（后续优化用：统一响应、状态码） +│ │ ├── controller/ // 控制器（接口层） +│ │ │ ├── ClassController.java // 班级管理接口 +│ │ │ └── StudentController.java // 学生管理接口 +│ │ ├── dto/ // 数据传输对象（后续优化用：接收前端参数） +│ │ ├── entity/ // 实体类（对应数据库表） +│ │ │ ├── GradeClass.java // 班级实体 +│ │ │ └── Student.java // 学生实体 +│ │ ├── mapper/ // Mapper接口（MyBatis-Plus） +│ │ │ ├── ClassMapper.java +│ │ │ └── StudentMapper.java +│ │ ├── service/ // 服务层 +│ │ │ ├── ClassService.java // 班级服务接口 +│ │ │ ├── StudentService.java // 学生服务接口 +│ │ │ └── impl/ // 服务实现类 +│ │ └── config/ // 配置类 +│ │ └── MyBatisConfig.java // MyBatis-Plus配置（分页插件等） +│ └── resources/ +│ ├── application.properties // 配置文件（数据库、端口等） +│ └── mapper/ // MyBatis XML映射文件（若有） +└── test/ // 测试类（可选） +``` + +## 四、核心功能说明 + +### 1. 班级管理 + +- 查询班级列表（按年级筛选、模糊查询班级名称） +- 新增班级 +- 编辑班级信息 +- 删除班级（校验班级下是否有学生，有则禁止删除） +- 检查班级是否有学生（用于删除前校验） + +### 2. 学生管理 + +- 分页查询学生列表（支持年级、班级、姓名模糊筛选） +- 新增学生 +- 编辑学生信息 +- 批量删除学生 + +## 五、接口文档（当前版本） + +### 1. 班级管理接口 + +| 接口地址 | 请求方式 | 参数说明 | 返回结果 | +| ---------------------- | -------- | ------------------------------------------------------ | -------------------------------------- | +| /api/class/list | GET | grade（年级，必填）、name（班级名称，可选） | 班级列表（List） | +| /api/class/add | POST | name（班级名称）、grade（年级）、headTeacher（班主任） | 新增结果（布尔值） | +| /api/class/edit | PUT | id（班级 ID，必填）、name、grade、headTeacher | 编辑结果（布尔值） | +| /api/class/delete/{id} | DELETE | id（班级 ID，路径参数） | 删除结果（布尔值） | +| /api/class/check | GET | classId（班级 ID，必填） | 是否有学生（{hasStudent: true/false}） | + +### 2. 学生管理接口 + +| 接口地址 | 请求方式 | 参数说明 | 返回结果 | +| ------------------------- | -------- | ------------------------------------------------------------ | -------------------------------------------- | +| /api/student/list | GET | page（页码，必填）、size（每页条数，必填）、grade（年级）、classId（班级 ID）、name（学生姓名） | 分页学生列表（{list: [...], total: 总条数}） | +| /api/student/add | POST | name、age、gender、address、grade、classId | 新增结果（布尔值） | +| /api/student/edit | PUT | id（学生 ID，必填）、name、age、gender、address、grade、classId | 编辑结果（布尔值） | +| /api/student/delete/{ids} | DELETE | ids（学生 ID 逗号分隔，如 1,2,3） | 删除结果（布尔值） | + +## 六、配置说明（application.properties） + +```properties +# 服务器端口（默认8080，若冲突可修改） +server.port=8080 + +# 数据库连接配置（需修改为你的MySQL信息） +spring.datasource.url=jdbc:mysql://localhost:3306/student_management?useUnicode=true&characterEncoding=UTF-8&serverTimezone=Asia/Shanghai +spring.datasource.username=root # 你的MySQL用户名 +spring.datasource.password=123456 # 你的MySQL密码 +spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver + +# MyBatis-Plus配置 +# 实体类别名扫描包（对应entity目录） +mybatis-plus.type-aliases-package=com.example.studentmanagement.entity +# XML映射文件路径（若有） +mybatis-plus.mapper-locations=classpath:mapper/*.xml +# 开启驼峰命名转换（如数据库字段class_id -> 实体类classId） +mybatis-plus.configuration.map-underscore-to-camel-case=true +``` + +## 七、使用说明 + +### 1. 环境准备 + +- JDK 8+ +- MySQL 8.0 +- Maven 3.6+（或使用 IDEA 自带 Maven） + +### 2. 数据库初始化 + +1. 创建数据库 student_management + + ```sql + CREATE DATABASE IF NOT EXISTS student_management DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; + ``` + + + +2. 执行数据库脚本（创建班级表class和学生表student） + + ```sql + -- 班级表 + CREATE TABLE `class` ( + `id` bigint NOT NULL AUTO_INCREMENT COMMENT '班级ID', + `name` varchar(50) NOT NULL COMMENT '班级名称', + `grade` int NOT NULL COMMENT '年级', + `head_teacher` varchar(50) DEFAULT NULL COMMENT '班主任', + PRIMARY KEY (`id`) + ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='班级表'; + + -- 学生表（关联班级表id） + CREATE TABLE `student` ( + `id` bigint NOT NULL AUTO_INCREMENT COMMENT '学生ID', + `name` varchar(50) NOT NULL COMMENT '姓名', + `age` int DEFAULT NULL COMMENT '年龄', + `gender` int DEFAULT NULL COMMENT '性别（1-男，2-女）', + `address` varchar(255) DEFAULT NULL COMMENT '家庭住址', + `grade` int NOT NULL COMMENT '年级', + `class_id` bigint DEFAULT NULL COMMENT '班级ID（关联class表id）', + PRIMARY KEY (`id`), + KEY `idx_class_id` (`class_id`), + CONSTRAINT `fk_student_class` FOREIGN KEY (`class_id`) REFERENCES `class` (`id`) ON DELETE SET NULL + ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='学生表'; + ``` + + + +3. 执行测试数据脚本（批量插入班级和学生数据） + + ```sql + -- 切换到你的数据库（请确保已创建 student_management 数据库） + USE student_management; + + -- 清空现有数据（可选，首次执行可跳过，避免重复插入） + -- TRUNCATE TABLE student; + -- TRUNCATE TABLE class; + + -- 1. 插入班级数据（3个年级，每个年级3个班，共9个班级） + INSERT INTO class (name, grade, head_teacher) VALUES + -- 一年级班级 + ('一年级一班', 1, '王老师'), + ('一年级二班', 1, '李老师'), + ('一年级三班', 1, '张老师'), + -- 二年级班级 + ('二年级一班', 2, '赵老师'), + ('二年级二班', 2, '孙老师'), + ('二年级三班', 2, '周老师'), + -- 三年级班级 + ('三年级一班', 3, '吴老师'), + ('三年级二班', 3, '郑老师'), + ('三年级三班', 3, '钱老师'); + + -- 2. 插入学生数据（每个班级5名学生，共45名学生，关联正确的 class_id） + INSERT INTO student (name, age, gender, address, grade, class_id) VALUES + -- 一年级一班（class_id=1） + ('张三', 6, 1, '北京市海淀区中关村大街', 1, 1), + ('李四', 7, 1, '北京市朝阳区建国路', 1, 1), + ('王五', 6, 2, '北京市西城区金融街', 1, 1), + ('赵六', 7, 2, '北京市东城区王府井大街', 1, 1), + ('孙七', 6, 1, '北京市丰台区马家堡东路', 1, 1), + + -- 一年级二班（class_id=2） + ('周八', 6, 1, '上海市黄浦区南京东路', 1, 2), + ('吴九', 7, 2, '上海市徐汇区淮海中路', 1, 2), + ('郑十', 6, 1, '上海市静安区静安寺路', 1, 2), + ('钱十一', 7, 2, '上海市长宁区虹桥路', 1, 2), + ('冯十二', 6, 1, '上海市普陀区中山北路', 1, 2), + + -- 一年级三班（class_id=3） + ('陈十三', 6, 2, '广州市天河区天河路', 1, 3), + ('褚十四', 7, 1, '广州市越秀区北京路', 1, 3), + ('卫十五', 6, 2, '广州市海珠区江南大道', 1, 3), + ('蒋十六', 7, 1, '广州市荔湾区上下九路', 1, 3), + ('沈十七', 6, 2, '广州市白云区机场路', 1, 3), + + -- 二年级一班（class_id=4） + ('韩十八', 7, 1, '深圳市福田区深南中路', 2, 4), + ('杨十九', 8, 2, '深圳市南山区科技园', 2, 4), + ('朱二十', 7, 1, '深圳市罗湖区东门步行街', 2, 4), + ('秦二一', 8, 2, '深圳市盐田区沙头角', 2, 4), + ('尤二二', 7, 1, '深圳市宝安区宝安大道', 2, 4), + + -- 二年级二班（class_id=5） + ('许二三', 7, 2, '杭州市西湖区西湖大道', 2, 5), + ('何二四', 8, 1, '杭州市上城区解放路', 2, 5), + ('吕二五', 7, 2, '杭州市拱墅区武林路', 2, 5), + ('施二六', 8, 1, '杭州市滨江区江南大道', 2, 5), + ('张二七', 7, 2, '杭州市萧山区市心路', 2, 5), + + -- 二年级三班（class_id=6） + ('孔二八', 7, 1, '成都市锦江区春熙路', 2, 6), + ('曹二九', 8, 2, '成都市青羊区宽窄巷子', 2, 6), + ('严三十', 7, 1, '成都市金牛区天府大道', 2, 6), + ('华三一', 8, 2, '成都市武侯区武侯祠大街', 2, 6), + ('金三二', 7, 1, '成都市成华区建设路', 2, 6), + + -- 三年级一班（class_id=7） + ('魏三三', 8, 2, '武汉市武昌区东湖路', 3, 7), + ('陶三四', 9, 1, '武汉市汉口区中山大道', 3, 7), + ('姜三五', 8, 2, '武汉市汉阳古琴台路', 3, 7), + ('戚三六', 9, 1, '武汉市洪山区光谷广场', 3, 7), + ('谢三七', 8, 2, '武汉市青山区和平大道', 3, 7), + + -- 三年级二班（class_id=8） + ('邹三八', 8, 1, '西安市雁塔区大雁塔路', 3, 8), + ('喻三九', 9, 2, '西安市碑林区南大街', 3, 8), + ('柏四十', 8, 1, '西安市莲湖区北大街', 3, 8), + ('水四一', 9, 2, '西安市未央区未央路', 3, 8), + ('窦四二', 8, 1, '西安市新城区解放路', 3, 8), + + -- 三年级三班（class_id=9） + ('章四三', 8, 2, '南京市鼓楼区中山路', 3, 9), + ('云四四', 9, 1, '南京市玄武区玄武湖路', 3, 9), + ('苏四五', 8, 2, '南京市秦淮区夫子庙路', 3, 9), + ('潘四六', 9, 1, '南京市建邺区河西大街', 3, 9), + ('葛四七', 8, 2, '南京市雨花台区雨花大道', 3, 9); + + ``` + +### 3. 项目启动 + +1. 用 IDEA 打开项目，等待 Maven 依赖加载完成。 +2. 修改 `application.properties` 中的数据库连接信息（用户名、密码）。 +3. 运行 `StudentManagementApplication.java` 的 `main` 方法，启动项目。 +4. 启动成功后，访问 `http://localhost:8080/api/class/list?grade=1`，若返回班级列表则表示运行正常。 + +## 八、后续优化方向 + +1. **参数校验**：引入 `Spring Validation`，用注解（如 `@Min`、`@NotBlank`）替代手动参数判断。 +2. **统一响应格式**：创建 `ApiResult` 统一返回结构（状态码、提示信息、数据），替代 `HashMap`。 +3. **DTO/VO 分离**：用 DTO（数据传输对象）接收前端参数，VO（视图对象）封装返回数据，隐藏后端实体细节。 +4. **全局异常处理**：用 `@RestControllerAdvice` 捕获异常，统一返回错误信息。 +5. **接口文档自动生成**：引入 Swagger/knife4j，自动生成接口文档，方便前后端联调。 +6. **权限控制**：引入 Spring Security 或 Shiro，实现用户登录、权限校验。 + +## 九、注意事项 + +1. 数据库表名、字段名采用下划线命名，实体类采用驼峰命名，MyBatis-Plus 会自动转换（需开启 `map-underscore-to-camel-case`）。 +2. 分页功能依赖 MyBatis-Plus 分页插件，已在 `MyBatisConfig.java` 中配置，若分页无效需检查该配置。 +3. 前端请求需配置代理（如 Vite 代理），将 `/api` 前缀转发到后端地址（`http://localhost:8080`），避免跨域问题。 +4. 删除班级时会校验班级下是否有学生，若有则返回删除失败，需先删除该班级下的学生或转移学生到其他班级。 \ No newline at end of file