SpringBoot+Vue OA系统源码：前后端分离项目跑通与二次开发避坑指南-平芜编程栈

简介：基于Spring Boot与Vue构建的在线办公OA系统源码，面向计算机、通信、人工智能等专业学生、教师及从业者，适用于毕业设计、课程设计、期末大作业等场景，项目采用前后端分离架构，代码经过调试与测试可稳定运行，能帮助快速理解主流框架的整合与业务开发。压缩包共413个文件，以Java源码、XML配置与Class编译文件为主，同时包含Vue前端组件、JavaScript脚本及YML配置等，目录结构清晰，便于按模块学习后端接口、数据持久化与前端交互，包体约376KB，轻量紧凑，下载后即可快速部署。目前已有252人浏览学习，完成度较高，内容涵盖员工管理、薪资调整、邮件日志、菜单权限、考核评价等OA常见模块，可直接运行查看完整效果。基础较好的读者还可基于现有代码二次开发扩展功能，并与作者沟通答疑，获得实践指导。

1. 为什么一套 springboot+vue 的 OA 源码，值得你花一下午去跑通它

做后端这几年，我接过不少“给公司上一套 OA”的活儿，也见过太多团队在自研和买成品之间反复横跳。市面上现成的 OA 产品功能全，但定制一个审批流要等供应商排期；自己从零写，光用户角色权限、流程引擎、消息通知这三座大山就能磨掉一两个月。于是“基于 springboot+vue 的在线办公 OA 系统源码.zip”这种压缩包，就成了很多人的救命稻草——它听起来像是一个“黑匣子”，解压就能用，但实际跑通它，需要你对前后端分离、权限模型、工作流有足够清晰的认识。

这套源码解决的核心问题，是让你不用从空目录开始敲代码：springboot 负责后端接口和业务逻辑，vue 负责前端页面和交互，两者通过 RESTful API 通信。适合谁？一类是刚入门全栈、想找个完整项目练手的技术新人；另一类是小团队的技术负责人，想基于现成代码快速二次开发。但我要先泼一盆冷水：源码不是一键启动的玩具，环境版本不匹配、数据库初始化脚本缺失、前端跨域配置错误，任何一个坑都能让你卡半天。这篇笔记，就是把我自己跑通这类项目的经验拆开讲清楚，从选型理由到参数配置，再到排错记录，尽量让你少走弯路。

2. 跑通前后端分离的 OA 系统：先认清这套源码的骨架和选型逻辑

2.1 为什么选 springboot+vue，而不是别的组合

在线办公 OA 系统最常见的落地形态就是前后端分离，而 springboot + vue 几乎是国内中小团队事实上的标准组合。springboot 的优势在于起步快、生态成熟，内嵌 Tomcat、自动配置、Starter 机制让后端服务能在一个 main 方法里直接跑起来；vue 的优势在于组件化开发、响应式数据绑定，加上 Element UI 这类现成组件库，做后台管理界面效率极高。相比 SSM 传统架构，springboot 省掉大量 XML 配置；相比若依等重型框架，这个组合又足够轻，适合我们理解核心逻辑。

选择这个组合还有一个现实原因：招聘市场上熟悉 springboot+vue 的开发者最多，后续维护和二次开发不会找不到人。对于 OA 这种强业务场景的系统——需要做用户管理、部门管理、审批流程、通知公告——前后端分离能让后端专心写业务接口，前端专心做交互页面，两者通过 JSON 数据对接，职责清晰。如果你拿到手的源码还整合了 MyBatis-Plus 和 Redis，那说明封装程度不错，CRUD 和缓存这块能省很多事。

2.2 源码目录结构：先别急着启动，先看懂每个文件夹干什么

解压“基于springboot+vue的在线办公OA系统源码.zip”之后，你会发现里面通常有两个主要目录：一个后端工程（一般是oa-backend或直接叫项目名），一个前端工程（一般是oa-frontend或web）。很多新手上来就双击 idea 打开整个文件夹，结果前后端代码混在一起，启动时各种报错。正确做法是先分清楚目录职责。

