企业官网建设流程全解析

最近在本地把一套基于SpringBoot2 + Vue3 + MyBatis-Plus + MySQL8.0的Java Web工资信息管理系统完整跑通了一遍，从建库到前后端联调，中途确实是踩了不老少坑。工资管理这题目看着像纯CRUD，真做起来才会发现：工资计算规则怎么拆、月份重复生成怎么防、金额精度用什么类型、角色权限怎么控制，每一环都有讲究。这篇文章就按我实际操作的顺序，把这个项目的核心设计、技术选型逻辑、数据库结构、后端计算流程、前端页面实现、本地部署步骤以及高频问题排查经验全部梳理出来。适合正在做毕业设计、想从前端转全栈、或者需要给公司内部快速搭一套薪酬查询工具的开发者参考，照着走基本能少走一大半弯路。

1. 项目定位与整体技术方案拆解

1.1 工资管理系统到底要解决什么

工资信息管理系统不是简单的“员工表+工资表”，真实场景里它至少要覆盖三个层面的诉求。第一层是基础数据管理，包括员工档案、部门维护、岗位信息、入离职状态，这些是工资计算的数据底座。第二层是工资项配置，基本工资、岗位工资、绩效奖金、餐补交通补、社保公积金个人部分、缺勤扣款、个税预扣——每个工资项是收入还是扣款、计算时怎么取值，必须可配置而不是写死在代码里。第三层才是月度结算，选定一个月份，系统自动把在职员工这个月的所有工资项汇总生成工资单，然后提供查询、导出、打印工资条的能力。

很多项目失败就失败在只做了第三层的“汇总展示”，前面两层数据结构和计算规则设计得一塌糊涂。我个人的经验是，工资管理系统的数据流可以概括成一条线：员工档案和工资项配置是输入，月度结算逻辑是加工过程，工资明细表和工资汇总表是输出，员工自助查询和报表导出是最终消费场景。把握住这条线，功能边界就清楚了。

1.2 为什么是SpringBoot2 + Vue3 + MyBatis-Plus + MySQL8.0

这套技术组合放到今天依然有很强的普适性，不是因为它新，而是因为它稳。

SpringBoot2选择2.7.x版本而不是SpringBoot3，核心原因是生态兼容性。SpringBoot3强依赖JDK17和Jakarta命名空间，很多老牌中间件、生成工具链还没有完全平滑迁移。而SpringBoot2.7可以跑在JDK8上，恰恰是大多数公司生产环境和服务器的现状。对毕业设计和内部工具来说，JDK8 + SpringBoot2.7 + MyBatis-Plus这套组合的参考资料量、踩坑记录丰富程度都是最高的，遇到问题搜一下基本都有解。

Vue3配合Vite构建工具和Element Plus组件库，是目前搭建中后台管理系统最顺手的搭配。组合式API对复杂页面逻辑的组织比Vue2的Options API清晰太多，ts的加持也让前后端联调的数据结构对得更准。

MyBatis-Plus存在的意义是干掉单表CRUD的重复代码。工资系统里员工表、部门表、工资项表的增删改查是标准操作，用MyBatis-Plus的BaseMapper可以直接省掉一大半XML和Mapper接口代码。同时它自带的分页插件、逻辑删除、自动填充、乐观锁都是这套系统真实需要的功能，属于正正好。

MySQL8.0选它一方面是因为utf8mb4默认字符集对中文支持更好，另一方面8.0对窗口函数、CTE这类复杂查询的支持在日后写统计报表时会非常有用。

1.3 功能模块与页面结构规划

按我前面说的数据流，整个系统可以拆成六个模块。系统管理管用户、角色、登录；员工管理管档案、部门、入离职；工资项管理配置计薪项目和计算公式；工资结算做月度批量生成和撤销；工资查询提供明细、汇总、打印；统计报表按月、部门两个维度做分析和导出。

