SpringBoot+Vue全栈项目实战：大学生考勤系统毕设方案详解

开篇先说个大实话：不管你是准备做Java Web毕设，还是想拿一套完整的全栈项目练手，“SpringBoot+Vue”这个组合都是一个投入产出比非常高的选择。我见过太多毕设项目要么后台堆了一堆JSP，要么前端纯静态页面糊弄过去，最后答辩时被老师一问接口设计就卡壳。而我今天要拆解的这套大学生考勤系统，属于典型的“前后端分离+权限控制+定时任务+报表统计”全要素项目，它把Java Web方向的核心考点几乎全占了：SpringBoot骨架、MyBatis-Plus持久层、JWT鉴权、Vue全家桶、SQL初始化脚本、接口文档。所以你拿到的不只是一堆代码，而是一整套可以讲清楚、改得动、跑得起来的完整毕设方案。这篇文章我会把这个项目的设计思路、数据库结构、后端实现、前端配合、接口文档写法以及部署踩坑全部过一遍，适合正在做毕设的在校生，也适合想补全栈经验的新人。

1. 项目定位与整体技术选型

1.1 为什么是SpringBoot + Vue，而不是其他组合

先聊选型。大学生考勤系统这类业务，本质上是一个典型的“管理信息系统”，它的核心诉求是：用户分角色、数据要录要查、流程要审批、结果要统计。这类系统最适合的技术形态，就是后端提供API、前端做交互界面的前后端分离架构。

SpringBoot能成为Java Web毕设的绝对主流，不是因为名字好听，而是因为它把Spring生态里那些让人头疼的配置基本都抹平了。你用Spring MVC单独搭项目要配一堆XML、要做嵌入式容器整合，而SpringBoot直接内嵌Tomcat，一个main方法就能起服务。再加上spring-boot-starter-web、spring-boot-starter-validation这些现成starter，依赖管理变得极其省事。对于毕设来说，你花在“配置环境”上的时间越少，留给“业务逻辑”的时间就越多，这直接决定了你项目的完成度。

再就是MyBatis-Plus。很多毕设项目还在手写XML映射文件，不是说不行，但对于考勤系统这种以单表操作和简单联查为主的场景，MyBatis-Plus的BaseMapper提供了一整套CRUD方法，分页查询用Page对象一调就完事，代码量直接砍掉一半。我建议你在答辩时提一句“使用MyBatis-Plus减少了大量样板代码，让团队把精力聚焦在业务规则上”，这种表述比背概念更能让老师觉得你做过功课。

Vue那边的道理类似。Vue 2.x还是Vue 3.x，我的建议是直接用Vue 3 + Vite + Element Plus。因为这是目前企业里新建项目的默认取向，也是很多新教程在用的方案。Vue的响应式机制让“学生签到状态列表”这种高频变动的数据渲染不需要你手动操作DOM，配合Axios做接口请求，前端逻辑能控制得非常干净。如果你对Vue 3的组合式API不熟，就把它当成“把代码按功能组织成小函数块”的思路，比Vue 2的Options API更直观。

1.2 项目的整体架构长什么样

这套系统我倾向于按标准的三层架构去组织，同时把前后端彻底拆开：

• 后端：SpringBoot 2.7.x + MyBatis-Plus + MySQL 8.0 + JWT + Lombok，提供纯RESTful API。
• 前端：Vue 3 + Vite + Vue Router + Pinia + Element Plus + Axios，构建后生成静态文件，可部署在Nginx或任意静态服务器。
• 数据层：采用MySQL数据库，SQL脚本里包含建库、建表、初始化数据三个部分。
• 文档：接口文档使用Markdown或放一份Postman导出的JSON集合，用于描述所有接口的请求与响应。

整体请求链路是：浏览器访问Vue页面 -> Axios携带JWT Token -> SpringBoot拦截器校验 -> Controller接收参数 -> Service处理业务 -> Mapper操作数据库 -> 结果封装后返回前端。

这里有个很关键的工程化思路：前后端通过接口约定耦合，而不是通过页面跳转耦合。前端写死的每个API地址，都必须能在接口文档里找到对应解释。这也是为什么这套项目里接口文档不是一个可有可无的附件，而是整个项目的“契约文件”。

1.3 这套项目适合什么人