以我见过的典型工程结构为例，后端目录会包含src/main/java下的 controller、service、mapper、entity 分层，src/main/resources下的application.yml配置文件和 mapper XML；前端目录则包含src/views下的页面组件、src/router下的路由配置、src/api下封装的请求模块。如果你看到的目录里还有sql或db文件夹，里面大概率放着数据库初始化脚本——这是最关键的资产，没有它后面全白搭。

# 典型的源码包解压之后大概长这样，先记结构再动手 oa-system/ ├── backend/ # springboot 后端工程 │ ├── src/main/java/... # Java 源码 │ ├── src/main/resources/ │ │ ├── application.yml # 后端配置文件 │ │ └── mapper/ # MyBatis 的 XML 文件 │ └── pom.xml # Maven 依赖配置 ├── frontend/ # vue 前端工程 │ ├── src/ │ │ ├── api/ # 封装 axios 请求 │ │ ├── router/ # 前端路由表 │ │ ├── views/ # 页面级组件 │ │ └── main.js # 前端入口 │ ├── package.json # npm 依赖清单 │ └── vite.config.js # 前端构建配置，注意跨域代理 └── sql/ └── oa_init.sql # 数据库初始化脚本，命根子

这个结构本身给我们两条重要信息：第一，后端必须通过 Maven 拉取依赖，前端必须通过 npm 或 pnpm 安装依赖，两条链路不能混；第二，数据库脚本和配置文件之间通过数据库名、用户名密码强关联，改任何一个都要同步。很多翻车现场就是因为把application.yml里的数据库密码改了，但没注意脚本里初始数据的密码加密方式。

2.3 数据库脚本和配置文件：启动前必须核对的三件事

在写任何启动命令之前，建议先打开application.yml和 SQL 脚本检查三件事。第一是数据库版本，我用 MySQL 8.0 跑这类项目最省心，5.7 也兼容但要注意驱动版本差异；第二是连接参数，url、username、password是否和你本地环境一致；第三是脚本里的库名和配置里的库名是否对得上——见过有人把脚本导入到test库，但配置里连接的是oa_db，启动直接报表不存在。

常见的application.yml配置项大致长下面的样子。要注意driver-class-name新版驱动是com.mysql.cj.jdbc.Driver，老版本写法com.mysql.jdbc.Driver在 MySQL 8 下会报警告甚至失败。redis配置如果源码里有，记得本地先启动 Redis 服务，否则缓存相关的接口会超时。

server: port: 8080 spring: datasource: url: jdbc:mysql://localhost:3306/oa_db?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai username: root password: 你的数据库密码 driver-class-name: com.mysql.cj.jdbc.Driver redis: host: localhost port: 6379 database: 0 mybatis-plus: mapper-locations: classpath*:mapper/**/*.xml configuration: map-underscore-to-camel-case: true

2.4 前端工程的关键配置:跨域代理和接口地址

前端能连上后端，靠的是vite.config.js里的代理配置。开发环境下前端跑在 5173 端口，后端跑在 8080 端口，浏览器直接请求跨域会被拦，所以要让 vite 把/api开头的请求代理到http://localhost:8080。这个配置如果你没核对就启动，前端页面能打开，但所有列表数据都会加载失败。

// vite.config.js — 开发环境的跨域代理，必配 import { defineConfig } from 'vite' import vue from '@vitejs/plugin-vue' export default defineConfig({ plugins: [vue()], server: { host: '0.0.0.0', port: 5173, proxy: { '/api': { target: 'http://localhost:8080', // 后端服务地址 changeOrigin: true, // 如果后端接口路径本就带 /api，不要做 rewrite // 如果后端不带 /api，需要取消下面这行的注释 // rewrite: (path) => path.replace(/^\/api/, '') } } } })

这里有一个最常见的分歧点：有的源码后端 Controller 的@RequestMapping里已经带了/api前缀，有的没带。如果前端封装的 axios 请求统一以/api开头，而后端路径没有对应前缀，你看到的现象就是所有请求返回 404。处理方式就一句话：保持路径匹配，要么改代理配置加 rewrite，要么改后端的 context-path。我建议优先用后端的server.servlet.context-path: /api来统一，改一处全局生效。