页面结构上，前端采用典型的左侧菜单 + 右侧内容区的后台布局。登录后进入工作台，工作台通常放几个统计卡片：本月在职人数、本月应发工资总额、本月实发工资总额、各部门工资分布。这些数字通过一个聚合接口返回，前端直接展示，既好看又不复杂。核心操作页是“工资结算”，选择月份、选择部门范围、点击生成，整个过程有进度反馈和结果提示。员工端页面则简单得多，只看自己的工资条历史记录。

权限模型这步我建议直接按三种角色设计：管理员能配置工资项和查看所有数据，HR能做员工管理和工资结算，普通员工只能查看自己的工资条。角色控制在路由层面和接口层面同时做，后端用拦截器校验角色是最底线的要求。

2. 数据库设计与后端核心逻辑

2.1 核心表结构与设计取舍

数据库是整个系统的地基，表结构设计没做好，后面写多少代码都是补救。

sys_user是登录用户表，字段包括id、username、password、real_name、role、status，密码必须加密存储，角色用字符串常量或者枚举都行，不建议在表里用外键关联角色表，中小型系统一个role字段够用了。

department表是部门表，维护部门名称和负责人。员工表employee_info是绝对的核心表，emp_no员工编号要唯一，name、gender、phone、id_card等基础信息，dept_id关联部门，position岗位，hire_date入职日期，salary_base基本工资，status在职状态。这里有一个细节：基本工资是放在员工表还是放在工资项配置表？

我的做法是“基本工资”放员工表，“其他工资项”放配置表。原因是基本工资是每个员工独立的基础数据，跟着人走；绩效、补贴、扣款这些是规则性数据，跟着配置走。两者分开，后续调薪只需要改员工表，调整绩效规则只需要改配置表，互不干扰。

工资项配置表salary_item，字段有item_name、item_type（收入/扣款）、calc_type（固定金额/按出勤天数计算）、sort排序。这张表相当于“计薪字典”，程序里不要写死工资项，而是通过配置驱动。

月度数据用两张表。salary_detail工资明细表，记录“某员工某月某工资项的金额”，一个员工一个月有若干条记录；salary_slip工资汇总表，记录“某员工某月应发、实发合计以及状态”。为什么要拆两张表而不是一张大宽表？因为工资明细要支撑工资条逐项展示，要给员工看“基本工资是多少、补贴是多少、扣款是多少”，宽表虽然查询方便，但工资项是动态增长的，每加一个工资项就要改表结构，而明细表的行式存储天然支持任意工资项的增长。

金额字段一律用DECIMAL(10,2)，Java里对应BigDecimal，严禁用double或者float存钱，这是金融相关业务的红线。二进制的浮点数在加减运算里会有精度误差，工资差一分钱在财务核对时都是事故。

2.2 MyBatis-Plus配置与使用要点

MyBatis-Plus在这个项目里扮演的是“少写代码”的角色，但有几个配置点必须提前处理好。

分页插件是必须配置的。很多新人写完了分页接口发现传了pageNum和size之后还是返回全量数据，原因就是没注册MybatisPlusInterceptor。配置方式如下：

@Configuration public class MybatisPlusConfig { @Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor(); interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL)); return interceptor; } }

这个配置类放在后端项目的config包下，SpringBoot启动时自动加载。

逻辑删除直接通过注解实现。在实体类的deleted字段上加上@TableLogic，之后所有Mapper查询会自动带上deleted=0的条件，删除操作也变成update而不是delete。注意逻辑删除字段在database里默认值要给0，插入时要自动填0，否则查不到数据。

自动填充交给MetaObjectHandler处理，create_time、update_time这类字段可以在插入和更新时自动写入，不需要每个service方法都手动set一遍：

@Component public class MyMetaObjectHandler implements MetaObjectHandler { @Override public void insertFill(MetaObject metaObject) { this.strictInsertFill(metaObject, "createTime", LocalDateTime.class, LocalDateTime.now()); this.strictInsertFill(metaObject, "updateTime", LocalDateTime.class, LocalDateTime.now()); } @Override public void updateFill(MetaObject metaObject) { this.strictUpdateFill(metaObject, "updateTime", LocalDateTime.class, LocalDateTime.now()); } }