如果你是快要交毕设的在校生，这个项目可以直接作为你的毕设原型，但我不建议原封不动地交。你可以根据自己学校的要求，把“考勤”的业务场景换成“实验室考勤”“自习室预约考勤”“运动会志愿者考勤”等，核心代码改动量不大，却能形成差异性。

如果你是想走Java开发岗的应届生，这个项目更适合作为“可以写进简历并且经得起深挖”的项目。考勤系统涉及权限、审批流、统计报表、定时任务、异常处理，这些都是面试官喜欢追问的点。你只要把项目里的任何一个模块（哪怕就是请假审批的状态流转）吃透，面试时都有东西可讲。

2. 系统功能模块设计与核心业务流程

2.1 角色权限设计：三种角色各管一摊

考勤系统的用户群体很固定：学生、教师（辅导员）、系统管理员。所以角色权限我用的是简单清晰的RBAC模型，没有引入Spring Security的完整体系，而是自己实现了一套基于JWT + 拦截器的轻量权限控制。这样做的考虑是：毕设项目的核心在于让逻辑可解释，而不是引入过度复杂的安全框架把项目搞得难以调试。

• 学生：登录后查看自己的考勤记录、请假记录，发起请假申请，修改个人密码。
• 教师/辅导员：查看所带班级的学生考勤列表，处理请假审批，按日期和班级维度统计考勤异常情况。
• 管理员：管理所有用户账号、班级信息、课程/节次信息，查看全站考勤汇总，导出报表。

这个设计有三个好处。第一，每一个角色的功能边界清晰，前端菜单可以按角色动态渲染；第二，数据权限天然收敛，学生只能查自己的记录，教师只能看本班记录，管理员不受限制；第三，答辩时你可以明确说“本项目基于RBAC模型设计了三类角色，权限粒度控制在接口级别”，这一句话就展示了你的系统设计能力。

2.2 考勤的核心业务规则

考勤系统的核心不是“记录”而是“规则”。我和很多人聊过，大家做考勤系统总是先想着怎么把签到记录存下来，却忽略了业务规则的设定。实际上，老师最关心的问题是：怎么知道一个学生这节课算不算缺勤？这里我把考勤状态设计为四种：正常、迟到、早退、缺勤。

判断规则如下：

• 学生点击签到，若当前时间早于上课时间，状态为“正常”。
• 若当前时间晚于上课时间开始阈值（比如设置迟到阈值15分钟），则状态为“迟到”。
• 若学生根本没有提交签到请求，由定时任务在下课后自动判定为“缺勤”。
• 早退比较特殊，一般依赖于签退功能。学生在下课前可以点击“签退”，若提交时间早于下课时间超过一定阈值，判定为“早退”。

这里有一个很容易被忽略的细节：考勤判定的时间基准必须统一。如果前端页面用的是浏览器本地时间，后端用的是服务器时间，而学生电脑时间不准，就会导致同一时刻前后端判断不一致。所以我在后端一律取服务器当前时间（LocalDateTime.now()），前端提交考勤动作时只传课堂ID和操作类型，绝不依赖前端传时间。

2.3 请假流程：从学生发起到教师审批

请假审批是考勤系统里最有代表性的“流程型业务”。学生发起请假申请时，需要选择请假开始日期、结束日期、请假类型（病假/事假/其他）以及说明原因。提交后记录状态为“待审批”，教师端能看到待办列表，点“通过”或“驳回”并填写审批意见。

这里我在数据库里设计了一张leave_record表，状态字段用int存储：0待审批、1已通过、2已驳回。为什么不直接用字符串？因为数字状态在做统计聚合时更高效，而且和前端下拉框选项的value值能直接对应。审批完成后，系统需要反向关联考勤：如果请假时间段覆盖了某节课，则该课时的考勤状态自动视为“正常（请假）”。这个逻辑我是通过一个定时任务批量修正的，避免用户在审批通过后还要手动去改每一个考勤记录。

2.4 数据统计模块：让系统不止于记录

很多毕设项目做到最后，系统只能“录数据、查列表”，这其实是不够的。一个合格的考勤系统，统计报表是刚需。教师端和管理员端都应有“按班级、按日期范围”维度的统计能力，输出每个学生的出勤率、迟到次数、缺勤次数等指标。

