基于SpringBoot2+Vue3的船舶维保管理系统全栈实战解析

如果你打开各类源码分享平台输入船舶维保管理系统这个关键词大概率会看到这样一个技术组合SpringBoot2 Vue3 MyBatis-Plus MySQL8.0末尾还要缀上含文档。这几乎是当前Java Web中小型管理系统的标准套餐——后端用SpringBoot2搭接口MyBatis-Plus做ORM层省去大量SQL前端用Vue3全家桶撑起交互数据落在MySQL8.0上附带文档意味着不光是代码还给了数据库脚本、接口说明和操作步骤能真正跑起来。我用这个技术栈做过不止一个船务类的信息化项目对这个标题背后的业务逻辑和落地细节非常熟悉。很多刚接触这类源码的人第一反应是我能不能直接拿它当毕业设计或者能不能改改就接到真实业务里。我的答案是可以但你必须先把这套系统要管的业务理顺。船舶维保不是简单的设备维修登记它牵扯到船舶设备台账、保养计划排期、工单下发与验收、备件领用出库、船检证书到期提醒这一整条链。下面我从业务拆解、后端实现、前端实战、本地部署和踩坑记录这几个角度把这类项目完整过一遍。1. 船舶维保业务到底要管什么系统怎么拆出来1.1 船务维保的行业痛点和模块划分船舶和普通设备最大的区别在于移动的资产和强制性的检验。一艘船开到海上主机、辅机、舵机、锅炉、救生设备、通导设备任何一样出问题不光影响运营还会牵涉船舶检验和保险条款。所以船东公司对维保的核心诉求不是坏了再修而是按计划保养、提前发现隐患。系统里最核心的模块自然就是设备台账、维保计划、工单执行和检验提醒这四个。我拆过好几个船务项目发现真正上线后使用频率最高的页面反而是设备台账和计划列表。设备台账是根所有维保计划、工单、备件消耗都挂靠在设备上。拿主机举例台账里要记录船舶名称、设备编码、设备名称、型号、安装位置、生产厂商、出厂编号、投产日期这些字段。没有台账后续一切计划都无从谈起。1.2 从标题看技术选型背后的逻辑SpringBoot2 Vue3 MyBatis-Plus MySQL8.0这套组合在中小企业项目里出现频率极高不是没有道理。SpringBoot2的好处是生态成熟网上资料多遇到问题一搜就有解决方案。相比SpringBoot3虽然3已经出了很久但在国内存量项目里SpringBoot2依然占据大量份额JDK8跑得稳主流中间件兼容性也更好。MyBatis-Plus解决的是单表CRUD的效率问题BaseMapper直接提供增删改查方法配合条件构造器QueryWrapper简单查询连SQL都不用手写。MySQL8.0相对5.x增加了窗口函数、CTE等能力对报表统计类需求更友好而且8.0对JSON数据类型的支持也明显更强。这套组合的本质是用最小的开发量把传统管理系统的骨架搭起来把节省出来的时间留给业务逻辑。对于船舶维保这个场景来说业务逻辑的复杂度集中在计划周期计算和工单状态流转而不是框架本身所以选这套组合非常合适。1.3 数据模型设计思路看这类源码我建议先理清实体关系而不是急着跑代码。典型的船舶维保系统会有这样几张核心表船档表船名、船舶类型、总吨、净吨、主机功率、船籍港、建造日期设备分类表和设备台账表设备属于哪艘船、属于哪个系统、编码规则、位置、状态维保计划表计划名称、设备关联、计划周期类型日保、周保、月度、季度、年度、间隔参数、上次执行日期、下次执行日期维保工单表单号、计划关联、工单状态、执行人、验收人、计划开始时间、实际完成时间备件材料表备件编码、名称、规格、单位、库存数量、预警阈值维保记录表工单执行后写入的文本记录、附件地址、结果标记检验证书表证书名称、证书编号、发证日期、有效期截止日、下次检验日期其中最容易忽略的是维保计划表和工单表之间的关系。正确设计是计划表负责该不该做工单表负责做了没有、结果如何。每次到了计划周期触发时间系统生成一张待执行的工单执行完回写记录。如果直接把执行记录写在计划表里后续想做历史查询和统计就会很痛苦。我在某次改造项目里就见过把执行明细塞在计划表的文本字段里的做法结果统计报表只能靠字符串截取非常坑。2. 后端SpringBoot2核心实现从建表到接口的完整链路2.1 基础工程配置与公共类的搭建拿到这类源码先从pom.xml看依赖。SpringBoot2.7 mybatis-plus-boot-starter mysql-connector-j lombok jwt是常见组合。如果项目里还要做文件上传、Excel导出会额外引入hutool或EasyExcel。第一件事是配置统一返回结构。我习惯定义一个Result类包含code、message、data三个字段Controller层所有接口统一返回。前端axios拦截器只需要判断code是否为200是则取data否则弹出message。这个小习惯能避免前后端联调时各写各的返回格式到了对接阶段互相扯皮。然后是全局异常处理。用RestControllerAdvice包一层业务异常、参数校验异常、系统异常分开处理。很多新手项目不写全局异常处理Controller里每个方法都写try-catch代码又长又乱。用全局异常处理器之后Service层只需要在业务不满足条件时抛出业务异常前端拿到的永远是统一的错误结构。这个习惯在维保项目中尤其重要因为工单流转涉及审批、验收、库存扣减这类多步骤操作任一步出错都需要清晰反馈。2.2 MyBatis-Plus的常用配置与自动填充MyBatis-Plus在这一类项目里几乎是标配。集成时要注意三件事。配置MapperScan。主启动类上记得加MapperScan(xx.mapper)或者每个Mapper接口标注Mapper注解二选一即可别重复配。分页插件必须显式声明。MyBatis-Plus的分页不是默认开启的需要在配置类里注入MybatisPlusInterceptor并添加PaginationInnerInterceptor。很多初学者写完分页查询发现返回全部数据就是少了这一步。Configuration public class MybatisPlusConfig { Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor new MybatisPlusInterceptor(); PaginationInnerInterceptor pagination new PaginationInnerInterceptor(DbType.MYSQL); pagination.setMaxLimit(500L); interceptor.addInnerInterceptor(pagination); return interceptor; } }自动填充是这一类系统里提升效率的关键。create_time、update_time这两个字段如果每个新增和更新操作都手动set不仅重复劳动还容易漏。MyBatis-Plus提供了MetaObjectHandler接口在插入时自动填充创建时间和更新时间在更新时自动填充更新时间代码层面完全无感知。字段上记得加TableField(fill FieldFill.INSERT)和TableField(fill FieldFill.INSERT_UPDATE)。逻辑删除也一样实体字段加TableLogic注解配置全局逻辑删除值和未删除值。这样所有查询会自动带上deleted0条件删除操作变成update数据保留在库里方便追溯。船舶维保数据是有追溯要求的设备维修历史不能真删逻辑删除在这种场景下几乎是必须的。2.3 维保计划周期计算的业务逻辑这是整个系统最需要动脑子的地方。维保计划通常不是一次性的而是周期性循环的计划执行完要自动推算下一次日期。最简单的实现方式是在计划表里存上次执行日期和周期天数下次执行日期 上次执行日期 周期天数。但这只适用于按天计算的情况。船舶维保里常见的每季度每半年每年度如果都折算成天数遇到闰年会漂移而且不直观。更好的做法是枚举计划周期类型根据类型调用不同的日期计算逻辑。例如日保nextDate currentDate.plusDays(1)周保nextDate currentDate.plusWeeks(1)月保nextDate currentDate.plusMonths(1)季保nextDate currentDate.plusMonths(3)年保nextDate currentDate.plusYears(1)还要考虑一种情况某个计划已经逾期但一直没生成工单这时候系统应该自动补单还是提示人工处理我见过两种方案一种是把逾期计划高亮列在待办页让机务人员手动触发另一种是定时任务自动补单。实际业务中我更倾向第一种因为维保资源是有限的强行自动补单会让机务人员疲于应对反而不利于真实执行。2.4 工单状态流转与权限控制工单是维保流程的执行载体状态流转一般是待下发 - 执行中 - 待验收 - 已完成特殊情况可以取消。每一步对应不同角色调度或者机务经理下发工单轮机员/船员执行机务经理验收。状态流转不要用简单的int字段在前端随便改应该在后端用枚举或者状态机校验。最简单的做法是接口里做状态判断只有合法流转才允许更新。比如待下发状态只能流转到执行中不能直接跳到已完成。这个约束放在后端能避免前端误操作带来的脏数据。权限控制方面这类管理系统的常规做法是Spring Security JWT配合RBAC模型。用户表、角色表、菜单表、用户角色关联表、角色菜单关联表五张表是标配。前端根据用户角色渲染菜单后端在接口上做角色校验。维保系统里典型的角色有管理员、机务经理、船长、轮机员、普通船员角色不同能看到的菜单和可执行的操作差异很大。3. 前端Vue3项目结构从初始化到维保页面实战3.1 工程初始化与常用依赖选择前端工程用Vite构建是比较主流的选择比Webpack快很多。创建Vue3 Vite工程后常用的依赖是vue-router、pinia、axios、Element Plus。Element Plus是这套组合里最省事的UI组件库表格、表单、弹窗、分页都齐了。工程目录我习惯这样组织src/ api/ # 按模块拆分的接口请求文件 assets/ # 静态资源 components/ # 公共组件 router/ # 路由配置 stores/ # Pinia状态管理 utils/ # axios封装、auth工具等 views/ # 页面组件如果拿到手的源码没有按模块拆分api建议自己重构一遍。把请求地址散落在页面组件里是最难维护的写法改一个接口名得全局搜索。3.2 axios封装与token处理的细节axios封装的核心是拦截器。请求拦截器统一把token放到Authorization头里响应拦截器统一处理业务错误码和HTTP错误码。这套逻辑几乎每个管理系统都有但细节上有差别。import axios from axios const service axios.create({ baseURL: import.meta.env.VITE_API_BASE_URL || /api, timeout: 10000 }) service.interceptors.request.use(config { const token localStorage.getItem(token) if (token) { config.headers.Authorization Bearer ${token} } return config }) service.interceptors.response.use( response { const res response.data if (res.code ! 200) { // 业务错误统一提示 return Promise.reject(new Error(res.message)) } return res.data }, error { if (error.response error.response.status 401) { localStorage.removeItem(token) window.location.href /login } return Promise.reject(error) } ) export default service有一个细节容易被忽略响应拦截器返回的是res.data而不是response这样页面里调用接口的时候直接拿业务数据少一层结构访问。但如果后端返回的data里还有分页对象代码里就要注意是page.records还是page.list。3.3 维保工单页面状态驱动的交互设计维保工单列表页是这类系统里最典型的页面包含搜索条件、表格、分页、新增和编辑按钮。搜索条件常见的有工单号、船舶名称、计划类型、状态、时间范围。表格列建议展示工单号、关联设备、计划类型、执行人、状态、计划开始时间、实际完成时间、操作按钮。操作按钮要根据状态动态显示待下发状态显示下发和取消执行中状态显示提交验收待验收状态显示验收通过和驳回。这个动态按钮的逻辑用Vue3的computed或者直接在模板里用v-if都行。我更倾向把按钮权限和状态权限分开判断状态权限在前端做按钮权限结合用户角色做两套一起判断。工单新增和编辑建议用弹窗表单而不是单独的页面因为字段控制在十个以内弹窗操作路径短用户体验更好。表单里日期选择器用Element Plus的el-date-picker提交时把value-format设置为YYYY-MM-DD HH:mm:ss后端直接用String接收也不会出错。3.4 Pinia状态管理和路由守卫登录状态存Pinia还是localStorage我的习惯是Pinia存内存中的用户信息token持久化到localStorage。刷新页面后通过路由守卫里调用获取用户信息接口重新拉取。用户体验和安全性都能兼顾。路由守卫的逻辑不复杂判断是否存在token没有则跳转登录页登录后根据用户角色动态生成可访问的菜单路由。这里有一个常见坑动态路由如果是在登录后才addRoute的刷新页面会因为路由还没注册而过早跳转404。解决方案是在全局前置守卫里判断store是否已加载路由未加载则先await动态挂载路由再接续放行。4. 从拿到源码到跑起来本地环境搭建与部署实录4.1 版本匹配清单拿到这类源码先别急着点运行。先按照版本矩阵检查本地环境版本不匹配是跑不起来的第一大原因。组件推荐版本说明JDK1.8 或 11SpringBoot2.7官方支持JDK8/11/17但源码多半按JDK8语法编写Maven3.6.3 以上太低可能无法解析部分依赖Node.js16.18.x 或 18.xVite4要求Node14.18Vite5要求Node18先看package.jsonnpm/yarnnpm 8 或 yarn 1.22常规选择MySQL8.0.x注意字符集utf8mb4连接驱动用8.0.33Redis不必须若源码里引入了Redis做缓存需要本地启动一个实例如果源码里用的是Vite5而本地Node是16启动报错几乎是必然的。遇到这种问题优先匹配Node版本而不是去改Vite版本因为项目依赖的插件可能也不兼容。4.2 数据库脚本导入的三个关键步骤MySQL8.0导入脚本的坑集中在编码和时区。脚本文件先确认是utf8还是utf8mb4编码导入时如果用了错误字符集中文乱码很难排查。导入步骤建议用数据库管理工具新建数据库字符集选择utf8mb4排序规则选择utf8mb4_general_ci或utf8mb4_unicode_ci打开sql脚本检查建库语句里是否指定了数据库名。如果脚本里包含CREATE DATABASE建议注释掉只保留表结构和数据部分避免库名冲突执行脚本后重点检查几张核心表的数据量特别是用户表和菜单表。如果登录后发现页面空白多半是菜单表和角色表关联数据没导全4.3 后端数据源配置和常见报错后端application.yml里的数据源配置是第一个要改的地方。MySQL8.0的驱动类名是com.mysql.cj.jdbc.DriverURL要带serverTimezone参数和服务端的public key检索参数。spring: datasource: url: jdbc:mysql://localhost:3306/ship_maintenance?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/ShanghaiuseSSLfalseallowPublicKeyRetrievaltrue username: root password: 你的密码 driver-class-name: com.mysql.cj.jdbc.DriverallowPublicKeyRetrievaltrue这个参数很多人会忽略。MySQL8.0默认使用caching_sha2_password认证客户端首次连接时如果没有这个参数会报Public Key Retrieval is not allowed的错误。加上之后开发环境用没问题生产环境如果安全要求高建议改用mysql_native_password或者配置SSL。4.4 前端联调与跨域代理前后端分离项目联调最怕跨域。开发阶段不要靠后端加CrossOrigin解决应该用Vite的proxy代理转发。在vite.config.js里配置proxy前端请求/api/xxx开发服务器把请求转发到后端8080端口浏览器感知不到跨域。import { defineConfig } from vite import vue from vitejs/plugin-vue export default defineConfig({ plugins: [vue()], server: { port: 3000, proxy: { /api: { target: http://localhost:8080, changeOrigin: true } } } })注意前端axios的baseURL配置成/api和后端接口路径拼接。如果前端请求路径本来就带了/api前缀而后端Controller的RequestMapping是/api/xxxproxy的路径重写rewrite功能可能需要关闭否则会出现双/api的问题。这块是前后端联调最典型的报错。启动顺序上先启动MySQL和Redis如果用到再启动后端SpringBoot最后启动前端。后端启动后先访问后端端口下任意一个接口确认数据源配置没问题再启动前端。如果一上来就前后端同时启动出问题还要两头排查浪费时间。5. 我把这个项目跑通过程中踩过的坑5.1 时间字段差8小时的陷阱维保工单的计划时间在数据库里是对的前端页面展示却少了8小时而且数据库导入后date字段没问题datetime字段却漂移。这个问题的根因是MySQL连接URL里的serverTimezone和系统时区不一致。解决办法是把url里的serverTimezone显式设置为Asia/Shanghai同时MySQL服务端时区也检查一下。8.0版本可以执行SET GLOBAL time_zone 08:00或者修改my.cnf的default-time-zone。这类问题在初学时很容易漏掉因为它不报错只是数据看起来不对。5.2 MyBatis-Plus逻辑删除与唯一索引冲突我在一个备件表上设计了备件编码唯一索引又加了逻辑删除字段。结果删除一条备件记录后再插入同编码的新备件唯一索引冲突导致插入失败。原因是逻辑删除没有真正删记录旧数据还在表里占着唯一索引。解决办法主要有两种一是唯一索引改成联合索引把deleted字段加进去二是插入前先物理清除同编码且已删除的旧记录。考虑到维保系统的备件历史需要保留我推荐前者。不过要注意联合索引也会让同编码的已删除记录最多保留一条因为deleted字段在一般实现里并不是每条记录不同的值如果不做特殊处理还是会冲突。5.3 Excel导出字段顺序混乱与日期格式维保计划导出是一个高频功能。用EasyExcel导出时字段顺序由实体类属性顺序决定而数据库查询返回的Map集合顺序不可控。如果你用的是ExcelProperty注解可以指定index否则默认顺序容易和表头错位。日期格式也是高频问题。数据库的datetime字段导出到Excel里经常变成一串数字或者UTC格式需要在导出字段上加ExcelProperty(value 计划时间, format yyyy-MM-dd HH:mm:ss)明确格式化。我踩过一次导出后日期显示成2024-03-01T08:00:00就是忽略了格式声明。5.4 前端路由在history模式下的404本地开发用BrowserRouter路由模式没问题一旦部署到Nginx刷新子页面就会出现404。这是因为前端是单页应用路由跳转由前端处理刷新时浏览器直接向服务器请求当前路径服务器没有对应文件就返回404。解决办法是Nginx配置try_files来兜底让所有前端路由都回到index.htmllocation / { try_files $uri $uri/ /index.html; }或者更省事的做法是把vue-router切换到hash模式URL上多一个#号但部署时不需要额外配Nginx。实际项目中我一般看部署环境决定内网管理类系统用hash模式更省心。5.5 问题速查表现象可能原因解决办法项目启动报数据库连接失败数据源配置错误、MySQL未启动检查username/password/url确认MySQL服务已启动报Public Key Retrieval is not allowedMySQL8.0认证方式url加allowPublicKeyRetrievaltrue插入记录时create_time为空未配置自动填充处理器实现MetaObjectHandler并启动类扫描分页查询返回全表数据未配置分页插件注入MybatisPlusInterceptor PaginationInnerInterceptor前端启动报Node版本不兼容Node与Vite版本不匹配按package.json要求切换Node版本页面401循环跳登录token过期未处理响应拦截器对401做跳转登录页排除在拦截外导出Excel中文乱码响应头未设置编码设置Content-Type为application/vnd.ms-excel;charsetutf-8请求后端接口跨域前后端端口不同Vite proxy代理或者后端加CORS配置6. 这类系统还可以往哪些方向扩展6.1 移动端扫码巡检维保系统只坐在电脑前操作是不够的机舱里的实际巡检场景更适合手机端操作。可以扩展扫码巡检功能每台设备生成二维码手机扫一扫进入设备详情填写巡检结果拍照上传。这个需求在船务场景里非常真实船员不可能带着电脑去机舱。实现方案可以是独立的移动端H5后端复用现有接口新增扫码登录和图片上传接口。二维码可以用设备的唯一编码生成不需要额外开发复杂的二维码引擎。6.2 备件库存与维保工单的联动现有系统里备件领用往往和工单是两张皮工单执行归工单备件出库归出库月底对账靠Excel。扩展方向是以工单号为关联字段执行人领用备件时选择关联工单备件出库自动记录在工单成本里。这样每个月可以统计出每条船的维保成本这一块是船东公司非常关注的数据。6.3 维保大屏与统计报表管理部门关心的数据不是某一条工单是否按时完成而是整体维保完成率、逾期率、故障类型分布、备件消耗趋势。可以扩展一个数据大屏页面或者把统计接口提供给BI系统。用MySQL8.0的窗口函数算月度环比增长率比传统的临时表写法效率高很多。前端大屏用ECharts配合Vue3的组件化开发一两天就能搭出可用的原型。这类系统里我认为最有价值的扩展还是移动扫码和成本联动它们直接把业务数据从记录变成了分析价值完全不同。最后说一点个人体会。我每次拿到这类带文档的源码项目从来不会直接扔进IDE运行而是先花半小时把数据库脚本执行一遍把表结构关系画出来再根据ER图反推业务流转。这个习惯能让我在动手改代码之前就对系统的边界有清晰判断。还有一个非常实用的小技巧跑通之后先点一遍菜单把每一个页面涉及的接口在浏览器控制台里记录下来标注好用途后面无论是排查问题还是加功能这份接口清单都能省很多时间。按这套思路把这个维保系统源码吃透你收获的不仅是一个能跑的Demo更是一套可以直接面对真实船务业务的技术框架。