做Java Web开发的人应该都见过这类项目办公管理系统。网上存量的项目资源非常多但真正能用Spring Boot 2 Vue 3 MyBatis-Plus MySQL 8.0这套组合把它们串起来的其实不算多。大多数老项目要么停留在JSP时代要么用Vue 2 Element UI要么数据库还是MySQL 5.7换到新版环境时各种水土不服。这个标题里的项目恰好踩在了我日常工作中最常用的一套技术栈上而且自带文档光这点就值得先说一句这是少见的“拿到手能真正跑起来”的完整度。如果你正好在学Spring Boot和Vue 3或者公司想快速搭一套内部OA又或者你手头有个课设/毕设要做那这个项目的参考价值都不低。它解决的核心问题是怎么用前后端分离的方式把员工管理、部门管理、请假审批、公告通知、考勤统计这些常规办公场景落地成一套可维护的系统。下面我会从项目设计、技术选型、真实开发细节到排错经验把这套东西完整拆一遍。1. 项目整体设计与思路拆解1.1 办公管理系统到底在管什么很多人一听到“办公管理系统”就以为是个大杂烩其实真正落到代码层面它的业务边界是相当清晰的。我拆过不少这类项目核心模块基本逃不开这几块组织架构、人员信息、考勤管理、请假与出差审批、公告发布、会议管理、个人待办。这个项目也是一样的套路。组织架构和人员信息是整个系统最底层的基础数据。部门表、岗位表、用户表这三张表几乎决定了后续所有业务逻辑的走向。请假审批需要知道申请人的部门归属考勤统计需要知道用户的状态和时间规则公告发布需要知道接收对象的组织范围。所以这套系统在数据库设计上用户表一定会带上部门ID和岗位ID部门表则通常会设计成父子层级方便做树形展示。审批流是另一个关键模块。办公系统里最烦人的开发点往往就是审批因为它的状态流转很绕。一个请假单从提交到部门主管审批再到人事确认中间要经历多个状态节点。大部分教学级项目不会直接上流程引擎而是用一张“审批记录表”配合状态字段来模拟。这种实现方式的好处是简单直观、容易理解坏处是流程一旦复杂就不好维护。这个项目的处理方式属于前者里的典型做法请假单表里存当前状态另建一张审批记录表存每次操作的人和意见。考勤模块则通常是“打卡数据 统计规则”。前端提供打卡按钮后端记录打卡时间然后按月份统计出勤天数、迟到次数、请假天数。这里最容易忽略的是时区问题和周末判断很多项目上线后出现打卡时间偏移基本都是这两个地方没处理好。公告和会议模块相对简单就是增删改查加一个已读状态。但需要注意这类功能往往要跟待办提醒联动登录首页要有“未读公告数”“待我审批的单据数”。这就要在首页聚合查询时把多张表的统计结果合并到一个接口里返回减少前端的请求次数。1.2 技术栈选型背后的逻辑项目为什么选Spring Boot 2而不是Spring Boot 3选Vue 3而不是Vue 2选MyBatis-Plus而不是MyBatis原生背后其实都有非常务实的考量。先说Spring Boot 2。虽然Spring Boot 3已经发布很久了但国内很多企业的存量系统依然跑在Spring Boot 2.x上特别是2.6和2.7这个大版本段。原因很现实大量中间件和第三方开源库对Spring Boot 3的兼容性还在逐步跟进而Spring Boot 2经过多年沉淀生态稳定、资料齐全、坑基本都被踩平了。对于教学项目和中小型企业内部系统来说稳定压倒一切选Spring Boot 2不是落后是求稳。Vue 3就更不用犹豫。Vue 2已经停止维护组合式API带来的代码组织方式在应对办公系统这种“组件多、状态交互频繁”的场景时比选项式API舒服太多。配合Element Plus组件库哪怕是没写过前端的人也能快速把表单、表格、对话框这些常用界面搭出来。MyBatis-Plus的选择是整个后端开发效率的关键。办公系统的业务大多是单表或多表联合的分页查询如果用原生MyBatis每个实体都要手写一套XML的CRUD工作量直接翻倍。MyBatis-Plus提供通用Mapper和通用Service单表增删改查零SQL分页插件一加就完事。它的条件构造器在处理复杂查询条件时尤其好用比如考勤统计时根据部门、日期范围、关键字筛选一句LambdaQueryWrapper就解决了不需要写一堆动态SQL拼接。MySQL 8.0在这个组合里属于“默认正确”的选择。相比5.78.0在性能、窗口函数、CTE、默认字符集utf8mb4上都领先一大截。尤其是utf8mb4如果你系统里可能出现生僻字或者表情符号5.7的utf8其实有点力不从心8.0默认就给你妥善处理了。1.3 “含文档”这个亮点含金量有多高我必须单独说一下“含文档”这件事。做Java Web项目源码其实是最不稀缺的东西GitHub上一搜一大把。真正稀缺的是能把项目跑起来的配套说明。很多开源项目什么代码都给了唯独不给数据库初始化脚本或者给了脚本却不说明用哪个版本MySQL执行导致新手在各个报错之间反复挣扎。这个项目带文档意味着至少包含三样东西数据库初始化SQL、接口说明、部署运行指南。数据库初始化SQL是最关键的因为办公管理系统的表结构非常依赖设计部门表、用户表、审批表之间的外键关系通过SQL一眼就能看懂。接口说明在前后端分离的项目里也至关重要它告诉你登录接口返回什么字段、提交请假单需要传哪些参数、分页查询的page和limit怎么命名。有了这些后端的Controller层和前端的API封装才能对得上。具备完整文档的项目拿来做学习是特别顺畅的。你能直接从“已知能跑通的代码”往回倒推结构而不是在猜测中消耗热情。2. 部分核心模块的设计与实现路径2.1 用户权限模型RBAC的落地姿势办公系统里权限这块老实说方案可以复杂到上RBAC 数据权限 操作审计但实际项目中90%都用的是最经典的RBAC模型用户表、角色表、菜单表外加用户角色关联表和角色菜单关联表。这个项目的用户、角色、菜单三张主表外加两张关联表属于标准配置。我重点说一下菜单权限怎么控制。后端在用户登录成功后一次性查询出该用户所有可见的菜单以树形结构返回给前端。前端拿到菜单树后动态生成侧边栏和路由。这里有个实用细节菜单表里通常包含“父菜单ID”和“路由地址”两个字段。父菜单ID用来拼树路由地址对应前端Vue Router里配置的path。Vue 3中动态添加路由要用router.addRoute而且要注意在用户退出登录后重置路由不然下一个用户登录时会看到上一个用户的菜单残留。按钮级别的权限这个项目不一定做得很细但如果要做思路通常是在菜单表里加一个“按钮权限标识符”字段后端在查询用户菜单时一并返回前端用自定义指令控制按钮显隐。这类实现的好处是权限设计能覆盖到页面里的“新增”“删除”“导出”这些具体动作而不是只能控制到整个菜单。另外要提醒一句前端控制按钮显示只是体验层面的优化真正的安全校验必须在后端做。后端接口上加上权限注解比如PreAuthorize用SpEL表达式判断当前用户是否拥有指定权限标识这样即使有人跳过前端直接调API也会被拦截下来。2.2 数据库表设计的几个关键细节办公管理系统的数据库表通常在20到30张之间。比如这个项目会包含sys_user、sys_role、sys_menu、sys_dept、oa_notice、oa_leave、oa_attendance、oa_meeting这类表。这些表的设计有几个细节特别值得注意直接决定你后续开发的顺滑程度。逻辑删除标志是必须的。办公系统里的数据都是真实业务数据比如员工离职、公告撤销、请假单作废你不能真的把行删掉否则后续审计和统计都成问题。所以每张业务表都要有一个deleted字段MyBatis-Plus的TableLogic注解配上这个字段能实现“查询自动过滤已删除数据、删除操作自动转成更新”的效果。比如员工离职改成deleted1但考勤记录里依然能查到这个人当月的打卡数据。创建时间和更新时间这种审计字段建议每个表都要有。别小看这两个字段排查“2107这个单子是谁在什么时候建的”这类问题全靠它们兜底。MyBatis-Plus的字段自动填充功能可以做这件事实体类上标注TableField(fill FieldFill.INSERT)和TableField(fill FieldFill.INSERT_UPDATE)然后定义一个MetaObjectHandler的实现类在insert和update时自动填入当前时间省掉在每个Service里手动set时间的繁琐。审批状态字段的定义要提前统一。我见过不少项目等待审批用0同意用1驳回用2但到了会议审批模块状态含义就变了搞得前端写死一堆映射关系后期维护极其痛苦。正确的做法是定义一个统一的状态枚举比如用Integerstatus表示未提交、待审批、已通过、已驳回、已作废每个模块的表都复用这套约定前端再统一封装一个状态标签映射组件就不会出现各模块状态颜色对不上的尴尬。2.3 前后端交互约定的建立目前项目多为前后端分离开发。把交互约定先想清楚能省掉大量联调时间。接口返回结构统一是最基础的一条。这个项目的后端会定义一个统一响应体通常长这样{code: 200, message: 操作成功, data: {}}。所有Controller的返回值都放进这个壳子里。前端配合Axios拦截器在响应拦截器里判断code非200统一弹错误提示200则直接把data解出来用。这样后端只需专注业务逻辑和返回数据前端只需规范统一处理异常和成功分支。状态码设计上我建议区分两类HTTP状态码用于表示请求本身是否成功业务状态码用于表示业务逻辑是否成功。登录过期返回401权限不足返回403参数校验失败返回400这属于HTTP层语义至于“请假单已经在审批中不能重复提交”这类就属于业务状态码。在一套系统里后端把这两类区分清楚前端拦截器处理起来才不别扭。Date类型序列化的坑也要提前踩掉。后端LocalDateTime默认序列化成2025-04-15T10:30:00这种带T的ISO格式前端拿到手显示就会别扭。常见做法有二一是在Jackson配置中统一日期格式二是在实体字段上用JsonFormat(pattern yyyy-MM-dd HH:mm:ss)。对整个系统来说我更倾向全局配置不然每个字段都要加注解很容易漏。3. 实操过程与核心环节实现3.1 后端项目骨架搭建的关键步骤先把后端骨架搭起来。你拿到的源码结构一般会是这样一个Maven多模块或者单模块的Spring Boot工程包含controller、service、mapper、entity、dto、config、common这些包。第一步是改配置。application.yml里最重要的几个配置项包括数据源、Redis如果有、文件上传路径和日志级别。对于这套项目数据源配置必须注意MySQL 8.0的驱动类名。以前的com.mysql.jdbc.Driver已经不用了现在必须写com.mysql.cj.jdbc.Driver同时JDBC URL上要加上时区参数spring: datasource: url: jdbc:mysql://localhost:3306/oa_system?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai driver-class-name: com.mysql.cj.jdbc.Driver username: root password: 123456把数据源配置好后启动类上加上MapperScan注解扫描Mapper接口所在的包。MyBatis-Plus的插件配置也要在这个阶段配好主要是分页插件和乐观锁插件。分页插件直接关系到查询接口能否正确处理page和size参数不配的话写着PageUser的查询方法会退化成查全表再内存分页数据一多就卡成PPT。登录认证这块项目一般会用JWT。我建议你把JWT的密钥和过期时间放到配置文件里管理不要写在代码里。前端登录成功后拿到token后续每次请求通过Authorization请求头带上。后端用一个拦截器或过滤器去校验token校验通过后从token里解析出用户ID和用户名放在ThreadLocal或RequestScope里后续Service层需要知道“当前操作人是谁”时直接取省得每次从Controller手动传参。登录流程里还有个细节密码加密。不要用MD5一定要用带盐的哈希算法。BCrypt是主流选择。Spring Security自带BCryptPasswordEncoder项目如果是自己写拦截器实现的认证也可以单独引入Spring Security Crypto组件只用它的BCrypt加密工具。注册或初始化用户时存进数据库的必须是BCrypt加密后的密文而不是明文。这个问题在课设项目里出现频率特别高一定不要图省事存明文。3.2 前端Vue3部分的组织方式前端项目若用Vite构建那整体工程结构比Webpack时代的“义乌小商品市场”清爽得多。src目录下通常是api、views、components、router、store、utils这几个子目录。Axios封装是前端里面值得优先看的部分。一套好的Axios封装会在请求拦截器里自动把token加到请求头上在响应拦截器里统一处理业务错误码、HTTP错误码、登录状态过期。办公系统里会频繁出现“提交表单时后台返回‘该员工本月已提交过加班申请’”这样的业务错误拦截器里判断业务码统一弹Message提示前端每个页面的错误处理代码可以精简到只关心成功路径。路由和菜单的联动是Vue3项目里最考验封装功底的地方。这个项目的路由配置文件里静态路由通常只写登录页、404页这类公共页面业务页面全部走动态路由。登录成功拿到菜单数据后前端把这些菜单数据映射成RouteObject结构用router.addRoute动态挂载。菜单配置里带有图标名称时渲染侧边栏时需要异步加载Element Plus图标组件这个细节做不好菜单里的图标就会全部显示成空白方块。组件拆分层面办公系统的数据表格使用频率极高。强烈建议把“搜索表单 表格 分页”的套路抽成一个通用组件或组合式函数。这样用户管理页、公告管理页、考勤记录页都复用它只传入对应的列配置和查询API页面代码能减少一半。3.3 审批流的通用实现套路请假审批这个具体模块代码逻辑很值得手把手看一遍。它的数据库表通常长这样oa_leave表存请假单基础信息字段包含申请人ID、请假类型、开始时间、结束时间、请假天数、原因、当前状态oa_leave_record表存审批记录每个审批人审批一次插入一行包含审批人ID、审批意见、审批时间、审批结果。提交请假单时后端要做两件事。第一校验时间是否冲突比如同一个员工在同一时间段是否已有审批通过的请假单或者是否重叠了出差申请。第二把状态置为“待审批”并且向直属主管的待办列表里插入一条待办记录。这里的“直属主管”怎么确定最简单的方式是在部门表上有一个leader_user_id字段把你的用户表与该字段关联要找到部门Leader时直接查询用户信息。如果组织架构更复杂比如有副主管、有代理审批人那就得在部门表上扩展更多字段或者引入更完整的审核流程配置。审批人操作时点击“通过”后端做的是更新请假单状态为“已通过”同时在审批记录表插入一条结果。点击“驳回”同理只不过状态变成“已驳回”并且可以附带驳回原因返回到前端时在原表单下方显示红字原因。这套简单审批流最大的优点是容易看懂、容易改。你要让部门主管审批完跳过同级、直接到人事复核只需多加一个状态节点再加一条更新状态的判断逻辑改动成本很低。等业务复杂到需要多级审批、条件审批、并行审批时再考虑集成Flowable或Activiti就行没必要一开始就上重型框架。3.4 前后端联调时最容易卡住的几个点先把运行环境看好。后端默认端口通常8080前端开发服务器默认5173两者不在一个端口上。生产环境可以用Nginx把前后端放同一个域名下通过/api前缀把请求反向代理到后端绕开跨域开发环境则直接在后端配置CORS放行http://localhost:5173这个来源。后端配置CORS时注意要允许携带凭证。办公系统登录后如果采用Cookie Session方式那allowedHeaders里必须明确放行Authorization、Content-Type等常用请求头。如果使用JWT则请求多为无状态的Authorization头但仍然需要允许前端跨域读取响应头中的token信息。这里的细节在于允许凭证和允许所有来源不能同时为真allowedOrigins要精确到具体的开发地址否则浏览器会直接拦截。另外接口联调时最常遇到的是参数名对不上。后端分页接口若是用current和size前端就得传current和size后端的pageNum/pageSize前端就得跟着改。这类问题靠的是文档完全无法凭脑补解决。3.5 部署到服务器上的标准路径部署这块很多新手容易被卡住。核心思路是后端打包成Jar包运行前端打包成静态文件用Nginx托起来。后端Waymvn clean package -DskipTests java -jar target/oa-system-1.0.0.jar如果服务器内存有限可以用-Xms256m -Xmx512m限制JVM堆内存办公系统这种规模的项目勉强够跑。前提是服务器上加个Swap空间或者干脆把并发量压得低一点。前端构建npm install npm run build构建完后dist目录里的静态文件拷贝到Nginx的html目录下或者配置一个server块指向它。Nginx配置里最关键的一段则是反向代理把所有以/api开头的请求转发到后端接口服务上这样前端和后端都从同一个端口对外提供服务就不存在跨域问题了。location /api/ { proxy_pass http://127.0.0.1:8080/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; }这里有个细节proxy_pass http://127.0.0.1:8080/;末尾的斜杠会把/api/logout重写为/logout。如果你的后端Controller里的请求映射本身就带/api前缀那Nginx配置里斜杠的处理方式就要反过来。这个细节会导致接口404排查起来却很容易被忽略。4. 常见问题与排查技巧实录4.1 版本兼容性问题开发环境上最容易踩第一脚坑的就是JDK版本。Spring Boot 2官方推荐用JDK 8或JDK 11JDK 17虽然让很多上Spring Boot 3的项目受益但拿到这个项目源码时如果本地是JDK 17很可能会遇到编译错误因为依赖的旧库里有些反射调用或第三方字节码在17的模块系统下运行不了。稳妥的做法是在项目里配置Maven编译插件把source和target设为1.8并在本地装JDK 8或JDK 11来跑。Vue 3前端项目也有版本坑。不同Node版本下Vite构建有时会报出各种依赖冲突。解决办法是看package.json里的engines字段要求以及优先使用LTS版本的Node。记住一个原则项目锁哪个Node大版本就尽量用哪个不要无脑升级最新版。MySQL版本上8.0和5.7最明显的差异排序规则上。8.0默认字符集utf8mb4排序规则是这个较为严格的utf8mb4_0900_ai_ci而5.7常用的utf8mb4_general_ci。如果你把数据库导出后到另一台5.7服务器上恢复大概率出现字符集不支持的报错。所以在项目初始化脚本里建库语句直接把字符集写清楚别依赖MySQL全局默认配置CREATE DATABASE oa_system DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;4.2 跨域与登录态丢失前后端联调时“前端能登录但一刷新登录状态就没了”是高频问题。排查思路分两大类如果是JWT方案看前端是否把token持久化到localStorage或sessionStorage刷新页面后是否从store初始化如果token存了但还是丢失看路由守卫里拿token的判断逻辑留意当前用户信息是不是异步获取的要等接口返回后再放行页面跳转。如果是Session方案重点排查后端CORS配置有没有allowCredentials(true)前端Axios有没有配置withCredentials: true以及响应头里Set-Cookie的SameSite属性。特别是Chrome浏览器的新版本会对跨域带Cookie的行为限制得更严格很多旧项目上线后莫名登录失效都是SameSite属性没有设置成None造成的。4.3 时间与数字的“灵异问题”办公系统里最多的数据就是日期时间。考勤打卡、请假起止、审批时间每一个都涉及时间处理。我已经不止一次见过有人把LocalDateTime传到前端显示成2025-04-15T10:30:00.00000:00然后用户一脸懵地发现时间比真实时间少了8个小时。这个问题的根源是时区。MySQL连接串里如果不指定serverTimezone驱动会用JVM默认时区。国内服务器时区一般没问题但云数据库的服务器如果设在其他地区时区偏移就会很诡异。正确做法就是在JDBC URL里把serverTimezoneAsia/Shanghai固定下来。前端拿到时间后也要做格式化处理。要么后端统一返回格式化好的字符串比如yyyy-MM-dd HH:mm:ss要么前端写一个全局的日期格式化函数。不要在页面上到处访问时间字段然后各显神通地格式化同一套系统里时间展示格式出现三四套模样的混乱感用户第一眼就会觉得很不专业。4.4 MyBatis-Plus使用中的高频坑MyBatis-Plus虽然好用但有些坑不提前躲开排查起来相当费劲。最典型的是逻辑删除字段和唯一索引冲突。比如用户表里设置了用户名字段为唯一索引用MyBatis-Plus逻辑删除用户后该用户名下次再注册时由于数据库里实际还留着deleted1的旧记录会触发唯一索引冲突导致注册失败。解决办法是索引设计时把deleted字段作为联合唯一索引的一部分比如(username, deleted)这样逻辑删除后的同用户名就能再次注册。第二个问题是条件构造器里的eq和like大小写敏感问题。MySQL默认字符串比较不区分大小写如果你查username Admin可能把admin也查出来。办公系统里用户名如果是登录凭证建议数据库里用utf8mb4_bin排序规则或者在后端代码里统一转大写再比较避免账号大小写歧义。第三个问题是自动填充没生效。写成fill FieldFill.INSERT_UPDATE后如果MetaObjectHandler这个类忘了加Component注解后台创建人、创建时间就永远是空的。这类问题IDE不会自动报错只有等你查“为什么数据表里没有创建时间”时才会发现。4.5 前端常见的渲染与打包问题Vue3的setup函数里如果你用ref包了一个对象修改时不小心把整个对象重新赋值为新对象页面往往会重新渲染但如果你直接用const state reactive(...)来维护就不用担心这个问题。办公系统里那些“保存后列表没刷新”“弹窗关闭后表单还残留上次数据”的问题大多是因为响应式数据没有正确重置。打包上传后首页白屏也是前端新手常见痛点。Vite默认的base路径是/如果你的前端部署在Nginx子路径下比如http://server/oa/静态资源会去请求http://server/assets/xxx.js自然404。处理方法是在vite.config.ts里设置base: ./让打包后的资源路径变成相对路径。5. 项目文档与后续扩展方向5.1 “含文档”项目的正确打开方式拿到这种带文档的源码先不要急着import到IDE里就开跑。我的习惯顺序是先看README再看数据库初始化SQL最后才看代码。README会告诉你项目怎么启动、前后端用什么命令跑起来SQL能让你对表结构有个整体认知知道用户怎么造出来、有哪些模块代码则是到这一步才去看具体业务怎么实现的。跑通之后建议自己在数据库里随便改点东西、加个字段追踪这个字段在Controller、Service、Mapper、前端页面里走过的路径。这种“从数据库字段到前端按钮”的全链路追踪是理解一个项目的最佳方式。调试工具里给登录接口打个断点看看从请求进入Controller后一个参数是怎么一步步流转的比躺着读十遍代码都有用。5.2 如果你想在这个项目上继续加功能办公管理系统的扩展空间其实很大。最值得做的是把审批流真正完善起来。当前的简单审批流只支持一条线性路径你可以引入Flowable或Camunda把请假、报销、采购申请都纳入同一套流程引擎里去。这意味着要新增流程定义表、流程实例表、任务表前端的待办中心也要重新设计让它按任务类型而不是按业务表单类型去渲染。这个方向成熟后系统的可复用性会高出一个量级。其次是引入更细的权限划分。部门级数据权限可以考虑切面或注解的方式在部门经理的账号下限定只能看本部门数据而不是让他直接看到全公司所有人的考勤。这类“数据权限”是办公管理系统从“演示级”走向“生产级”的重要分水岭。再就是引入消息推送机制。现在的待办提醒很多停留在页面里的小红点如果能在企业微信或飞书的应用消息里同步推送“你有一条新的请假审批待处理”这会让整个系统的使用体验直接上一档。技术实现也不复杂抽出统一的消息服务接口对接企业微信或飞书的Webhook接口就行。如果你打算把它当作毕业设计或学习项目可以增加更直观的数据可视化仪表盘上展示本月考勤汇总、各部门请假趋势、审批平均时长。这部分用ECharts或者Vue3生态的图表库都能实现后端只需要提供聚合查询接口即可。写在最后的一段实操体会根据我个人经验Java Web类办公系统看起来业务简单但真正做到“办公又好用”其实很考验开发者的全局设计能力。这个项目能把Spring Boot 2 Vue 3 MyBatis-Plus MySQL 8.0这套组合整合得比较完整已经具备了一个生产级OA系统的雏形。拿到手之后建议从“用户登录→建单→审批→统计”这条主线跑一遍跑通后再去碰边角功能。最后再分享一个小技巧不管你是学习还是二次开发拿到这种项目第一件事就是备份数据库初始化SQL。然后在本地跑通后立刻执行一次全量导出生成一份自己的“恢复快照”。后面再怎么改代码、改了表结构、删了测试数据只要还能从这份快照恢复到初始状态你就有无限次重来的底气。办公管理系统的开发就是个不断试错的过程有这个保命手段在胆子就能大很多。