实现上，我并没有在业务表里存冗余的统计数据，而是通过SQL聚合查询实时计算。比如要查“某班级近一个月的缺勤名单”，SQL大概长这样：

sql复制SELECT s.student_no, s.name, COUNT(*) AS absent_count
FROM attendance_record a
JOIN student s ON a.student_id = s.id
JOIN class_info c ON s.class_id = c.id
WHERE c.id = #{classId}
  AND a.attendance_status = 3
  AND a.attendance_date BETWEEN #{startDate} AND #{endDate}
GROUP BY s.student_no, s.name
HAVING COUNT(*) > 0
ORDER BY absent_count DESC;

这类查询语法简单，但对索引有要求。我给attendance_record表建了联合索引(student_id, attendance_date)，否则数据量过万后这个统计查询会明显变慢。

3. 数据库设计详解与SQL脚本解读

3.1 建表原则：宁可拆细，不要堆大

考勤系统的表数量不用太多，七八张核心表足够，但每一张表的设计都要经得起推敲。我把数据表分成了四类：基础档案类、业务记录类、流程审批类、系统支撑类。

• 基础档案类：sys_user（账号表）、student（学生档案）、teacher（教师档案）、class_info（班级表）、course_info（课程表）、semester_course（开课计划表，即某学期某班级有哪些课程）。
• 业务记录类：attendance_record（考勤记录表）、attendance_config（考勤规则配置表）。
• 流程审批类：leave_record（请假申请表）。
• 系统支撑类：sys_role、sys_menu、sys_role_menu，以及用户角色关联表，用于支撑轻量RBAC。

这种拆分方式的好处是：学生信息不依赖账号表，哪怕学生毕业了账号删除，历史考勤记录依然可以通过student_id关联到学生档案。很多初学者喜欢一个user表里把姓名、班级、角色全塞进去，短期开发是快了，但统计班级考勤时会发现SQL写得极其别扭。

3.2 核心表结构逐张拆解

我用三张最关键的表来说明设计的核心用意。

第一张是sys_user，这是登录入口表：

sql复制CREATE TABLE sys_user (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    username VARCHAR(50) NOT NULL UNIQUE COMMENT '登录账号',
    password VARCHAR(255) NOT NULL COMMENT '密码密文',
    user_type TINYINT NOT NULL COMMENT '1-学生 2-教师 3-管理员',
    status TINYINT DEFAULT 1 COMMENT '1-正常 0-禁用',
    create_time DATETIME DEFAULT CURRENT_TIMESTAMP,
    update_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);

密码我统一用BCrypt加密存储，不是MD5。这个选择在答辩时可以重点讲：MD5加盐虽然也不错，但BCrypt内置随机盐且计算开销可控，是现代应用更推荐的做法。

第二张是核心业务表attendance_record，每一行代表“某学生在某节课的一次考勤结果”：

sql复制CREATE TABLE attendance_record (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    student_id BIGINT NOT NULL,
    course_id BIGINT NOT NULL,
    schedule_date DATE NOT NULL,
    period_no INT NOT NULL COMMENT '第几节课',
    attendance_status TINYINT NOT NULL COMMENT '1-正常 2-迟到 3-缺勤 4-早退',
    check_time DATETIME NULL COMMENT '实际签到时间',
    source TINYINT DEFAULT 1 COMMENT '1-自动 2-手动补录',
    remark VARCHAR(255),
    UNIQUE KEY uk_student_course (student_id, course_id, schedule_date, period_no)
);

特别说明这个唯一索引：加它的目的是防止同一位学生在同一节课产生两条考勤记录。这是考勤系统中非常容易忽略的数据完整性约束，没有它，前端连续点击两次签到就会生成重复数据，统计结果马上出错。

第三张是请假申请表leave_record：

sql复制CREATE TABLE leave_record (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    student_id BIGINT NOT NULL,
    leave_type TINYINT DEFAULT 1 COMMENT '1-病假 2-事假 3-其他',
    start_date DATE NOT NULL,
    end_date DATE NOT NULL,
    reason VARCHAR(500) NOT NULL,
    status TINYINT DEFAULT 0 COMMENT '0-待审批 1-已通过 2-已驳回',
    approver_id BIGINT NULL,
    approve_comment VARCHAR(255),
    create_time DATETIME DEFAULT CURRENT_TIMESTAMP
);