实体类对应字段加上@TableField(fill = FieldFill.INSERT)和@TableField(fill = FieldFill.INSERT_UPDATE)即可。

2.3 工资计算主流程与幂等处理

工资计算是整个系统最有技术含量的部分，也是最容易翻车的地方。

我设计的流程是这样的：前端选择要结算的月份，比如2026-01，后端接收到请求后做三步处理。第一步，查找这个月份所有在职员工列表；第二步，遍历每个员工，依次计算基本工资、绩效、补贴、缺勤扣款、社保公积金个人部分等各工资项的金额，插入salary_detail明细表；第三步，把每个员工的明细汇总成应发、扣款合计、实发金额，插入salary_slip汇总表。

计算中最核心的是出勤天数相关逻辑。基本工资除以当月应出勤天数得到日工资，再乘以实际出勤天数。应出勤天数可以用两种方式得出：一种是看当月的工作日数量，另一种是直接用国家规定的21.75天月计薪天数。内部系统通常采用21.75天作为标准月计薪天数，因为简单稳定。

BigDecimal除法必须指定精度和舍入模式，这是最容易踩坑的地方：

BigDecimal dailySalary = basicSalary.divide(BigDecimal.valueOf(21.75), 2, RoundingMode.HALF_UP); BigDecimal actualSalary = dailySalary.multiply(BigDecimal.valueOf(attendDays));

如果直接把basicSalary除以21.75不指定精度，遇到除不尽的小数时会直接抛ArithmeticException，这是BigDecimal的经典陷阱。

幂等处理必须用唯一约束兜底。工资很容易出现误操作重复点击生成，同一员工同一个月生成两次就会数据错乱。我的做法是在salary_slip表加一个联合唯一索引(employee_id, salary_month)，插入时如果冲突会抛DuplicateKeyException，Service层捕获这个异常后返回友好提示“该月工资已生成，请先撤销后再操作”。注意这里不建议用逻辑删除配合唯一索引，因为逻辑删除的deleted字段会参与联合唯一索引，第二次生成时旧记录虽然deleted=1但索引里还是占着位置，照样冲突。

整个生成过程必须加上@Transactional事务注解，要么全成功要么全回滚。曾经遇到的情况是明细插了一半，汇总时报错，结果明细和汇总数据不一致，查了很久才发现是事务没加。这种低级错误一旦发生，对数据可靠性的打击是致命的。

3. Vue3前端工程与核心页面实现

3.1 前端工程结构与依赖准备

前端采用Vite + Vue3 + TypeScript的工程化结构，配合Element Plus组件库。目录结构上，src/api放接口请求定义，src/router放路由配置，src/views放页面组件，src/components放公共组件，src/utils放axios封装和工具函数，src/stores放Pinia状态管理。

依赖方面核心几个：vue-router负责路由跳转和守卫，pinia负责全局状态比如用户信息，axios负责HTTP请求，element-plus负责UI组件。Element Plus建议用unplugin-vue-components按需引入，避免全量引入导致首屏体积过大。配置好之后，组件不需要手动import，在template里直接用，插件会自动按需加载。

axios封装是前后端联调的关键一环，请求拦截器负责把token塞进请求头，响应拦截器负责统一处理业务code、跳转登录态失效、弹出错误消息。封装好了所有页面请求的代码可以精简很多，也方便统一修改。

3.2 登录鉴权与路由守卫

登录逻辑是标准的token方案。用户输入账号密码，后端验证通过后返回一个token字符串，前端存到localStorage和Pinia里。之后每次请求axios请求拦截器自动带上，后端通过拦截器验证token有效性。

路由守卫用router.beforeEach实现，核心逻辑就一段：

router.beforeEach((to, from, next) => { const token = localStorage.getItem('token'); if (!token && to.path !== '/login') { next('/login'); } else if (token && to.path === '/login') { next('/'); } else { next(); } });

