回想我刚做人事管理系统那会儿还停在一个SpringMVC项目里塞一堆JSP的阶段前端页面和后端逻辑全耦在一起。后来接了公司内部HR的改造需求才真正转向前后端分离架构。这个项目前后折腾了大半个月从SpringBootVueMyBatisMySQL这套组合里踩了不少坑也沉淀了不少经验。现在回头看这类人事系统确实是练前后端分离最佳的项目之一业务边界清晰、模块划分自然既有增删改查又有权限和流程做一遍基本能把主流开发链路走通。这篇文章我就把这套系统的完整源码结构、核心实现和部署步骤都拆开讲希望帮你少走几个月的弯路。1. 项目整体设计与架构拆分1.1 为什么是前后端分离SpringBootVue这套组合人事系统这个业务场景天然适合用前后端分离来搭建。原因很实在人事系统面对的是一线员工、部门主管、HR管理员三类角色不同角色的操作界面和权限差异很大如果还是传统的服务端渲染每次页面跳转都要刷新整个页面体验非常割裂。而前后端分离后前端负责交互和展示后端只暴露JSON接口职责边界一下子就清楚了。技术选型上SpringBoot解决后端开发的配置地狱问题。以前用SpringMVC光配置xml就得写几十行SpringBoot用自动配置和约定大于配置内嵌Tomcat后连External容器都不用管。Vue在交互性上有一套双向绑定和组件化让员工信息这种表格表单的场景改起来非常快页面局部刷新也够流畅。MyBatis作为持久层框架胜在可以把SQL直接写在Mapper文件里做人事系统这种带复杂多表关联查询的场景员工、部门、职位、考勤、薪资多表join比JPA的抽象更方便控制SQL执行计划。MySQL就不用说了开源、稳定、生态成熟中小型企业内部系统完全够用。这套组合还有个隐形优势前后端分离后后端可以独立开发、独立测试前端也能独立开发、独立部署。我们当时的协作流程是后端先把Swagger接口文档定义好前端拿着文档同步开工最后再联调。相比以前的串行开发模式进度至少省了三分之一。1.2 核心表结构设计从员工到考勤的建模思路人事系统的底层是数据库表设计表结构设计不好后面写SQL的时候痛苦万分。我设计这套系统的核心思路是主数据业务数据分离。主数据包括员工表、部门表、职位表业务数据包括考勤记录表、薪资记录表、请假申请表。员工表是核心中的核心。我建议不要把所有信息堆在一张表里而是把员工的基本信息工号、姓名、性别、手机号、邮箱、入职日期和扩展信息学历、紧急联系人、合同信息分开存。这样做的考虑是基本信息的查询频率远高于扩展信息分开存储可以减少单表行宽提高查询效率。部门表用经典的自关联结构每行记录一个parent_id字段就可以支持多级部门树。人事系统里部门层级经常调整比如某个部门从A事业部划到B事业部只需要update一条记录的parent_id。职位表则放在员工和部门之间作为关联表记录员工在某个部门下担任的职位这样支持一人多岗的场景。业务数据表的设计举考勤表为例。考勤记录表的核心字段是employee_id、attendance_date、check_in_time、check_out_time和status。最关键的约束是employee_id和attendance_date的联合唯一索引防止同一个人同一天产生重复记录。这个索引我吃过亏一开始没加后来测试插入重复数据时发现统计报表结果翻倍排查了半天才发现是脏数据问题。薪资表我用了月度快照模式单独设置一个snapshot_date字段。这是跟会计同事讨论后才明白的工资是历史数据如果员工后续调薪之前月份的薪资记录应该保持不变所以不能用员工表里当前薪资字段直接算历史薪资而要有独立的月结数据表。2. 后端SpringBootMyBatisMySQL核心实现2.1 SpringBoot工程搭建从0到可运行项目SpringBoot项目搭建现在都用Spring Initializr十秒钟就初始化好一个工程。但我在实际操作中发现很多人初始化完工程就直接开写忽略了关键配置导致后面到处打补丁。这里我建议一次性把基础打好。工程结构我习惯按模块分层controller层接收请求、service层处理业务逻辑、mapper层访问数据库、entity层定义实体、dto层用于接口参数校验和返回。很多人觉得dto和entity可以合并但实际项目里这两个混在一起会出问题。比如员工实体里有created_at字段创建员工时前端不需要传这个字段如果直接用entity接收就需要在setter上做逻辑判断。用dto专门接收前端参数entity负责数据库映射两边职责清清楚楚。核心依赖只需要spring-boot-starter-web、mybatis-spring-boot-starter和mysql-connector-java三件套。这里有个版本坑要特别提醒SpringBoot 2.x和3.x之间的差异非常大。3.x要求Java 17以上并且javax包改成了jakarta如果随便找个老教程配依赖编译期就会报错。我建议新项目直接上SpringBoot 3.x毕竟Java 17是长期支持版本但如果你要参考的代码是2.x写的注意改依赖版本和import路径。application.yml里的关键配置是数据源和MyBatis映射。数据源用HikariCP连接池这是SpringBoot默认的配置maximumpoolsize为20就差不多了太小高峰期会卡顿太大MySQL压力大。MyBatis的配置我建议把mapper-locations指定到classpath:mapper/*.xml并把map-underscore-to-camel-case设为true这样数据库里的employee_name字段能自动映射到employeeName属性省去大量ResultMap的编写。spring: datasource: url: jdbc:mysql://localhost:3306/hr_system?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai username: root password: 你的密码 driver-class-name: com.mysql.cj.jdbc.Driver hikari: maximum-pool-size: 20 minimum-idle: 5 mybatis: mapper-locations: classpath:mapper/*.xml type-aliases-package: com.hr.system.entity configuration: map-underscore-to-camel-case: true2.2 MyBatis使用的三个关键细节SQL、缓存、类型处理器MyBatis的高频使用点集中在写动态SQL。人事系统的查询条件非常多比如员工列表要支持按部门、按姓名、按入职日期范围筛选如果每个组合都写一个独立方法代码会爆炸。这时候用动态SQL就对了MyBatis的if和where标签能自动拼接条件并且处理好多余的AND。我写动态SQL的习惯是大于两个查询条件的就放到XML里写毕竟动态SQL在XML里更好debug。Java代码里的注解SQL写简单查询还可以一旦涉及动态条件就非常难维护。这里给出员工列表分页查询的Mapper示例select idselectEmployeePage resultTypecom.hr.system.entity.Employee SELECT * FROM employee where if testdeptId ! null AND dept_id #{deptId} /if if testkeyword ! null and keyword ! AND (name LIKE CONCAT(%, #{keyword}, %) OR employee_no LIKE CONCAT(%, #{keyword}, %)) /if /where ORDER BY create_time DESC LIMIT #{offset}, #{pageSize} /select再说说MyBatis的缓存机制。MyBatis一级缓存是默认开启的作用范围是SqlSession级别。我的项目开发过程中就遇到过一级缓存的坑同一个SqlSession里连续查询两次相同条件数据第二次走缓存返回了旧数据。在Spring中每次请求如果没有开启事务SqlSession会新建并关闭所以一级缓存问题不容易暴露但一旦加了Transactional整个方法共享一个SqlSession一级缓存就可能会让你拿到过时数据。解决办法是在Mapper方法上配置flushCachetrue或者在需要实时数据的查询上设置statement的属性。二级缓存我一般不建议在人事系统这种数据一致性敏感的项目里开启。人事数据的准确性高于性能如果有人修改了员工信息二级缓存里的其他SqlSession还留着旧数据就会看到幽灵数据。如果实在要开也只建议在字典表、职位表这种很少变动的基础数据上开启。类型处理器TypeHandler是另一个容易忽略的点。人事系统里有状态字段我习惯用Integer存储0-在职1-离职2-停职但在前端展示时却需要中文状态所以接口返回时要转一次。我写了一个枚举转换TypeHandler直接在查询结果映射时把Integer转成对应的状态枚举。这样就避免了在Service层到处写if-else转换逻辑。2.3 接口设计与登录鉴权JWT比Session更适合前后端分离前后端分离开发接口设计必须遵循RESTful风格但人事系统里有些场景不必死板地完全套用。我的原则是资源操作走RESTful业务流程走动词接口。比如新增员工对应POST /api/employees修改员工对应PUT /api/employees/{id}删除员工对应DELETE /api/employees/{id}这些没问题。但审批请假单这种就是业务流程用POST /api/leave-requests/{id}/approve比用PUT /api/leave-requests/{id}更直观因为审批本质上不是一个单纯的资源修改操作。鉴权设计上前后端分离后不能依赖HttpSession因为前端可能部署在不同的域名或端口下且Session天然不适合横向扩展的集群部署。我使用JWT方案用户登录成功后后端生成一个签名Token返回前端前端存在localStorage里并在每次请求时放到Authorization请求头。后端用一个拦截器解析Token校验通过就把用户信息放入ThreadLocal后续Service层可以直接获取当前登录用户。JWT有个很关键的坑Token失效时间。人事系统每天在线时长较长我设置Token的有效期为2小时同时做一个Refresh Token机制在用户操作时检测到快过期时自动签发新Token。这个机制还是很有必要的否则员工上午登录中午吃完饭回来已经在摸鱼了突然发现Token过期被踢回家。这并不是安全问题而是人为降低了效率所以刷新机制不是所有系统都需要但像人事管理这种长时间使用的后台系统很需要。权限控制方面我使用了Spring Security框架配合JWT设计。权限模型参考RBAC方案三个核心表用户表user、角色表role、权限表permission。员工表与用户表做一对一关联用户表关联角色角色关联权限。在代码层面通过PreAuthorize(hasAuthority(employee:add))这种注解对接口做权限控制。这个方案能覆盖人事系统95%以上的权限场景只有那些需要同部门才能看的复杂数据级权限才需要额外的数据权限校验逻辑。3. 前端Vue工程实现与接口联调3.1 从create到环境变量先别急着写页面前端工程我使用的是Vue 3 Vite Element Plus这套组合。Vite在一些项目场景下比Webpack快太多了开发时的热更新基本是秒级而老项目Webpack冷启动都要十几秒改一次代码等好一会儿才能看到效果。不过Vite的热更新在个别场景下也会失效比如修改了vite.config.js或者router目录下新增了文件这一般要重启DevServer习惯了反而觉得比Webpack的持久化缓存方案更直观。项目创建命令很简单npm create vuelatest创建时选择Router、Pinia这几个选项。Element Plus接入也不复杂安装后全量引入还是按需引入是个选择题。全量引入最简单但打包体积会到1MB以上。按需引入靠unplugin-auto-import插件自动做构建速度会提高不少。我做了个折中基础组件全量引入业务组件按需引入。原因在于人事系统页面以表格和表单为主如果全部按需引入开发时总会遇到某个组件没导入导致页面空白的情况排查起来也麻烦。这里分享一个真实经验调试时写完页面发现有报错在浏览器控制台报组件名称未注册的错误排查半天发现是某次改代码把组件引入了删掉。后来干脆不再去记哪些组件是自动导入的直接全量引入开发效率反而更高。环境变量的配置是很多同学容易忽略的。测试环境、生产环境请求的后端地址不一样得在env.development和env.production两个文件里配置VITE_API_BASE_URL变量。这样开发时是http://localhost:8080部署到服务器后是http://your-server-ip:8080切换环境不用去改代码非常方便。3.2 axios封装与动态路由的实现逻辑axios在前后端分离项目里必须做统一封装。我的做法是在request.js里统一设置baseURL、超时时间和请求头导出request对象供所有api模块调用。关键处理有两点请求拦截器里自动从localStorage取Token放到Authorization头响应拦截器里统一处理HTTP错误和业务错误码比如后端返回401时自动跳转登录页返回500时用Element Plus的Message提示错误原因。人事系统的路由权限又比普通系统复杂一层。员工、主管、管理员登录后能看到的菜单和页面不同如果所有路由都在前端静态配置员工登录后也可以通过地址栏直接跳转到管理员页面。我的做法是使用动态路由登录成功后后端返回当前用户的角色和权限列表前端根据权限列表用router.addRoute()动态注册对应路由。这样地址栏直接访问无权限页面时路由表中根本不存在这个路由会自然落到404页面安全边界非常清晰。动态路由还有一个好处是菜单可以动态生成。前端拿到权限列表后根据父子路由结构渲染侧边栏菜单不需要在代码里写死每个页面的入口。比如员工管理下面有员工列表和员工审核两个菜单项管理员登录时两个菜单都显示部门主管登录时只显示员工列表。这个体验上的细节用人话说就是你登录进去看到的菜单和你的权限匹配。3.3 表格、表单和分页的前端交互细节人事系统前端的核心交互就三类表格展示、表单编辑、弹窗确认。我总结了一个通用模板每个管理页面基本就是三件套组合。表格展示用Element Plus的el-table配合el-pagination处理分页。这里要注意的是刷新页面时页码丢失的问题当用户点击第3页后不小心刷新了浏览器列表又回到第1页体验很差。解决办法是在Vuex或Pinia里保存分页状态或者通过URL的query参数记录pageNo和pageSize我实现的时候选择了后者因为页面刷新后路由状态不会丢。表单编辑的关键是数据回显。编辑员工信息时需要把员工数据传入表单。我用的是el-dialog内嵌el-form的写法在打开弹窗时通过nextTick把数据赋值给表单对象。为什么会有nextTick这个坑因为el-dialog的渲染是异步的弹窗还没渲染完成就赋值表单组件还没挂载赋值就被忽略了。这个报错很隐蔽不会在控制台报错唯一的表象就是打开弹窗时表单是空的当初差点被这个问题带偏。删除操作我加了二次确认弹窗使用ElMessageBox.confirm。很多人刚开始觉得这个多余但人事数据误删除影响很大加了确认至少能拦掉一大半手滑操作。确认后调接口返回成功后刷新列表逻辑串起来就好。4. 从源码到上线完整部署流程实录4.1 后端打包与生产环境配置后端项目开发完成后不能直接提交给运维得先做生产环境配置调整。最关键的三项是数据源、日志级别和数据库初始化方式。数据源配置在application-prod.yml文件中区分。生产环境用独立的MySQL账号绝对不能沿用开发用的root账号。我遇到过企业因为生产库用root账号被人拖库导致数据全删的事故所以这个细节务必注意。生产账号只授权hr_system库的增删改查权限就够了不需要give global权限。打包命令是一个简洁的命令但打包的重点在于环境指定。开发环境、生产环境的配置分离用不同的配置文件。mvn clean package -DskipTests -Dprod.profileprod指定的环境会影响打包结果生产环境的配置和开发环境的配置会使用不同的数据源。这样可以避免把开发环境的数据源配置带到生产环境的配置中。打包后SpringBoot项目的可执行jar是自带内嵌Tomcat的启动命令是java -jar hr-system.jar非常简洁。我一般会再加上 -Xms256m -Xmx512m参数设置JVM内存毕竟服务器内存有限时还是要做一些限制。另外一定要用nohup或systemd方式挂后台跑否则SSH断开项目也跟着停了。nohup java -Xms256m -Xmx512m -jar hr-system.jar --spring.profiles.activeprod logs/console.log 21 4.2 Tomcat部署方式的选择为什么内嵌Tomcat就够了很多教程会教你在外部Tomcat的webapps目录下丢war包来部署这种做法我实际体验下来不太推荐。SpringBoot的内嵌Tomcat完全可以搞定部署没必要为了用外部Tomcat做一层转换。如果你非要外挂Tomcat就需要修改pom.xml中的打包方式改为war并继承SpringBootServletInitializer。但这样做的收益并不大外挂Tomcat的版本与SpringBoot的内嵌版本不一致时还可能遇到ClassNotFound之类的兼容性报错。SpringBoot的优势之一就是内嵌容器之后部署时的简化强烈建议用java -jar方式。唯一要我劝退的场景是企业确实有运维规范要求使用外部Tomcat那没办法只能按war包方式处理。但个人项目或中小型项目java -jar是体验最好的部署方式。4.3 前端构建与Nginx配置要点前端项目部署到生产环境先要构建出静态文件然后想办法把它们托管起来。我用Nginx承担这个任务。npm run build构建完成后dist目录下的静态资源就是部署包。Nginx配置的关键是将根路径指向静态资源目录同时将/api的请求都反向代理到后端服务。server { listen 80; server_name hr.example.com; root /opt/hr-system/frontend/dist; index index.html; location / { try_files $uri $uri/ /index.html; } location /api/ { proxy_pass http://127.0.0.1:8080/api/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } }这里try_files $uri $uri/ /index.html这条配置非常重要。Vue项目的路由默认是history模式用户直接刷新访问 http://hr.example.com/employee/list 这个路径时如果不加try_files配置Nginx会在磁盘上找不到employee/list这个真实文件直接返回404。try_files的作用就是让所有访问请求都落到index.html再由Vue的路由接管。另一个配置细节是proxy_pass的路径匹配。如果location是/api/proxy_pass的路径必须带/api/或精确写 http://127.0.0.1:8080否则会出现路径重写问题。常见的坑是在proxy_pass后面少写了/api/这串结果请求转发到后端时路径变了后端返回404。这一点踩过的同学应该都懂。4.4 数据库初始化与版本管理生产环境数据库不能用开发环境的数据直接导入而是要跑初始化脚本。我习惯用Flyway做数据库版本管理它能在应用启动时自动执行未运行的SQL脚本并且保证脚本不会重复执行。Flyway的使用方式不复杂在pom里加上依赖然后在resources/db/migration目录下按照V1__init.sql、V2__add_leave_table.sql这种命名方式放SQL脚本。启动时它会自动执行没有执行过的脚本并记录到flyway_schema_history表里。这样后续要加字段或加表只需要新增脚本不用手动去生产库执行SQL避免因为漏执行导致的不一致。Flyway有一个坑需要重点注意已经执行过的脚本一旦写入之后就不要改动哪怕只改一个字符都不行。因为Flyway是基于文件哈希值判断脚本是否执行过的改动会导致checksum校验失败应用启动直接报错。我犯过一次这种错误补了个索引导致全表的数据还在但脚本哈希变了启动直接失败。教训是数据库脚本变更只允许新增文件不允许修改已执行文件。5. 常见问题与排坑手记5.1 启动阶段的高频报错速查表报错信息原因解决办法Access denied for user root数据库账号密码不对或未授权检查application.yml中的用户名密码执行授权SQLUnknown database hr_system数据库还没创建执行CREATE DATABASE hr_system;Failed to configure a DataSource数据源配置缺失或加载失败确认spring.datasource配置是否完整profile是否选对Invalid bound statement (not found)Mapper接口和XML文件没有对应上检查Mapper接口方法名与XML中id是否一致namespace是否正确Table doesnt existFlyway脚本未执行或执行失败检查flyway_schema_history表状态查看日志中SQL执行报错Consider defining a bean of type XxxMapperMapper接口未被Spring扫描在启动类上加MapperScan注解或Mapper接口加Mapper注解这表里最常见的是Invalid bound statement这类报错。一开始遇到的时候往往怀疑是代码逻辑问题实际上大多数时候是namespace写错或者方法名没有对应上。我自己就犯过把Mapper接口写在com.hr.system.dao包但XML文件里的namespace写成了com.hr.system.mapper一直找不到对应关系排查这个小问题浪费了不少时间。5.2 前后端联调阶段的常见坑前后端联调时的坑有80%都出在数据格式不一致上尤其是时间字段。后端返回的时间是一个标准的ISO格式的UTC毫秒值或字符串而前端Element Plus的表格组件显示的默认格式不是你能直接使用的格式要在展示前做格式化处理。我踩过的坑是后端返回2024-01-15T08:30:00.00000:00这样的字符串前端如果不格式化表格里直接显示一大长串非常不友好。解决方法是统一用day.js做时间格式化在全局设置好formatter导出使用import dayjs from dayjs; export function formatDate(dateStr) { if (!dateStr) return -; return dayjs(dateStr).format(YYYY-MM-DD HH:mm:ss); }另一个联调坑是跨域问题。开发环境下前端在localhost:5173后端在localhost:8080端口不同就产生了跨域。在Vite的proxy中配一个代理可以解决开发环境的问题// vite.config.js export default defineConfig({ server: { proxy: { /api: { target: http://localhost:8080, changeOrigin: true } } } });但生产环境我建议不要使用后端开启CORS的方式用Nginx反向代理最省心。因为Nginx代理后前端和后端在浏览器看来就是同一个域名根本没产生跨域。5.3 部署阶段的问题端口占用与MySQL连接失败MySQL连接时报SSL连接错误这个我遇到过几次。核心原因是MySQL 8.0之后默认开启SSL而驱动连接时没有配置相应参数会导致警告或不稳定。这个问题的解决办法是在jdbc连接串里明确指定。用MySQL 8以上版本时建议加上useSSLfalse并配置serverTimezone参数解决时差问题。完整的URL配置我在前面的yml文件里已经给出了这里就不再重复。但要注意如果公司DBA强制要求SSL连接那就要在数据库服务器上正确配置SSL证书并将连接参数改为useSSLtrueverifyServerCertificatefalse。端口被占用的问题特别容易出现在开发机。我之前固定用8080端口跑后端但电脑上开了另一个SpringBoot项目没关掉导致每次启动都报Port 8080 was already in use。排查方法很简单# 找到占用8080端口的进程PID lsof -i:8080 # 根据提示的PID杀掉进程 kill -9 PID这类启动失败问题大多不是代码层面的问题更多是环境层面的问题。遇到不确定的情况第一步去看启动日志的前几行报错根据报错内容定位问题会比盲改代码高效得多。5.4 针对前期遗留问题的复盘与推荐方案整个项目做下来回到设计层面再看有些地方其实可以做得更好分享一点我的总结。代码层面Service层的事务控制很关键。一开始我在批量导入员工Excel时每到一条就做一次数据库插入几百条数据写了十几分钟都没结束。后来发现问题是启动的事务粒度不对。最后用了批处理方案解析Excel放入List然后一次性插入到数据库分分钟就处理完了。批量操作时注意控制批处理数量几千条一口气插也会把数据库压垮。ItemWriter这种分批次提交的策略是常用的方案你会在实际项目中体会到它的价值。表结构设计上把员工合同二进制数据直接存在MySQL里其实不是最优方案。如果有下一轮迭代我会把这类文件放到MinIO或OSS存储MySQL路径字段只存文件的URL。这样MySQL表格的行宽会大幅下降查询性能也会更好。前端方面如果这个系统要持续迭代可以考虑引入TypeScript。我这次用的是纯JS后期维护时因为字段类型不明确在写复杂逻辑时经常需要反复确认返回结构。TypeScript的接口定义配合后端的Swagger自动生成能给前端的类型错误提前做一层预检长远来看维护成本会有所降低。这个项目的源码完整的保留了各个模块的实现逻辑如果你想基于它做二次开发或者学习这个技术栈的综合用法直接在源码基础上按我前面讲的配置和部署流程操作就行。按照经验一个中等配置的服务器跑这套系统支撑几百个员工同时使用绰绰有余。