审批意见字段允许为空，因为驳回时必须填意见，通过时可不填。这类“字段与状态相关”的细节设计，在数据库层面不强制约束，但需要在Service层做逻辑校验。

3.3 SQL脚本的正确执行顺序

拿到源码后，SQL脚本的执行顺序是很多新手第一个卡住的地方。切忌直接双击整个sql文件让可视化工具乱执行。正确的顺序是：

1. 先执行init_database.sql，里面只有CREATE DATABASE语句和指定USE。
2. 再执行tables.sql，按依赖顺序建表：先建基础档案表（班级、用户、课程），再建业务记录表，最后建关联表和索引。
3. 最后执行init_data.sql，插入初始账号、班级、课程、默认配置数据。

为什么分开？因为一旦建表失败，你能根据出错位置快速定位原因，不用在一整份sql文件里乱翻。我自己习惯在每一个建表语句后加上DROP TABLE IF EXISTS的预处理，这样脚本可以重复执行而不报错，在反复调试的过程中非常省心。

3.4 初始化数据里必须有的“演示账号”

项目源码的init_data.sql里，我会预置三组演示账号：学生（stu001 / 123456）、教师（teacher001 / 123456）、管理员（admin / 123456）。密码都是BCrypt加密后的密文，而不是明文。这里有个小坑：如果你在SQL脚本里直接写明文密码，而代码里的登录逻辑用的是BCryptPasswordEncoder.matches()去校验，那永远登录不进去，因为BCrypt存储的密文必须是特定格式。

所以你在修改初始账号密码时，要么自己先用一个临时SpringBoot测试类生成BCrypt密文，要么直接在启动后通过“管理端新增账号”的功能去创建。我推荐后者，因为同时就验证了功能链路。

4. SpringBoot后端核心实现解析

4.1 后端工程结构与分层

后端工程我按下面这个结构组织：

code复制src/main/java/com/example/attendance/
├── config/          # 配置类：MyBatis-Plus分页插件、CORS跨域、WebMvc拦截器
├── controller/      # 接口层：按模块分为AuthController、StudentController等
├── service/         # 业务层：接口 + 实现类
├── mapper/          # 数据访问层：继承BaseMapper的Mapper接口
├── entity/          # 实体类：与数据库表字段一一对应
├── common/          # 通用类：统一返回结果、异常处理、JWT工具类
└── AttendanceApplication.java

每层职责必须单一，这是答辩时你可以理直气壮讲给老师听的工程素养。Controller只负责接收参数、调用Service、返回结果，Service里写业务规则，Mapper层只碰SQL。我经常在评审别人的毕设时看到Controller里堆了一大堆计算逻辑，这种代码面试官看一眼就会失去兴趣。

4.2 统一返回结果与全局异常处理

前后端分离项目里，接口返回格式必须统一，否则前端Axios拦截器没法做通用处理。我定义的统一返回类很简单：

json复制{
    "code": 200,
    "message": "操作成功",
    "data": { ... }
}

code为200代表业务成功，非200代表失败，401代表未认证，403代表无权限，500代表服务异常。前端Axios拦截器会统一判断code，如果是401则跳转到登录页。

对应的全局异常处理使用@RestControllerAdvice，把参数校验异常、业务异常、未知异常分别捕获，返回对应的code和message。这里有个细节：业务异常必须手动抛出，并且带上对用户友好、对开发者有用的提示语。我在Service里是这样用的：

java复制if (leaveRecord.getStatus() != 0) {
    throw new BusinessException("该请假申请已被处理，请勿重复操作");
}

好，现在聊聊JWT。我用JWT生成登录令牌，在登录成功时颁发，有效期为2小时。JWT工具类负责生成和解析Token，拦截器从请求头Authorization里获取Token，校验通过后把用户信息存入ThreadLocal，Controller里通过@CurrentUser注解即可拿到当前登录用户。

Token里放什么信息？我建议只放userId和userType，不要放太多业务字段，因为JWT一旦签发就无法在服务端主动修改。角色变更、账号禁用等场景需要通过数据库实时校验，所以拦截器在每次请求时不仅要校验Token合法性，还要查一下用户状态是否正常。

4.3 核心接口实现：签到、请假、审批

