每年毕业设计季，Java Web 方向最容易被问到的题目之一，就是“考勤管理系统”。这个题目看着普通，做起来其实广度刚好卡在一个很舒服的位置：既有权限管理、增删改查、请假审批这类基础功能，又有打卡统计、报表展示这类能体现技术深度的地方，选它当毕业设计的人非常多。

我见过不少同学拿到一套“SpringBoot+Vue 公司日常考勤系统平台”完整源码后，第一反应是先点开跑起来，结果不是 MySQL 连不上，就是前端依赖装不上，或者登录之后页面一片空白。三样东西摆在那里——源码、SQL 脚本、接口文档，但怎么把它们串起来、跑通、还能在答辩时讲清楚，才是真正值钱的部分。

所以这篇文章就专门来讲这套考勤系统，从项目结构、数据库设计、后端接口、前端页面，到部署排错、答辩加分，完整梳理一遍。不管你是刚拿到源码还没跑起来的小白，还是已经跑通但想理解内部逻辑、准备进一步改造成自己项目的同学，这篇文章都会比你自己对着代码瞎猜效率高很多。

1. 项目整体设计与业务架构

1.1 为什么考勤系统是Java Web毕设的经典命题

考勤系统的业务复杂度非常适中。对比商城系统，少了一堆支付、库存、物流的边界情况；对比纯管理系统，又比图书管理、学生管理多了一点时间逻辑和状态流转的趣味性。

它的核心就两件事：每天记录员工上下班时间，月底根据这些时间算出勤率。听起来简单，但要做到能演示、能被老师追问、能体现工程化能力，就需要把以下闭环打通：

员工登录后打卡上班、打卡下班；忘记打卡可以申请补卡；有事可以提交请假申请；加班之后可以登记加班单；管理员能看全员当天的打卡状态；月底能按部门输出考勤汇总。

这一套业务闭环正好覆盖了 Java Web 开发最常见的技术练习点：用户认证、CRUD、状态机流转、时间处理、聚合统计。再加上 Vue 前端的页面对接，前后端分离、跨域、Token 鉴权这些知识就全练到了。

1.2 系统角色与权限边界

考勤系统通常分两种角色，复杂一点的会再加一层部门主管。角色越少越好设计，但为了答辩时有讲头，建议保留三类角色：

• 管理员：管理用户、部门、班次，查看全部考勤数据，审批请假与加班。
• 普通员工：打卡、查看自己的考勤记录、提交请假和加班、修改个人资料。
• 部门主管：在管理员和员工之间加一层，负责审批本部门员工的申请。

权限控制的思路很简单：后端接口做角色校验，前端菜单按角色动态渲染。管理员登录后看到的是“系统管理”菜单，普通员工登录后只有“个人考勤”菜单，这种差异化展示在答辩演示时非常直观。

1.3 前后端分离架构的核心边界

这套项目采用的是导航制的前后端分离架构——SpringBoot 只提供 RESTful API，Vue 负责页面渲染和交互。

前后端分离的关键分界线是接口契约。前端不直接操作数据库，后端也不关心页面长什么样。前端通过 Axios 调后端接口，拿到 JSON 数据，再渲染到表格、表单、图表上。这个边界清楚之后，出现 bug 时你就知道问题出在哪一边：接口通了但页面没出来，那是前端渲染问题；页面报错但接口在 Postman 能通，那是前端传参格式问题。

后端习惯上再分四层：Controller 接收请求、Service 处理业务逻辑、Mapper 操作数据库、Entity 映射表结构。这套分层规范，在中后期维护时价值很大，答辩时也方便讲清楚“低耦合”是怎么做到的。

2. 数据库模型与SQL脚本设计

2.1 核心数据表及其关联关系

任何考勤系统的数据库核心都离不开这几张表：用户表、部门表、打卡记录表、请假表、加班表、班次表。表之间的关系并不复杂，用户表通过部门 ID 关联部门表，打卡记录、请假表、加班表都通过用户 ID 关联用户表。

我见过很多新手在数据库设计上踩坑，最常见的问题是“一张表写完所有字段”。比如把所有考勤数据塞进一张表，字段越加越多，最后变成一张超级大表，查起来既慢又难维护。规范的做法是拆分，下面这个 ER 关系在设计考勤系统时可以直接参考：

2.2 关键字段设计细节

在设计打卡记录表时，有一个细节值得注意：要把“上班打卡时间”和“下班打卡时间”放在同一行记录，而不是每次打卡都生成一条新记录。这样一条记录代表员工某一天的一整次出勤，统计时直接数记录条数就是出勤天数，效率高很多。

