SpringBoot+Vue前后端分离合同管理系统实战：权限、审批、部署全解析

1. 项目概述这套系统到底能做什么最近整理前后端分离项目源码时把“可盈保险合同管理系统”又重新过了一遍。这是一个基于 SpringBoot Vue MyBatis MySQL 的完整项目后端是 Spring Boot 提供的 REST API前端是 Vue 单页应用数据层由 MyBatis 的 Mapper XML 来管存储统一放在 MySQL。它不是一个只有 CRUD 的教学 demo而是把保险合同从录入、审批、缴费、到期提醒到统计分析这条业务链路完整跑通的系统源码拿来就能部署部署教程也直接照着做就行。保险公司的合同管理比普通合同要麻烦得多。普通合同签完归档就完事保险合同要长期跟踪投保人、被保人、缴费计划、保单生效日期、终止日期、续保状态还要走内部审批流程。用 Excel 管这些数据数量少的时候还能应付一旦过百份合同查一份历史审批意见都要翻半天。可盈这套系统就是要解决这个痛点把合同主档、审批记录、缴费计划全部结构化存库通过前后端分离的页面操作让业务员、审批人、财务、系统管理员各司其职。这套系统最适合两类人参考一类是正在做 Java 课设、毕设的学生项目代码量适中没有若依那种大而全的框架包袱但完整度足够让你讲清楚业务和架构另一类是刚入门的初级开发想看看一个真实的前后端分离项目里用户权限、分页查询、状态流转、部署发布这些环节到底是怎么串起来的。如果你已经能写简单的 SSM 增删改查但还没独立做过一个带权限、带审批、带报表的完整系统那这套源码就是很好的下一步练手对象。2. 技术选型为什么固定用 SpringBoot Vue MyBatis MySQL2.1 后端用 Spring Boot 而不是 SSM 手写配置后端核心用的是 Spring Boot这在 2024 年已经没有太多争议。选它不是因为“大家都在用”而是因为它解决了一套真实项目最烦的问题环境配置。SSM 时代光 spring-mvc.xml、spring-mybatis.xml、web.xml 就能折腾半天Spring Boot 用自动配置把这些都隐掉了一个 application.yml 就能管住数据源、MyBatis 和端口。保险合同管理这种业务对事务和权限的要求很直接。审批通过要同时更新合同状态、插入审批记录、记录操作日志任何一个环节失败都不能留下脏数据所以我大量使用 Spring 的Transactional回滚逻辑由框架保证。Spring Boot 自带的 Tomcat 让部署也简单后端打成 jar 包只要目标机器装了 JDK一条命令就能跑起来不用再单独装 Tomcat。2.2 前端用 Vue Element Plus 做后台交互前端用的是 Vue 3 Vite Element Plus。Vue 做这类管理系统非常顺手组件化开发让合同列表、审批表单、用户管理这些页面可以拆成一个个组件互相不干扰。配合 Vue Router 做前端路由Axios 统一处理接口请求和 token 携带Element Plus 直接提供表格、分页、弹窗、表单校验组件省去自己造轮子的时间。我特别在意的一点是前端和后端必须彻底分离。后端只返回 JSON不做页面跳转前端只调接口不碰 JSP、Thymeleaf。这样开发时前端可以独立启动 mock 调试部署时前端打包成静态资源扔给 Nginx后端 jar 独立跑两边互不阻塞。对于一个小团队来说这种前后端分离模式是能长期维护下去的。2.3 MyBatis 适合保险合同这种复杂动态查询选 MyBatis 而非 JPA 的原因并不复杂合同管理里的查询条件太不固定了。按合同状态查、按投保人姓名查、按产品类型查、按承保日期范围查、按缴费逾期状态查这些条件经常会组合在一起用 MyBatis 的 XML 写动态 SQL 非常顺手一眼就能看清最终的 SQL 长什么样。这套源码没有强行用 MyBatis-Plus而是保留了原生 MyBatis XML Mapper 的方式。我故意这样做的原因是希望初学者能理解Mapper 接口 - XML SQL - 结果映射这条链路而不是无脑继承一个BaseMapperT到出了问题都不知道 SQL 在哪。你之后想换 MyBatis-Plus把 Mapper 继承改一下SQL 逻辑基本不用动。2.4 MySQL 撑住合同数据的存取存储层是 MySQL版本 8.0。坦白说这个项目的数据量级别用 MySQL 完全足够而且生态最成熟、资料最多学生和初级开发最容易上手。建库时字符集统一用utf8mb4排序规则utf8mb4_general_ci这样投保人姓名里出现生僻字或者备注里写 emoji都不会存不进去。对于合同管理系统单库单表是合理的起点以后数据量真涨起来了再按合同年度拆表加归档策略也不迟。3. 核心模块与数据库设计3.1 功能模块拆成四大块整套系统按照业务边界拆成四个核心模块没有为了凑功能硬塞东西。合同管理合同的新增、编辑、查询、删除支持上传附件合同编号唯一列表页支持多条件组合筛选和分页。审批流管理业务员提交审批主管审批通过或驳回所有审批意见写入审批记录表形成可追溯的链条。缴费管理记录每份合同的缴费计划包括每期保费、缴费日期、实缴状态逾期部分有标记。系统管理用户管理、角色管理、菜单权限管理、操作日志。这四个模块正好构成一个能跑真实业务的完整闭环。3.2 合同主表如何设计保险合同的业务核心都放在biz_contract表里。我建表的思路是主表只存合同本身的稳定信息像投保人、被保人、产品、保费、起止日期、状态缴费计划、审批记录单独建表通过外键关联主表 ID。这样查询主表列表时不会因为关联子表而出现重复行分页时 total 也永远是对的。CREATE TABLE biz_contract ( id bigint NOT NULL AUTO_INCREMENT, contract_no varchar(32) NOT NULL COMMENT 合同编号, contract_name varchar(128) NOT NULL COMMENT 合同名称, customer_name varchar(64) NOT NULL COMMENT 投保人姓名, insured_name varchar(64) DEFAULT NULL COMMENT 被保人姓名, product_name varchar(128) DEFAULT NULL COMMENT 保险产品, premium_amount decimal(12,2) NOT NULL DEFAULT 0.00 COMMENT 总保费, start_date date DEFAULT NULL COMMENT 生效日期, end_date date DEFAULT NULL COMMENT 终止日期, status varchar(20) NOT NULL DEFAULT DRAFT COMMENT DRAFT-草稿/PENDING-审批中/ACTIVE-生效/REJECTED-驳回/EXPIRED-到期/TERMINATED-终止, create_by bigint DEFAULT NULL, create_time datetime DEFAULT CURRENT_TIMESTAMP, update_time datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, PRIMARY KEY (id), UNIQUE KEY uk_contract_no (contract_no), KEY idx_status (status), KEY idx_customer_name (customer_name) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4 COMMENT保险合同主表;合同编号一定要建唯一索引。业务上合同编号是线下纸质合同和系统电子合同的对应凭证一旦允许重复后续对账和检索都会乱套。状态字段我用的是字符串而不是数字虽然多占一点空间但可读性非常好查数据时不用对着数字翻字典。3.3 权限模型用 RBAC权限部分用的是经典 RBAC 模型三张基础表用户表、角色表、菜单权限表再加用户角色关联表和角色菜单关联表。登录成功后后端会算出当前用户拥有的权限码列表连同用户 ID、过期时间一起放进 JWT 返回给前端。前端拿到 token 存进 localStorage每次请求通过 Axios 拦截器塞到请求头里后端写了一个基于 AOP 的自定义权限注解接口上标RequirePermission(contract:approve)就能自动校验。这套权限模型不算新颖但它真实、可靠、好解释。课上和面试里你都能讲清楚用户属于哪些角色角色有哪些菜单和按钮权限后接口怎么拦截前端菜单怎么动态渲染。不用无脑把整个若依框架搬进来自己手动实现一遍之后你对“权限系统”的理解会完全不一样。4. 关键功能实现细节4.1 登录鉴权和前端路由守卫登录接口做的事很常规接收用户名密码校验验证码如果有比对密码生成 JWT。JWT 我用的 HS256 签名密钥写在配置里。生产环境密钥一定要单独配置且长度至少 32 字节别用默认值否则别人能直接仿造 token。生成代码核心如下String token Jwts.builder() .setSubject(username) .claim(userId, userId) .claim(perms, permsList) .setIssuedAt(new Date()) .setExpiration(new Date(System.currentTimeMillis() 86400000L)) .signWith(SignatureAlgorithm.HS256, secretKey.getBytes(StandardCharsets.UTF_8)) .compact();前端路由守卫的作用是防止未登录用户直接通过 URL 访问页面。在 Vue Router 的beforeEach里判断一下 token 就行router.beforeEach((to, from, next) { const token localStorage.getItem(token) if (to.path /login) { next() } else if (!token) { next(/login) } else { next() } })只判断“有没有 token”是不够的token 可能过期。所以 Axios 的 response 拦截器里还要处理 401收到 401 就清掉本地 token跳回登录页并给出“登录已过期”的提示。这两层配合才能真正拦截掉绝大部分未授权访问。4.2 MyBatis 分页插件的用法与避坑列表页的分页是这个项目里最容易出问题的地方。我这里用的是 PageHelper 分页插件因为配置简单引入依赖后写 Service 层时逻辑很干净PageHelper.startPage(pageNum, pageSize); ListContractDO list contractMapper.selectContractPage(query); PageInfoContractDO pageInfo new PageInfo(list);PageHelper.startPage会拦截下一个执行的 Mapper SQL自动把它改写成带LIMIT的分页语句同时查询 count 总数。执行完selectContractPage之后PageInfo里就有list、total、pageNum、pageSize、pages等字段前端分页组件直接消费。这里有三件事必须注意startPage后面必须紧跟着执行真正的 Mapper 查询中间不要再调其它 SQL 查询否则分页会串到那个查询上结果总数永远不对。分页查询的 SQL 尽量不要LEFT JOIN一对多子表。比如一张合同对应多条缴费计划如果 join 后查询List 长度会变大total就会虚高。正确做法是先分页查主表再按主表 ID 批量补子表数据。排序字段不要直接拼接用户传入的参数比如前端传sortField你直接ORDER BY ${sortField}这是 SQL 注入的高危写法。应该维护一个白名单映射用户传createTime时后端转成真实列名create_time。另外MyBatis 二级缓存我建议在这个项目里直接关闭。合同主表会关联审批记录、缴费计划涉及多表 join 时二级缓存很难保证一致而一级缓存默认的 SqlSession 级别已经够用。为了那点阅读性能提升换来“数据改了半天界面上还是旧值”的坑完全划不来。4.3 合同审批状态流用乐观更新防并发合同审批模块很能体现真实项目的严谨性。一张合同提交审批后业务员和主管可能同时在多个窗口操作如果后端的更新逻辑只是“先查出合同判断状态再 update”很容易出现两个人同时审批同一张合同都以为自己批了。我的做法是状态更新使用条件更新并检查影响行数。SQL 上大概是这样的Transactional(rollbackFor Exception.class) public void approve(Long contractId, boolean pass, String comment) { ContractDO contract contractMapper.selectById(contractId); if (contract null || !PENDING.equals(contract.getStatus())) { throw new BizException(当前状态不允许审批); } String targetStatus pass ? ACTIVE : REJECTED; int updated contractMapper.compareAndSetStatus(contractId, PENDING, targetStatus); if (updated ! 1) { throw new BizException(合同已被其他用户处理请刷新后重试); } approvalRecordMapper.insert(contractId, pass, comment, SecurityUtils.getUserId()); }核心是compareAndSetStatus对应的更新语句UPDATE biz_contract SET status #{targetStatus} WHERE id #{contractId} AND status PENDING只要影响行数不等于 1说明状态已经被别人改了事务直接回滚不会产生两条审批记录。这个“乐观更新”思路在订单、审批、库存这类并发修改场景里非常通用学会了你在其它项目里也能直接套。4.4 合同到期提醒任务的实现保险合同最怕的是到期忘续保。这个项目里用 Spring 的定时任务Scheduled做了自动扫描每天早上 7 点查一次end_date在未来 30 天内且状态为ACTIVE的合同然后给负责的业务员生成站内提醒。核心逻辑大概是Component public class ContractRemindTask { Scheduled(cron 0 0 7 * * ?) public void scanExpiringContracts() { ListContractDO list contractMapper.selectExpiringContracts(30); for (ContractDO contract : list) { remindService.createRemind( contract.getCreateBy(), 合同「 contract.getContractName() 」将在30天内到期请及时处理续保 ); } } }这个任务的坑点是重复提醒。如果没有记录上次提醒时间定时任务每天都跑客户会收到三十条一模一样的“即将到期”。所以我额外维护了一张提醒记录表同一合同在同一个提醒周期内只能生成一次提醒。如果以后系统要部署多个实例还要给定时任务加分布式锁防止每个节点都跑一遍那就会重复发消息了。单实例模式下当前这种写法是安全且高效的。4.5 文件上传PDF 附件要做的双重校验保险合同的附件经常是 PDF 保单、扫描件和签字页。后端上传接口不能只信前端传来的文件名有人可以改个后缀把恶意文件传上来。我的做法是双重校验第一层校验扩展名白名单只允许.pdf、.jpg、.jpeg、.png第二层读取文件头PDF 文件的头部必须是%PDF开头图片也有对应的魔数。文件名存储时全部用 UUID 重命名不保留用户原始文件名从根本上避免路径穿越和特殊字符问题。这些校验在前后端分离项目里尤其重要因为前端拦截很容易被绕过后端必须把守最后一道关。5. 部署教程从源码到线上环境一步步操作5.1 环境准备清单部署前后端分离项目最怕环境版本不统一。我这里列一个我在本机和 Linux 服务器上都验证过的组合。组件版本要求说明JDK1.8本项目基于 Java 8 开发Maven3.6用于后端打包Node.js16用于前端安装依赖和构建MySQL5.7 / 8.0生产建议 8.0Nginx任意稳定版部署前端 dist 和反向代理接口如果只是在本地跑通Nginx 也不是必须的。可以在开发环境用 Vite 的 proxy 把/api转发到后端地址但真正模拟生产环境我还是建议装一个 Nginx毕竟线上部署才是前后端分离项目的终局。5.2 MySQL 初始化拿到源码之后数据库脚本在database/keying_insurance.sql。第一步是建库然后导入脚本。MySQL 8.0 的建库命令CREATE DATABASE keying_insurance DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;导入脚本用命令行mysql -uroot -p keying_insurance database/keying_insurance.sql这里有个实操细节不要直接用 root 跑生产库脚本导入完成后创建一个业务账号单独授权keying_insurance库即可。比如CREATE USER keying% IDENTIFIED BY 你的强密码; GRANT ALL PRIVILEGES ON keying_insurance.* TO keying%; FLUSH PRIVILEGES;5.3 后端配置和启动后端配置文件在backend/src/main/resources/application.yml最核心的是数据源我用的是 MySQL 8.0 的驱动连接串里一定要带useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai否则中文可能乱码日期也可能差 8 小时。server: port: 8080 spring: datasource: url: jdbc:mysql://127.0.0.1:3306/keying_insurance?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/ShanghaiuseSSLfalseallowPublicKeyRetrievaltrue username: keying password: your_password driver-class-name: com.mysql.cj.jdbc.Driver mybatis: mapper-locations: classpath:mapper/*.xml type-aliases-package: com.keying.insurance.entity configuration: map-underscore-to-camel-case: trueallowPublicKeyRetrievaltrue这个参数需要注意MySQL 8 默认的caching_sha2_password认证协议在首次连接时需要获取 RSA 公钥不带这个参数很多客户端会直接报错。本地开发加上它没问题生产环境如果对安全要求高建议改用mysql_native_password或配置 SSL。另外map-underscore-to-camel-case一定要开这样数据库的contract_no才能自动映射到 Java 属性contractNo。后端打包mvn clean package -DskipTests启动java -jar target/keying-insurance.jar看到Started KeyingInsuranceApplication日志后端就算起来了。可以用curl http://localhost:8080/api/health验证服务是否正常。5.4 前端构建前端目录是frontend构建步骤很常规cd frontend npm install npm run buildnpm install如果很慢建议先把镜像切到国内源npm config set registry https://registry.npmmirror.com构建完成后会生成frontend/dist目录。这个目录就是前端的所有静态资源包括index.html、JS、CSS、图片。接下来要把它交给 Nginx 托管。5.5 Nginx 配置前后端联调生产环境中前端静态资源和后端接口最好都在同一个域名下用路径区分。这样就不需要处理跨域浏览器不会发出OPTIONS预检部署最省心。我的 Nginx 配置如下server { listen 80; server_name your-domain.com; root /opt/keying/frontend/dist; index index.html; # 后端接口反向代理 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; } # 前端页面路由 location / { try_files $uri $uri/ /index.html; } }有几个细节我必须单独拎出来说。第一location /api/里的proxy_pass末尾带了斜杠/这意味着/api/contract/page会被转发成http://127.0.0.1:8080/contract/page相当于把/api前缀去掉了。如果你的后端接口统一带/api前缀proxy_pass就不要加斜杠写成http://127.0.0.1:8080;。很多人就是栽在这个斜杠上接口 404 或者 302 循环半天。第二try_files $uri $uri/ /index.html;这一行是 Vue Router history 模式的生命线。没有它用户刷新/contract/list这个页面时Nginx 会去磁盘找contract/list目录找不到就返回 404有了它找不到文件就会回退到index.html交给前端路由渲染。配置改完后nginx -t nginx -s reload然后访问http://your-domain.com能看到登录页这套前后端分离项目就算部署成功了。5.6 如果必须用 Tomcat 部署怎么办有些院校或公司环境要求必须用传统 Tomcat webapps 部署那也可以但我不建议把前端塞进 war 包。改造思路是后端 pom 里把packagingjar/packaging改成packagingwar/packaging然后排除 Spring Boot 内嵌 Tomcat 依赖再把启动类改成继承SpringBootServletInitializer最后mvn package生成 war 放进 Tomcat 的webapps目录。前端 dist 还是放到 Nginx 或其它静态服务器。这样做的本质还是前后端分离只不过后端宿主由内置 Tomcat 换成了外部 Tomcat。如果你不是被环境硬性要求老老实实用 jar Nginx 的部署方式最简单。6. 常见问题与排查经验做这套项目时我踩过不少坑有些问题到现在回头看还觉得挺值得写出来。整理一份速查表方便你直接对照。问题现象根本原因解决办法页面刷新后 404Vue Router history 模式没有回退配置Nginx 加try_files $uri $uri/ /index.html;后端接口 404Nginxproxy_pass路径拼接不符合预期检查代理 URI 是否带斜杠和后端实际路径匹配登录后接口 401token 没被请求头携带Axios 请求拦截器里统一加Authorization前端跨域报错前端和后端不在同一个源生产用 Nginx 同源反代开发用 Vite proxy不要图省事开allow-origin *启动报 Public Key Retrieval is not allowedMySQL 8 认证协议问题连接串加allowPublicKeyRetrievaltrue中文乱码库表字符集不一致建库表统一utf8mb4连接串加characterEncodingutf8Mapper XML 没生效后端找不到映射文件确认mybatis.mapper-locations: classpath:mapper/*.xml分页 total 比实际多分页查询 join 了一对多子表先查主表分页再批量查子表明细审批重复提交并发更新覆盖了状态用UPDATE ... WHERE statusPENDING并检查影响行数还有一个经常被忽略的问题后端 jar 包明明启起来了但前端拉取不到数据。排查时要先绕开前端直接用浏览器打开http://localhost:8080/api/合同接口看返回的是 JSON 还是 404。如果是 404大概率是接口路径和前端baseURL对不上如果返回 401大概率是 token 问题。这个先后顺序能帮你省下大量“无畏”的调试时间。7. 最后再分享一点实操体会这套系统从头到尾跑通一遍之后我最大的体会是前后端分离项目的“难点”从来不在某个单独技术点上而在把 CRUD、权限、状态流转、文件上传、定时任务、部署发布这些环节合理地粘合在一起。很多人写代码时单看每个接口都很简单但真正做项目时会被“PageHelper 分页为什么不准”“Nginx 刷新为什么 404”“JWT 过期后前端为什么不跳转”这类组合问题卡住。我把这些问题连同解决方案一起写在这篇博文里就是为了让你不重走这些弯路。如果你想进一步扩展这个项目我建议优先做两件事一是把合同到期提醒升级成短信或邮件通知那个只增加一个消息发送接口业务收益立竿见影二是把统计报表模块补充起来用 Excel 导出替代后端临时拼数据日常运营会舒服很多。整个项目源码的拆分方式很清晰你拿它当脚手架往里面加新模块不会觉得别扭。