先说签到接口。前端调用POST /api/attendance/checkIn，参数为courseId和scheduleDate。后端逻辑分四步：

1. 从JWT中取当前用户，确认身份为学生。
2. 校验当前时间是否在允许签到的窗口期（上课前10分钟到下课时间）。
3. 根据当前时间与上课时间的关系，计算考勤状态（正常或迟到）。
4. 插入attendance_record，如果唯一索引冲突，则捕获DuplicateKeyException返回“请勿重复签到”。

这里有一个实操中必须注意的点：不要把业务规则散落在多次数据库查询里。比如先查一遍规则表，再查一遍是否已签到，再判断时间，每步都查库，连在一起就是多次IO。我一般会把课程信息、考勤规则一次性取出放入一个Map，然后用纯Java逻辑做判断，最后只有一次Insert操作。代码性能和学生阶段的评分其实关系不大，但这种“减少无谓IO”的思维方式是用人单位很看重的。

请假接口的核心在于状态流转。学生只能提交status为0的申请，教师审批时只能把status为0的申请改成1或2。这个状态机用if判断就可以保护，但如果想写得高级一点，可以定义一个枚举类AttendanceStatusEnum，把每个状态允许的转移写清楚。我在项目里更倾向于简洁的if判断，因为流程只有两步，引入复杂状态机反而不利于阅读。

4.4 定时任务：自动缺勤判定与请假关联

考勤系统的“自动判定缺勤”是整个项目中最能体现“主动设计”的功能点，也是我建议你在答辩时重点展示的部分。实现方式是用Spring的@Scheduled注解，写一个每天固定时间执行的定时任务。

不过这里有一个非常关键的工程问题：不能简单地每天跑一次。因为不同课程的下课时间不同，有些课结束得早，有些课结束得晚。更合理的方案是每隔10分钟扫描一次，找出“当前时间已超过下课时间5分钟、但没有任何签到记录”的考勤空缺，生成缺勤记录。

实现逻辑概括如下：

java复制@Scheduled(cron = "0 */10 * * * ?")
public void autoMarkAbsent() {
    List<CourseSchedule> finishedSchedules = courseScheduleMapper.findFinishedWithNoAttendance();
    for (CourseSchedule schedule : finishedSchedules) {
        attendanceMapper.insertAbsentRecords(schedule.getId());
    }
}

这个定时任务配合前面说到的那次“请假通过后批量修正考勤状态”的任务，就能让整个考勤数据闭环自洽。

4.5 权限控制细节与拦截器写法

拦截器是权限控制的核心入口。我这里用两个拦截器，一个处理JWT校验，一个处理角色权限。如果不带Token访问需要登录的接口，直接返回401；如果带了Token但角色不匹配，返回403。

代码示意如下：

java复制public class JwtInterceptor implements HandlerInterceptor {
    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
        String token = request.getHeader("Authorization");
        if (StringUtils.isBlank(token)) {
            throw new AuthException("未登录或Token已过期");
        }
        UserContext.set(jwtUtil.parseToken(token));
        return true;
    }
}

这里有个必须说清楚的要点：哪些接口放行，哪些接口拦截。登录接口、验证码接口放行，其余接口拦截。我通过在WebMvcConfig里配置addPathPatterns("/api/**")和excludePathPatterns("/api/auth/login", "/api/auth/captcha")来控制。

5. Vue前端关键实现与组件设计

5.1 前端工程结构与构建

前端工程使用Vite作为构建工具，src目录按功能划分：

code复制src/
├── api/            # 所有接口请求封装，按模块拆分
├── router/         # 路由配置，包含动态路由生成逻辑
├── stores/         # Pinia状态管理，存放用户信息、角色信息
├── views/          # 页面组件
├── components/     # 公共组件，如上传、表格封装等
├── utils/          # request.js封装、工具函数
└── App.vue

Vite相比Webpack最大的优势是开发服务器启动快、热更新秒级响应，这对毕设开发节奏非常友好。第一次接触的人不要被Node.js版本问题卡住，用Vite 4以上版本的话Node.js 16+就够，建议用18 LTS。

5.2 Axios封装与Token注入

这是我每次都要重点强调的工程点。如果你在每个页面里都直接写axios.get(url, config)，一旦后端调整了前缀或需要统一处理错误，你就得改几十个文件。所以我用utils/request.js统一封装Axios实例：