打卡记录表的字段大致是这样：

status 字段不要搞成存储中文，存英文小写字符串或者数字枚举值，前端展示时再转换。这样做的好处是后端统计时不需要做字符串匹配，写 SQL 也干净。

请假表还需要单独一个 status 字段，记录请假单当前处于什么状态。请假是一个典型的审批流：员工提交后状态是 pending，主管审批后变成 approved，拒绝则变成 rejected。请假单的流程状态流转，是答辩老师最喜欢追问“状态机设计”的地方，到时候要能说清楚。

2.3 SQL脚本里的初始数据与索引

拿到项目 SQL 脚本之后，千万不要直接盲导。第一步先看脚本里的建库语句，确认数据库名、字符集、排序规则。字符集强烈建议用 utf8mb4，因为这套编码才能完整支持中文和特殊符号，如果脚本默认是 utf8，也要自己改掉。

初始化数据部分通常会预置管理员账号和几个测试员工账号，默认密码一般是 123456 或者 admin123。这种默认密码项目源码里都有注释，第一次登录之后最好在数据库里直接把密码改掉，不然答辩演示时被人拿去登录，页面就尴尬了。

索引设计上，打卡记录表要给 user_id 和 work_date 建联合索引。因为月底统计的典型查询是“某员工在某个月份所有打卡记录”，联合索引（user_id, work_date）能直接命中，不用全表扫描。这个点看似不起眼，但你就是能靠它挡住老师的“数据量大时查询性能怎么优化”的问题。

3. 后端SpringBoot实现要点拆解

3.1 后端项目结构怎么看懂

SpringBoot 项目拿到手，先不用急着逐个文件读，先看包结构。标准的包结构基本能告诉你这个项目的模块划分。

一般长这样：

com.example.attendance ├── controller # 接口层 ├── service # 业务逻辑层 ├── mapper # 数据访问层 ├── entity # 数据库实体 ├── config # 配置类，如跨域、拦截器 ├── common # 通用类，如统一返回结果、异常处理 └── utils # 工具类，如 JWT 工具

先从这个结构开始，你就知道源码里六个关键文件有什么用，不会像无头苍蝇一样到处乱点。阅读顺序也有讲究：先看 entity 了解数据模型，再看 controller 了解有哪些接口，接着看 service 理解核心业务逻辑，mapper 反而是最简单的。

3.2 登录认证与Token鉴权机制

考勤系统的登录模块几乎全部使用 JWT 做认证。JWT 理解起来不复杂——登录成功后后端生成一个 Token 返回给前端，前端把 Token 存起来，之后每次请求都在 Header 里带上这个 Token，后端再解析 Token 判断请求是否合法。

打个比方：Token 就像游乐园的腕带，进门时发给你，之后玩每个项目都要出示一下腕带，工作人员不用查数据库也知道你是买过票的。

后端一般用一个拦截器或者 Spring Security 的过滤器来拦截接口请求，没有 Token 或者 Token 过期的直接返回 401。考勤系统里哪些接口需要登录、哪些接口需要管理员权限，都是在拦截规则里配置出来的。在看源码时找一下这个拦截配置类，基本就掌握了整个项目的安全设计。

3.3 核心接口设计与字段说明

接口文档是这套项目交付物里最重要的东西。从接口文档能看出项目设计得好不好，也能看出代码里哪些方法在做什么事。考勤系统的核心接口大致可以分为四组：

打卡接口的后端逻辑是这套系统里最有含金量的地方，值得仔细讲一下。员工点上班打卡时，前端把用户 ID 和后端时间传过去，后端先查当前日期有没有已存在的打卡记录，有就说明重复打卡了；没有就新建一条记录。然后后端把当前时间与班次规定的上班时间做比较，晚于规定时间就计算迟到分钟数，把 status 置为 late。下班打卡逻辑类似，但是更新记录而不是新建记录。

这里涉及一个时间边界问题：跨天排班怎么办？比如员工晚班从晚上十点上到第二天早上六点。简单方案是下班时间超过午夜，打卡日期仍记为上班那天的日期。更合理的设计是把 work_date 的意义定义为“排班开始的那天”，下班时间通过班次表计算，不与 work_date 机械绑定。答辩时如果有老师追问这个问题，你能答出这个区分就很加分。

请假审批的后端逻辑也不难，核心就是状态校验。审批时先看这条请假单当前 status 是不是 pending，如果不是就直接拒绝操作，避免重复审批导致状态错乱。这种状态校验，在并发场景下还要加乐观锁或唯一约束，但对毕设项目来说，先把状态判断写严谨已经足够。

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