// src/api/request.js — axios 封装，统一加前缀和拦截器 import axios from 'axios' const request = axios.create({ baseURL: '/api', // 配合 vite 代理使用 timeout: 15000 }) request.interceptors.request.use(config => { const token = localStorage.getItem('token') if (token) { config.headers.Authorization = token } return config }) request.interceptors.response.use( response => { const res = response.data if (res.code !== 200) { alert(res.msg || '请求失败') return Promise.reject(new Error(res.msg)) } return res }, error => { if (error.response && error.response.status === 401) { window.location.href = '/login' } return Promise.reject(error) } ) export default request

后端在过滤器或拦截器里解析Authorization请求头，如果前端没有在拦截器里把这个 token 带上去，就会一直提示未登录或 401。很多新手把注意力全放在业务代码上，忽略了这一层封装，导致登录接口能通，但后续所有业务请求全部因鉴权失败——这属于本源码跑通里最典型的“登录成功但进不了系统”问题。

3. 把后端跑起来：Maven 依赖、数据库初始化和 SpringBoot 启动参数调优

3.1 用 Maven 拉依赖：第一次构建你需要有点耐心

后端工程跑起来的第一步是 Maven 构建。常见的做法是用 IDEA 打开backend目录（注意是打开这个子目录，不是整个解压目录），让 IDEA 识别成 Maven 项目，然后等待依赖下载完成。如果你网络环境一般，第一次构建可能要花 5 到 15 分钟，因为 springboot 相关依赖加上 MyBatis-Plus、Redis、JWT 这些库，加起来体积不小。我通常会先配置阿里云 Maven 镜像，把下载速度提上来。

<!-- 在 maven 的 settings.xml 里配置镜像，国内下载依赖提速的常用手段 --> <mirror> <id>aliyunmaven</id> <mirrorOf>central</mirrorOf> <name>阿里云公共仓库</name> <url>https://maven.aliyun.com/repository/public</url> </mirror>

依赖下载完成后，执行clean和install，如果BUILD SUCCESS，说明后端工程的依赖闭环了。这一步卡住最常见的原因是 JDK 版本不匹配——springboot 2.x 用 JDK 8 最稳，springboot 3.x 必须 JDK 17 以上。如果你的源码里pom.xml写的spring-boot-starter-parent版本是 2.7 左右的，本地 JDK 最好不要用 17，遇到编译报错先检查这里。

3.2 导入数据库：初始化脚本的顺序和执行细节

打开sql目录下的初始化脚本，我一般用 Navicat 或命令行执行。如果你看到的是多个 SQL 文件，注意执行顺序；如果是单个oa_init.sql，通常已经包含了建库和插入数据的完整流程。执行完成后，重点检查三张核心表：用户表、角色表、用户角色关联表，因为 OA 系统的登录和权限控制全靠它们。