这段代码的意思很直白：没登录的只能去登录页，已登录的不能回头去登录页。角色权限的精细控制我建议放在路由meta里，比如管理的路由meta.roles设置为['ADMIN', 'HR']，然后在守卫里判断当前用户角色是否在允许列表里，不在就重定向到403页面。前端权限控制本质上是优化体验，真正安全的判断必须由后端接口校验来做，前端不能作为唯一防线。

3.3 工资查询与结算页面的实现要点

工资结算页是这个系统的核心操作页面。页面布局是顶部放一个筛选区域，包括月份选择器、部门选择器，中间是按钮，点击“生成本月工资”触发批量生成接口，下方是本月已生成工资的列表。

列表展示建议用el-table，每一行是一个员工的salary_slip记录，字段包括员工编号、姓名、部门、应发工资、扣款合计、实发工资、状态。点击行可以展开工资明细，这里我用的是el-table的expand展开行，展开后下方显示一个内嵌表格，把salary_detail的记录逐条列出来，收入项和扣款项可以分两栏显示，或者用type字段加tag标签区分。

前端展示金额的精度问题必须重视。后端返回给前端的金额统一转成string类型，不要用number类型返回。原因很简单，JS的Number类型在处理大金额或者高精度小数时可能出现精度丢失，比如19位的雪花ID在JS里会变成带e的科学计数法，金额如果出现0.1+0.2这种计算误差会直接显示成0.30000000000000004这样的诡异数字。金额精度我们在后端用BigDecimal保证，序列化时统一转字符串，前端只做展示，不做任何计算。

工资条的打印功能可以用浏览器的window.print来实现，把打印区域的DOM单独用一个id包起来，打印时只显示那块区域。如果项目有更高要求，可以接一个打印组件或服务端渲染PDF，但内部系统用浏览器打印最省事。

4. 从零到一：本地部署与运行全流程

4.1 环境版本与安装注意事项

部署这套系统对环境的版本要求是一环扣一环的，版本不对后面全是莫名其妙的报错。

后端依赖JDK8及以上，推荐JDK8，因为SpringBoot2.7在这个版本下表现最稳定。Maven需要3.6以上，用来拉取依赖和打包。MySQL必须是8.0版本，5.7虽然也能跑，但初始化脚本里如果用了8.0的新特性就会报语法错误。前端需要Node.js 16以上，npm会随Node一起安装。

安装MySQL8.0时有一个很多人忽略的细节：安装过程中或者第一次启动时要特别注意root账号的认证插件。MySQL8.0默认用caching_sha2_password密码认证，而一些老版本的JDBC驱动不支持这种认证方式，会报Authentication plugin caching_sha2_password cannot be loaded这样的错误。解决方案有两个，要么用8.0.x版本的JDBC驱动，这是推荐做法；要么在MySQL里把root用户的认证插件改回mysql_native_password，但这样对安全性有副作用。我自己的习惯是引新驱动，省事。

4.2 后端配置与启动

拿到源码之后，后端部分的第一步是导入数据库脚本。源码包里通常带一个init.sql或者salary_db.sql的文件，在MySQL命令行或Navicat里执行即可。执行之前要先创建一个数据库：CREATE DATABASE salary_db DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;，然后再导入脚本。

第二步是修改application.yml配置文件。这是整个部署过程最容易出问题的一步：

server: port: 8080 spring: datasource: url: jdbc:mysql://localhost:3306/salary_db?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai&useSSL=false&allowPublicKeyRetrieval=true username: root password: 你的数据库密码 driver-class-name: com.mysql.cj.jdbc.Driver

url里几个参数必须都在。serverTimezone如果不指定，北京时间连数据库会直接报时区错误；useSSL=false是关闭SSL加密连接，本地开发环境不会因为证书问题连不上；allowPublicKeyRetrieval=true必须显式设置，否则新版本的MySQL驱动会在首次连接时报Public Key Retrieval is not allowed。