看后端代码时你会发现几乎所有 Controller 编写的返回格式都是一致的：code、message、data。这就是统一返回结果，它保证了前端处理数据时不需要每个接口都单独判断一次成功失败。

与统一返回结果配合的是全局异常处理。项目里通常会用一个 @RestControllerAdvice 的类，专门接住各种异常。比如参数校验失败返回 400，业务异常返回 500 和提示信息。这个机制的意义在于：Controller 里不用写一堆 try-catch，代码干净很多，前端拿到的错误信息又是统一的格式，可以直接弹 Message 提示。

接口文档里一般会写好每种错误返回对应什么 code，比如 401 代表未登录，403 代表没有权限，500 代表服务器内部错误。前端拿到 code 后做对应处理，这就是前后端分离项目里“接口契约”的实际落地。

4. 前端Vue实现与页面流转

4.1 前端工程结构与路由设计

Vue 前端项目拿到手，先看 src 目录结构与路由配置。阅读入口文件后，知道整个项目的结构才好继续看下去。典型的结构长这样：

src ├── api # 接口请求封装 ├── assets # 静态资源 ├── components # 公共组件，如侧边栏、头部导航 ├── router # 路由配置 ├── store # 全局状态管理 ├── views # 页面视图组件 └── App.vue # 根组件

路由配置里能看到哪些路径对应哪些页面。考勤系统通常有三类路由：不需要登录的（登录页）、登录后可访问的（首页、个人打卡）、仅管理员可访问的（用户管理、部门管理）。前端路由守卫负责判断用户有没有登录，没登录就强制跳回登录页，这个体验做得好，答辩演示时很自然不出戏。

4.2 Axios请求封装与拦截器

Axios 封装是前端项目的灵魂。很多新手在自己写项目时，每个页面都单独调用 axios，代码重复一大堆。正规的毕设项目会统一封装一个 request.js 文件，把基础 URL、超时时间、请求拦截器、响应拦截器都写在里面。

请求拦截器的作用就是给每个请求自动加上请求头里的 Token，无需每个接口方法手动加。响应拦截器的作用是统一处理返回信息，如果后端返回 code 401，就直接清掉本地 Token 并跳转到登录页；如果返回 code 500，就弹出错误消息提示。

看源码时先看封装文件，后面每个 api 模块都只是定义接口函数，调用的都是这个封装好的 request，代码会简洁很多。这个封装逻辑答辩时也讲得出来，属于工程化思维的良好展示。

4.3 打卡页面与考勤统计展示

打卡页面是考勤系统的门面。页面设计一般是一个大按钮，上面写着“上班打卡”或“下班打卡”，按钮旁边展示当前时间。页面加载时调用接口查询当天打卡状态，如果已经打了上班卡，按钮文案就变成“下班打卡”；如果已经打了下班卡，按钮就禁用了。这个状态判断在前端实现，后端也要做二次校验，双保险。

考勤统计页面通常使用图表展示。月份出勤概览、迟到次数、加班时长这些数据用饼图或柱状图展示非常直观。图表组件最常用的是 ECharts，在 Vue 里通过一个图表组件传入配置项即可渲染。

统计接口返回的数据结构通常是这样的：一个数组，每个元素是一个月的汇总，包含出勤天数、迟到次数、早退次数、请假天数、加班总时长。前端拿到后按字段展示到表格和图表里，这个接口的设计直接影响页面效果的好坏。

4.4 菜单权限与动态渲染

菜单权限的前端实现一般有两种方式：第一种是写死在路由表里，然后根据角色过滤；第二种是后端登录接口返回菜单列表，前端动态生成侧边栏。对毕设项目来说，用第一种更稳。

做法是在路由配置的 meta 里写一个 role 字段，标记该组件允许哪些角色访问。前端渲染侧边栏时，根据当前登录用户的角色把这些 meta 信息过滤一遍，就能实现管理员看到完整菜单、普通员工只看到个人考勤菜单的效果。路由守卫再校验一遍访问权限，双保险避免用户手动改 URL 绕过菜单。

这个设计不复杂，但是非常实用，也是答辩时能讲的亮点之一。

5. 项目部署与环境配置指南

5.1 环境要求清单

如果拿到源码后第一件事不是看代码，而是先准备环境，会省掉很多坑。考勤系统这套代码通常要求下面这个环境组合：