javascript复制const service = axios.create({
  baseURL: '/api',
  timeout: 10000
});

service.interceptors.request.use(config => {
  const token = localStorage.getItem('token');
  if (token) {
    config.headers.Authorization = token;
  }
  return config;
});

service.interceptors.response.use(
  response => {
    const res = response.data;
    if (res.code === 401) {
      router.push('/login');
      return Promise.reject(new Error('未登录'));
    }
    return res;
  },
  error => {
    ElMessage.error(error.message || '请求失败');
    return Promise.reject(error);
  }
);

这样页面里调用时就极其清爽：

javascript复制import { getStudentAttendance } from '@/api/attendance';
const list = await getStudentAttendance({ studentId: 'xxx' });

5.3 动态路由与菜单权限的实现

动态路由的逻辑是：用户登录后，后端接口返回该用户角色的菜单/路由权限列表，前端再通过router.addRoute()动态挂载。这里需要注意一个时间节点问题：刷新页面时，路由和状态都会被清空，必须重新获取。所以我会在路由守卫里判断Pinia中是否有用户信息，如果没有则先调getUserInfo接口再放行。

这里有一个新手特别容易踩的坑：路由守卫里做异步请求时，避免循环跳转。我见过很多代码在router.beforeEach里访问to.path，然后又用next({ path: '/login' })造成死循环。建议写法是：先处理好用户信息（有则继续，无则跳登录），再根据白名单放行，且明确排除已经是/login的情况。

5.4 核心页面：考勤打卡页与统计看板

考勤打卡页是系统里最有视觉说服力的页面。我用Element Plus的日历组件el-calendar展示当月考勤情况，每一天的格子里用不同颜色标签标明考勤状态（绿=正常，橙=迟到，红=缺勤）。学生打卡操作做成一个大按钮，点击后调用接口，成功时弹出最新状态。

教师端的统计看板则是数据可视化展示。我会用ECharts展示班级出勤趋势折线图、缺勤TOP5学生柱状图。ECharts的用法不复杂，核心是拿到接口返回的数据后组装成option需要的格式。

这里要额外提醒：前端不要做任何“业务状态”的最终判定。比如考勤状态是正常还是迟到，必须由后端接口返回后前端再渲染，前端不能自己拿本地时间算一个状态去展示。原因很简单：前端可以被绕过，后端才是数据可信源。

6. 接口文档规范与前后端联调经验

6.1 接口文档为什么是毕设项目的加分项

很多毕设项目只有代码和数据库脚本，没有接口文档。你千辛万苦实现了前后端分离，却在答辩时说不清楚自己制定了什么接口规范，这是很亏的。接口文档的价值有三层：设计和开发期约束双方行为、联调期降低沟通成本、答辩期作为“项目工程化”证据。

我个人推荐使用Markdown格式的接口文档，因为它不需要额外工具，提交到Git仓库里任何人用编辑器都能打开阅读。每一页接口文档应包含：URL地址、请求方式、请求参数表（参数名、类型、是否必填、说明）、响应示例、错误码说明、备注。

6.2 一份合格的接口文档长什么样

以下面这个请假审批接口为例：

POST /api/leave/approve

请求参数：

请求示例：

json复制{
  "leaveId": 12,
  "status": 2,
  "comment": "附件的请假证明不清晰，请重新提交"
}

响应示例：

json复制{
  "code": 200,
  "message": "审批成功",
  "data": null
}

这里有个细节我会在文档里专门注明：审批接口只有教师/管理员角色可调用，学生调用会返回403。接口文档里把权限写清楚，前端才能做出正确的菜单/按钮隐藏逻辑。

6.3 联调阶段的痛点与规避方法

前后端联调最痛苦的场景是：前端说接口返回格式不对，后端说前端没按文档传参。这个问题我从一开始就用两个办法规避。

第一，后端参数一律使用DTO对象接收，并且加上javax.validation的注解。比如：

java复制@NotBlank(message = "请假原因不能为空")
private String reason;

这样前端传参缺失时，后端返回的message会明确告诉用户“请假原因不能为空”，而不是抛一个空指针。