pom.xml里MySQL驱动的依赖坐标要注意。老版本是mysql:mysql-connector-java，从8.0.31开始官方改成了com.mysql:mysql-connector-j。如果用了高版本驱动但坐标没改对，启动时会直接报找不到驱动类。

随后在项目根目录执行mvn spring-boot:run，或者在IDE里直接运行主类。看到Tomcat started on port 8080这样的日志就说明后端启动成功了。

4.3 前端配置与联调

后端跑起来后，前端部分的启动要先装依赖。在frontend目录下执行npm install，如果速度慢可以临时切换npm镜像源。依赖装完执行npm run dev，Vite默认会起在5173端口。

前后端联调有一个必须处理的环节是跨域。我在开发环境用的方案是Vite的proxy代理，在vite.config.js里配置：

server: { port: 5173, proxy: { '/api': { target: 'http://localhost:8080', changeOrigin: true } } }

这样前端请求/api/login这样的路径时，Vite会自动转发到http://localhost:8080/api/login，前端代码里看起来就像是请求的同源地址，绕开了跨域限制。生产部署时更推荐把前端dist目录直接放到Nginx下，配一个反向代理指向后端的8080端口，开发环境和生产环境的思路基本一致。如果后端非要自己处理跨域，可以写一个CorsFilter配置类，但开发环境用Vite proxy是最省心的。

启动完成后浏览器访问http://localhost:5173，能看到登录页基本就成功了一大半。

4.4 文档资料怎么用效率最高

这套源码的亮点之一是“含文档”。拿到手之后不要急着写代码或者跑起来，先花半小时把文档目录过一遍。通常文档会包含需求说明文档、数据库设计文档、接口API文档、部署运行手册。

我个人的阅读顺序是：先看需求文档，它会告诉你这个系统设计的业务流程和功能边界，这是理解代码的钥匙；再看数据库设计文档，搞清楚每张表的作用和表间关系；然后对照接口文档看Controller层的接口，前端调用和后端响应的字段是不是对得上；有部署问题再翻部署手册。这样一套流程走下去，项目的脉络就清晰了。

很多人在看项目源码时习惯直接Ctrl+F搜某个关键词，结果一搜就陷入细节，完全看不到整体架构。用文档作为导航手册，会比直接硬啃代码效率高很多。

5. 高频问题排查与避坑清单

5.1 MySQL 8.0连接类典型问题

第一类是驱动类名错误。SpringBoot2.7如果pom里引入了高版本MySQL驱动，但配置里还写的是com.mysql.jdbc.Driver，启动会直接报错。8.0以后驱动类名必须是com.mysql.cj.jdbc.Driver。

第二类是时区报错。URL没带serverTimezone时，报错通常会提示The server time zone value is unrecognized。解决方式就是前面写的在url后面加上serverTimezone=Asia/Shanghai。

第三类是认证闪烁问题。报Public Key Retrieval is not allowed时，在url末尾加allowPublicKeyRetrieval=true。报SSL连接问题时加useSSL=false。

我把这几类问题的排查办法整理成一张速查表：

5.2 跨域、Token 与前后面联调问题

联调阶段最常见的问题是接口能通但浏览器报跨域。如果前端用的是Vite的proxy，这个问题的排查要点是看请求路径前缀是否正确。比如后端接口的Controller定义的是/api/employee/list，前端调用地址写的是/employee/list，那proxy就匹配不到，请求会直接落到前端服务器，返回的可能是一个HTML页面而不是JSON数据。统一路径前缀是最省心的做法。

Token失效是另一个隐蔽问题。登录成功后token有效期设置太短，比如设成30分钟，用户操作到一半突然所有接口都401，体验非常差。建议开发环境token有效期设置到12小时以上，正式部署时再根据需要配置。同时前端axios的响应拦截器要做统一处理：检测到401状态时，清除本地token，跳转到登录页，而不是在每个请求里单独写错误处理代码。

还有一个容易忽略的点是处理“后端改了字段名但前端不知道”。后端返回的字段是驼峰命名如employeeName，前端可能按下划线写employee_name，结果页面一直在渲染undefined。这个需要前后端约定统一风格，或者用接口文档的字段名来严格对齐。