-- 典型 OA 系统的三张核心权限表结构 CREATE TABLE sys_user ( id BIGINT PRIMARY KEY AUTO_INCREMENT, username VARCHAR(50) NOT NULL UNIQUE, password VARCHAR(100) NOT NULL, -- 存加密后的密文 real_name VARCHAR(50), status TINYINT DEFAULT 1, create_time DATETIME ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4; CREATE TABLE sys_role ( id BIGINT PRIMARY KEY AUTO_INCREMENT, role_name VARCHAR(50) NOT NULL, role_code VARCHAR(50) NOT NULL ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4; CREATE TABLE sys_user_role ( user_id BIGINT NOT NULL, role_id BIGINT NOT NULL, PRIMARY KEY (user_id, role_id) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

这里提醒一句：脚本里的初始密码一般是加密过的，可能是 MD5 或 BCrypt。MD5 加密的密码你还能搜一搜原文，BCrypt 就不要尝试解了，直接登录默认账号（比如脚本注释里写的admin/123456）。如果你改了数据库里密码字段，但不知道对应的加密方式，登录永远会失败——这是又一个非常容易翻车的点。我一般习惯拿到源码先看pom.xml里有没有spring-security-crypto这个依赖，有就是 BCrypt，然后用相应的工具类生成新密码。

# 命令行导入示例（MySQL 8） mysql -u root -p < sql/oa_init.sql # 执行后应看到多条 Query OK，最后一条是创建存储过程或插入系统配置 mysql -u root -p -e "use oa_db; show tables;"

3.3 启动后端：端口冲突和 JVM 参数的常见坑

一切就绪后，在 IDEA 里直接运行main方法，或者在命令行用mvn spring-boot:run启动。如果启动过程中控制台输出Tomcat started on port(s): 8080，说明后端已经活了。但这里有两个高频问题：一是端口被占用，日志会直接提示Port 8080 was already in use，解决办法是把其他程序关掉，或者改端口；二是启动成功但接口返回的 JSON 格式和前端预期不一致，这个往往是Jackson序列化配置的问题。

# 如果端口被占用，先找到占用进程再决定下一步 lsof -i :8080 # 或者用 spring-boot 启动参数临时换个端口，比如 8081 mvn spring-boot:run -Dspring-boot.run.jvmArguments="-Dserver.port=8081"

我习惯在启动前检查application.yml里的spring.datasource.initialization-mode参数，如果设成了always，每次启动都会尝试执行脚本里的数据初始化语句，可能导致主键冲突或重复插入。正确做法是设为never，只在第一次手动导入脚本。还有生产环境相关的spring.datasource.druid.stat-view-servlet参数，如果源码里集成了 Druid，建议把login-enabled打开并设置初始账号密码，免得监控台裸奔——虽然本地跑无所谓，但这个习惯要养好。

3.4 后端调试技巧：日志级别和接口自测

后端启动成功后，别急着开前端，先用 curl 或 Postman 自测几个核心接口。常见的做法是先把application.yml里logging.level改成 debug，这样 MyBatis 的 SQL 会全部打印出来，接口报错时你能直接看到 SQL 语句是否拼接正确、参数是否正确绑定。

logging: level: com.oa.mapper: debug # 打印 mapper 层 SQL，排错关键 org.springframework.security: info

# 用 curl 登录接口测试，拿到 token 说明鉴权链路通了一半 curl -X POST http://localhost:8080/api/auth/login \ -H "Content-Type: application/json" \ -d '{"username":"admin","password":"123456"}' # 期望返回一个包含 token 字段的 JSON，例如 {"code":200,"data":{"token":"eyJhb..."}}

如果登录接口返回的是 500，先看后端控制台有没有 SQL 异常；如果是自定义错误码，通常是业务逻辑校验拦截了。自测这个步骤非常关键，它能帮你把后端和前端之间的变量彻底隔离——如果这时候已经发现接口有问题，就不要带着坏后端去启动前端，不然你会同时面对前端报错和后端报错的双重夹击。

4. 把前端跑起来：npm 安装、Vue 路由权限和代理调试

4.1 安装依赖：npm install 翻车时的备用方案

前端工程拿到手，第一件事是cd frontend && npm install。这一步卡住通常有几个原因：Node 版本太老或太新，vite 版本对 Node 有明确要求；npm 镜像慢，等半天以为卡死了；依赖之间有冲突，ERESOLVE错误。我一般直接用 pnpm 替代 npm，速度快且对依赖提升更严格。

# 先检查 node 版本，vite 5 需要 Node 18+ node -v # 用 npm 安装，失败时清缓存重试 npm install --registry=https://registry.npmmirror.com # 或者用 pnpm，速度更快 pnpm install

安装完成的标准是出现了node_modules目录，并且在命令行执行pnpm run dev后看到Local: http://localhost:5173/。如果启动报错，优先看报错里关于vite和vue-router的版本信息——有些残缺源码的依赖版本互相不兼容，npm install能过但运行时会白屏。这时候的常用方案是手动修复package.json里的版本号，把 vue 和 vite 对齐到官方兼容组合。

4.2 登录页到首页的链路：token 存储和路由守卫

前端能启动只是第一步，从登录页进入首页是另一道坎。得益于前面 axios 封装里写了从localStorage取 token，路由守卫会检查用户有没有登录凭证。如果这个守卫逻辑缺失，前端不会阻止未登录用户访问页面，但后端接口会 401，页面就永远处于“已经跳进首页但所有数据加载失败”的状态。标准做法是在src/router/index.js里配置全局前置守卫。

// 路由配置：定义无需登录就能访问的页面 const routes = [ { path: '/login', component: () => import('../views/Login.vue') }, { path: '/', component: () => import('../layout/Index.vue'), redirect: '/dashboard', meta: { requiresAuth: true }, children: [ { path: 'dashboard', component: () => import('../views/Dashboard.vue') }, { path: 'process', component: () => import('../views/Process.vue') } ] } ] router.beforeEach((to, from, next) => { const token = localStorage.getItem('token') if (to.meta.requiresAuth && !token) { next({ path: '/login' }) } else { next() } })

前端路由和后端接口一样，都遵循一个原则：页面级权限靠路由守卫不够，最终得靠后端接口的数据权限强校验。如果你拿到的源码里只有前端路由守卫，没有后端接口的权限拦截，那这套系统严格来说只做了“显示层控制”，一旦有人绕过前端直接调接口，权限就形同虚设。二次开发时这是优先要补的短板。

4.3 登录成功后白屏或报错的前端排查思路

登录成功但页面白屏，是一个信号混合的问题。先打开浏览器控制台 Network 标签，看请求有没有到 8080；再看 Console 标签有没有红色报错；如果报错是TypeError: Cannot read properties of undefined (reading 'xxx')，通常是后端返回的数据结构里没有前端预期的字段。比如后端返回{code, message, data}而前端取的是res.data.rows，这里就是数据契约不一致导致的翻车现场。

我常用的排查方法是先在浏览器里直接访问后端接口，确认返回值结构，再回头改前端响应拦截器或页面里的取值方式。还有一类情况是 Element UI 版本和 vue 版本不匹配，报错诸如Failed to resolve component: el-table之类的，这种不是工程问题，是组件库的版本兼容问题，升级或锁定版本即可。前后端联调阶段，原则就四个字：先网络、再控制台、最后看代码逻辑，按这个顺序能省下大量时间。

5. 避坑手册：从“跑不起来”到“数据不对”的 5 个高频问题排查

5.1 “启动就报错”和“启动不报错但页面打不开”是两种心态

遇到 springboot 启动时 Java 编译错误，不要慌：先把pom.xml里 Spring Boot 和 JDK 版本对齐。Spring Boot 2.5 以下对 JDK 17 直接编译失败，这是最常见的问题，启动类所在包路径和@SpringBootApplication扫描路径不匹配也会产生大量Consider defining a bean of type错误——现象是接口死活找不到 Service。这种情况下解决办法就是检查包名结构，把启动类放到com.oa根包下，确保扫描到所有 Bean。前端也一样，页面能不能打开不代表能正常工作，路由守卫、代理地址错误、token 失效都会让页面打开但数据空白。区分这两种现象，能帮你快速锁定问题属于前端后端的哪一边。

# 翻车场景 1：后端报这个错，就是启动类包路径不对 # "Description: Field userService in com.oa.controller.* required a bean of type 'com.oa.service.UserService'" # 解决：把主类移回 controller/mapper/service 的共同父包下

5.2 数据库密码正确却连不上 MySQL：时区和驱动问题

这类问题在 MySQL 8 下尤其常见。现象是日志报Public Key Retrieval is not allowed或The server time zone value 'ÖÐ¹ú±ê×¼Ê±¼ä' is unrecognized。原因一个在连接串没加serverTimezone=Asia/Shanghai，一个在连接串没加allowPublicKeyRetrieval=true。解决方式很简单：复制这条连接串，缺什么补什么。密码正确但不认，通常就是驱动版本或连接参数问题，不是密码问题。

5.3 前端控制台一直 404：先把代理和后端路径对齐

前端所有请求 404，这个现象我见过不下十次。原因不外乎后端端口没起来、代理 target 写错、后端 context-path 配置不一致。检查顺序是：用 curl 直接访问后端地址，确认服务活着；再检查 vite 代理配置；最后看后端server.servlet.context-path有没有设置。三个地方对不上，404 就是你唯一能看到的回报，而且是前端后端都不打印错误日志的那种。

5.4 Redis 没启动导致 “连接超时” 和 “操作失败”

很多 OA 源码喜欢用 Redis 存验证码和在线用户状态，如果你没启动 Redis，登录或获取部门列表接口会卡住或报RedisConnectionFailureException。解决的方案是本地装上 Redis，redis-server一键启动，或者如果你只是想让功能跑起来，可以把源码里 Redis 相关配置临时注释掉——不过不推荐，因为缓存逻辑牵扯到 token 有效期，注释掉后行为可能变得奇怪。

# 启动本地 Redis（Windows 或 mac 都类似） redis-server # 看到 "Ready to accept connections" 就说明 OK redis-cli ping # 返回 PONG

5.5 功能能用但审批流乱套：流程设计器的表结构设计是最容易欠债的地方

OA 系统的核心不止是 CRUD，审批流才是灵魂。很多源码的表结构里只有一张process_instance表，没有独立的流程定义表和审批记录表，导致你和业务方提“加一层审批”需求时，代码改动量巨大，这也是为什么标题里的 OA 源码值钱在流程引擎——可如果你拿到的源码只是把状态字段在业务表里硬写死，那就是个演示系统，不是生产级 OA。二次开发时先画清楚流程的角色节点图，再对应表结构，而不是上来就在代码里硬编码判断，否则以后每一次需求变更都是一次大改。

提示：这一条属于“源码选型”层面的避坑。跑通功能不难，难在选到一套表结构能支撑后续流程扩展的底子。如果发现流程是硬编码的，趁早换源码，别在它上面投入太多业务。

6. 把系统改造得能用于生产：JWT 刷新、权限细化和其他进阶技巧

当登录、用户、权限、通知这些基础功能都稳定跑起来后，下一步不是急着部署上线，而是整理代码里那些“只够演示”的地方。我个人经历里，这类 OA 源码最需要改造的是三块：token 续期与踢人下线的机制、按钮级权限和部门级权限，以及把内置的模拟数据替换成真实业务数据。

先说 token 续期和强制下线。很多源码用的是 JWT，登录后 token 存在浏览器 localStorage 里，后端每个请求解析一次，但没有 token 失效前强制踢人的能力。生产环境你可能需要：用户在别处被顶下线、管理员禁用账号后立刻失效、token 刷新机制。我在做这类改造时，一般会在后端加一个 Redis 黑名单，记录用户 ID 到 token 的对应关系，当管理员禁用账号时往里面塞一个失效标记。前端响应拦截器里检测到 401 就跳登录页，这对使用者来说体验就正常了。

再说权限细化。路由级权限只是第一层，按钮级权限才是真正接入业务的关键。一个部门经理能看本部门的审批列表但看不到其他部门的，这才是 OA 需求里最常见的诉求。完善的方案是后端接口里注入数据权限注解，通过部门表上下级关系来动态拼接查询条件；前端根据用户的按钮权限列表用v-permission指令隐藏“批准”“驳回”按钮。这一步一旦做扎实，系统的可用性会有本质提升。

@GetMapping("/process/list") @PreAuthorize("hasPermission('process:list:query')") public Result processList(@RequestParam Long deptId) { // 数据权限拦截：强制拼接 dept_id = 当前用户所属部门 QueryWrapper<ProcessInstance> wrapper = new QueryWrapper<>(); if (!isSuperAdmin()) { wrapper.eq("dept_id", getCurrentUserDeptId()); } return Result.success(processService.list(wrapper)); }

最后是数据初始化与回归测试。把源码自带的模拟数据清理干净，导入真实员工和组织架构，逐条核对审批流的每一步跳转是否符合预期。我自己的习惯是维护一个“测试账号清单”和“每个角色的预期权限矩阵”，每次改动代码后按清单过一遍，比盲测高效得多。像把请假流程从“部门经理 → 人事”改成“部门经理 → 分管副总 → 人事”，这种需求看似小，但会牵动表单字段、审批记录、通知模板多个表，回归时最容易翻车。

回到最开头的问题：这套源码值得你花时间跑通和改造吗？我的回答是值得，前提是你把它的定位搞清楚。它不是一个开箱即用的商业产品，而是一套能让你在真实业务场景里快速搭建骨架、理解平台型系统关键设计的起点。你可以从跑通它获得项目经验值，从改造它锻炼二次开发能力，但不要指望它在不投入任何维护工作的情况下扛住生产压力。