第二，前端所有接口调用都封装在api目录下，并且用JSDoc注释标注每个方法的参数和返回类型。这样当你从带参联调调试接口时，改后端字段，前端开发者只需要看api目录下的注释就能知道影响范围，不需要翻找每个页面里零散的axios调用。

6.4 使用Postman和Swagger辅助调试

除了Markdown文档，我还会在项目里集成springdoc-openapi（Swagger 3），让后端在开发阶段可以直接通过/swagger-ui/index.html页面调试接口。它与SpringBoot的整合非常简单，只要引入协调依赖：

xml复制<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.2.0</version>
</dependency>

然后在Controller类上补充@Tag注解、接口方法上补充@Operation注解，Swagger文档就会自动生成。我认为Swagger最适合做“开发期的实时文档”，Markdown文档则适合“交付时的静态契约”，两者互补。

7. 部署运行与常见问题排查实录

7.1 本地启动完整流程

从拿到源码到项目跑起来，我建议按这个顺序来，身边不少朋友跟着做基本二十分钟内能跑通。

1. 准备环境：JDK 1.8或11、Maven 3.6+、Node.js 16+、MySQL 8.0。
2. 创建数据库并导入SQL脚本。这里注意MySQL 8.0的默认字符集是utf8mb4，想要中文正常显示，建库语句必须加上DEFAULT CHARSET=utf8mb4。
3. 修改后端配置文件application.yml，把数据库地址、账号、密码改成自己的，重点是url后边的时区参数serverTimezone=Asia/Shanghai，少了这个在插入时间时会报错。
4. 启动后端：在项目根目录执行mvn spring-boot:run，看到“Started AttendanceApplication”即成功，端口默认8080。
5. 启动前端：进入前端目录执行npm install，然后npm run dev，Vite默认在5173端口启动。
6. 浏览器访问http://localhost:5173，用admin/123456登录。

这里我强烈建议你配置一个Nginx反向代理解决跨域问题，而不是在后端开启CORS。因为CORS的全局配置容易把接口暴露给任何来源，而Nginx代理则把前后端请求统一成同源。生产模式下，前端构建产物放到Nginx的html目录，同时把/api的前缀代理到后端地址即可。

7.2 常见问题速查表

7.3 我踩过的最大的坑

做这套系统时，我踩过最大的坑跟时间有关。考勤系统的时间判断横跨了“服务器时间”“数据库时间”“前端时间”三个维度。刚开始我天真地以为在MySQL里用NOW()就万事大吉，结果发现MySQL的时区和JVM的时区如果不一致，数据库自动填充的时间会和Java代码生成的LocalDateTime存在偏差。

后来我统一了时间策略：所有业务时间由SpringBoot的LocalDateTime.now()生成，数据库连接串显式指定serverTimezone，数据库表里的时间字段一律用DATETIME类型，绝不用TIMESTAMP（因为TIMESTAMP受数据库时区影响更明显）。统一之后，签到、请假、统计的时间判定再也没出过幺蛾子。

7.4 项目二次开发与扩展思路

如果你拿到源码后想在此基础上做二次开发，我建议优先考虑这几个方向。一是把签到方式升级为二维码扫码签到，教师端展示动态二维码，学生扫码后完成签到，这样能避免“代签”问题，适合作为创新点写进毕设论文。二是引入Redis缓存，把课表查询、统计数据等读多写少的接口缓存起来，演示时可以说自己做了性能优化。三是把报表导出为Excel，用EasyExcel生成月度考勤表，这种实用功能在答辩时很加分。

不过要提醒一句：每次扩展都要保持接口文档同步更新，不要让代码和文档走向分裂。这也是为什么项目里我会把接口文档放在docs目录下并纳入版本管理，每次修改接口，顺手改文档，形成习惯后联调成本会低很多。

根据我做过的多个全栈项目经验来看，这个考勤系统的完成度和工程规范性，已经足够支撑你写出一篇内容充实的毕业设计论文，也足够在面试时跟面试官展开聊权限控制、数据隔离、定时任务这些热门话题。最后说一个实操细节：拿到源码后别急着改功能，先把项目完整跑通一遍，然后用Postman把所有接口都调一遍，再去看每个表的数据变化。把这条链路理清楚后，你对前后端分离项目的理解会上一个台阶，后面无论是改代码还是写论文都会顺得多。