先把版本确定下来，再动手。版本冲突是跑通项目时最折磨人的问题，JDK、Node 这种大版本的差异很容易导致代码能编译但运行报错。

5.2 数据库导入与后端配置

第一步一定是导入 SQL 脚本。用 Navicat 或命令行执行脚本，先检查脚本里的建库语句，新建数据库，选择数据库，然后执行全脚本。全部执行完成后，看一下表是否齐全，系统管理相关的初始化数据是否导入。

第二步打开后端的 application.yml 配置文件，改数据库连接信息。最典型的是两处：URL 里的数据库名，以及数据库账号密码。

server: port: 8080 spring: datasource: url: jdbc:mysql://localhost:3306/attendance_db?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai username: root password: your_password driver-class-name: com.mysql.cj.jdbc.Driver

这里最容易出现的问题是 MySQL 8.0 和 5.7 的驱动类名不同，配置文件的 driver-class-name 不要照抄，检查项目里引入的 mysql-connector-java 版本来决定是填 com.mysql.jdbc.Driver 还是 com.mysql.cj.jdbc.Driver。统一建议用带 cj 的新驱动类名。

改完配置后在项目根目录运行mvn spring-boot:run，后端启动成功后终端会打印接口地址。用浏览器访问 Swagger 接口文档地址，能打开就说明后端启动成功。

5.3 前端依赖安装与启动

后端启动只是第二步的一半，前端也要启动。进入前端目录，执行 npm install 安装依赖。这一步经常会卡住，建议改用淘宝镜像源：

npm config set registry https://registry.npmmirror.com npm install

依赖装完后启动开发服务器：

npm run serve

前端默认端口一般是 8081 或 3000，因为后端占了 8080。开发环境下通过 vue.config.js 配置代理转发请求，前端开发服务器接收到 /api 开头的请求，会自动转发到后端的 8080 端口，这样就不会有跨域问题。

devServer: { port: 8081, proxy: { '/api': { target: 'http://localhost:8080', changeOrigin: true } } }

启动完成后打开浏览器访问前端地址，用初始化账号登录，能看到页面正常渲染，整个环境就算搭通了。

5.4 生产环境打包与部署

如果想把项目部署到云服务器上给老师在线演示，那就不能只用开发服务器了。前端执行npm run build构建出 dist 目录，后端执行mvn clean package -DskipTests打包出 jar 文件。

部署方案有两种常见选择：第一种是前后端分离部署，前端 dist 文件用 Nginx 托管，后端 jar 用 java -jar 启动，Nginx 配置里把 /api 请求反代到后端端口；第二种是整合部署，把前端 dist 目录里的文件拷贝到后端项目的 src/main/resources/static 目录下，再重新打包后端 jar，这样一个 jar 包同时承载前后端，部署更简单。

对毕设在线演示来说，第二种方案操作成本更低。但第一种方案能体现工程化能力，两个方案的口径自己在答辩前准备一下，按自己项目的实际部署方式讲。

6. 常见问题与排错经验

6.1 数据库连接类错误

“Cannot create PoolableConnectionFactory” 这类报错基本都是数据库连接串的问题。第一阶段检查 MySQL 服务有没有启动，第二阶段检查账号密码填没填对，第三阶段检查 URL 里的 serverTimezone 参数。MySQL 8.0 默认时区设置容易导致连接报错，URL 里加上 serverTimezone=Asia/Shanghai 基本能解决大半个问题。

如果所有配置都对，那就检查是不是端口被占用了。MySQL 默认 3306 端口，如果本机装了多个 MySQL 实例，端口可能冲突。连接失败时先看错误里提示的端口号，再用命令行确认监听状态。

6.2 前端依赖安装失败

npm install 报错的概率非常高。常见的错误是某个依赖版本与 Node 版本不兼容，比如 node-sass 装不上。原因很简单：node-sass 是 C++ 模块，需要针对特定 Node 版本编译，Node 版本过高时没有对应的预编译二进制文件，就要现场编译，环境里没有编译工具就报错。

解决办法也很直接：降低 Node 版本。考勤系统这类 Vue 2 项目建议用 Node 14 或 16，装完依赖再跑 dev server，基本不会再报 sass 相关的错。另外 npm install 时如果看到 deprecated 提示不需要慌，war 警报不一定影响运行。

6.3 Token登录过期与401问题

页面登录完过一段时间再操作，突然弹出一个 401，然后跳回登录页。这个现象几乎都是 Token 过期时间设置太短导致的。查看后端 JWT 配置里的过期时间参数，如果是按分钟级别的，改成 24 小时或者更长，演示时就不会中途被踢出去。