5.3 金额精度与Long序列化

金额精度问题在前端页面表现出来的症状是：明明数据库里存的金额是11325.50，页面显示却是11325.5，或者更严重的是算出来的数字不对。根源在于后端如果返回了float或double类型数据，JS接过去再转成字符串时会出现浮点数误差。

我的规范是：数据库DECIMAL对应Java BigDecimal，Controller返回VO里的金额字段用String类型接收，JSON序列化时BigDecimal默认输出数字，所以我还会在字段上加@JsonFormat或者自定义序列化器强制转字符串。展示层拿到的是严谨的字符串，直接给用户看。

Long类型精度问题的严重性更高，因为MyBatis-Plus的默认主键是雪花ID，一个ID有19位，而JS的Number类型只能精确表示到2的53次方也就是大约9千万亿，超过这个范围的整数会精度丢失。具体表象是：列表里查一条记录，点击编辑按钮，弹窗里显示的是另一个ID对应的数据，因为id其实已经变了。

解决方案是在全局配置Jackson，把所有Long类型序列化成字符串再给前端：

@Configuration public class JacksonConfig { @Bean public Jackson2ObjectMapperBuilderCustomizer longToStringCustomizer() { return builder -> builder.serializerByType(Long.class, ToStringSerializer.instance); } }

如果是SpringBoot2.7，也可以在application.yml里配置全局的策略，但用自定义Bean的方式最灵活也最清晰。

5.4 MyBatis-Plus 分页和逻辑删除的坑

分页插件没配是第一个大坑。症状是传入pageNum和pageSize后，返回的total是0或者结果是全部数据。原因就是前面说的没有注册MybatisPlusInterceptor。这个坑报错不明显，它是“能跑但结果不对”，排查起来很费时间。

第二个坑是逻辑删除和唯一索引的冲突。前面我在工资幂等部分提过，这里再展开说一下。如果salary_slip表建了(employee_id, salary_month)联合唯一索引，同时又用了逻辑删除，那么撤销工资后旧记录虽然逻辑删除了，但索引中的值还在，第二次生成同月工资时直接违反唯一约束。解决方式有两种：一种是不用逻辑删除而是物理删除工资结算记录，另一种是把唯一索引去掉，业务层自己先查后插。我个人建议工资结算这类数据直接物理删除，因为“撤销生成”本身这个操作已经写入了操作日志，物理删掉全月明细不会带来数据安全问题。

第三个是关于自动填充不生效。如果insertFill或者updateFill没生效，先检查实体类字段有没有加@TableField注解，以及填充注解设置的FieldFill类型是否正确。还有一个隐蔽点：strictInsertFill在字段值为空时才填充，如果前端传了createTime字段过来，即便你填了也会被忽略，这种情况用setFieldValByName更直接。

第四个坑是关于日期范围查询。用MyBatis-Plus的LambdaQueryWrapper做月份筛选时，如果实体类的salaryMonth字段是String类型，直接传入“2026-01”可以用like或者eq匹配；如果表里是datetime类型，需要先构造LocalDate的开始和结束时间再between查询。不少人在这个细节上卡住，报表一直查不出数据。

最后讲一下我个人的体会

写这套工资系统的过程，让我感触最深的一点是：一个系统真正难的不是某个具体技术点，而是把“业务规则”翻译成“代码逻辑”的过程中那些容易被忽略的边界情况。工资生成要考虑重复点击的幂等性、撤销操作的数据一致性、金额字段的精度安全、角色权限的数据隔离，这些不是在单一技术栈的教程里能学到的，必须要亲手做一遍才会记住。如果后面想继续扩展，这个项目还有两个很自然的迭代方向：一个是接入Excel导出，把工资明细和部门汇总表导出成文件；另一个是把个税和社保的复杂计算规则做成独立的策略类，让工资项的计算变得更加可配置。无论如何，先把核心链路跑通、把数据算对，比什么都重要。