还有一种情况是前端请求头没带 Token。排查方式很简单：打开浏览器开发者工具，看请求 Header 里 Authorization 字段是不是空的。如果是空的，说明响应拦截器或请求拦截器的逻辑有问题，Token 没被正确设置进去。

6.4 跨域报错

浏览器控制台出现 CORS 错误，分两种情况。第一种是开发环境没有配置代理，直接访问后端地址调的接口，浏览器拦截了跨域响应。第二种是生产环境 Nginx 反代配置不对，请求没转发到后端。

开发环境的解决办法就是上面提到的 vue.config.js 配置 proxy，这个代理是 webpack-dev-server 的功能，前端请求发到同源地址，代理再转发到后端，浏览器根本感知不到跨域。生产环境则检查 Nginx 配置里的 /api location 是否正确指向后端端口。

6.5 数据统计结果异常

打卡记录有，但每月统计结果对不上。这类问题的本质多半是日期查询边界不对。月底统计一般要查出勤月份的起始日期和结束日期，结束日期往往是下月第一天零点之前。如果代码里直接用了当月最后一天的 00:00:00，打卡记录里有当天晚上打卡数据的就会被漏掉。

排查时先打印 SQL 实际执行的参数，看看日期范围是否包含了当月所有天数。修改逻辑时统一使用日期工具类计算月份的 start 和 end，左闭右开区间查询，避免 23:59:59 这种人工写法。

7. 毕设答辩前的优化与演示准备

7.1 预留演示数据

答辩演示最怕的就是页面上空空如也。考前准备不要用全新的数据库，建议在 SQL 脚本初始化数据的基础上，再用测试账号录入一批“历史数据”：前三个月的打卡记录、请假审批单、加班单各造十几条。这样打开统计页面时，图表和表格立刻就有内容，视觉效果好很多。

造数据可以直接在数据库里手动插入，也可以用系统页面逐条录入。后者更稳妥，因为走一遍真实业务逻辑，数据格式不会出错。建议准备至少两个员工账号，一个演示个人打卡流程，一个给管理员用来演示审批和统计。

7.2 演示路径要提前排练

毕业答辩演示最重要的不是炫技术，而是让老师看清楚你的系统能干什么。我总结的演示路径顺序是：登录页登录 -> 个人首页看今日状态 -> 打卡 -> 查看个人考勤记录 -> 提交请假申请 -> 切换管理员账号 -> 审批请假 -> 查看部门考勤统计 -> 打开图表看月报 -> 用户管理展示权限。

提前按这个路径走一遍，留意每个页面切换的加载时间。整个过程控制在十分钟以内，不要在一个功能上磨蹭太久，剩余时间留给老师提问。提问环节比演示环节更重要，一定要能自信地回答自己项目里每个关键功能是如何实现的。

7.3 几个值得扩展的功能点

如果时间和能力允许，可以在这套基础上做一些扩展，既提升项目完成度，也让答辩时更有底气。我推荐三个方向：

第一个是导出 Excel。月度考勤统计页面加一个导出按钮，后端用 Apache POI 或者 EasyExcel 生成 xlsx 文件。这个功能非常实用，在演示中点击导出并打开文件，效果比口头描述直观得多。

第二个是增加图表可视化。除了基础表格外，用 ECharts 画出部门迟到率排行、月度出勤趋势，数据说服力强，前端技术含量也更饱满。

第三个是引入简单缓存。用 Redis 缓存用户信息和班次配置，降低查询数据库的压力。采用这个功能后，能写出“缓存穿透与缓存一致性”的内容，成为答辩加分点。

7.4 论文与源码如何对照

写论文时不要直接把源码贴上去。评审老师经验丰富，一眼就能看出哪些是套话。论文的核心章节应该与项目结构一一对应：需求分析对应业务架构、数据库设计对应 SQL 脚本中的表结构、系统实现对应 Controller 和 Service 的代码、测试章节对应你实际跑过的功能清单。

论文里的“系统测试”建议写功能测试结果，使用表格列出测试用例编号、测试步骤、预期结果、实际结果。这种表格在答辩时翻出来给老师看，比三千字描述项目背景要有说服力得多。

我个人在辅导这类项目时最深的感受是：源码只是起点，真正能拉开差距的是你对项目的理解深度。把数据库设计想明白、把接口流程走通顺、把一两个扩展功能做出彩，这套考勤系统就不再是网上下载的模板，而是你实实在在完成的毕业设计。