做船运物流管理系统SpringBootVueMyBatisMySQL这套组合说白了就是给船公司、货代企业做一个内部管理平台把船舶调度、海运订单、货物跟踪、账单结算这些事从Excel表格里捞出来变成一套前后端分离的Web系统。这个项目我在实际开发中完整落地过从数据库建模到前端看板再到最后上线部署整个过程踩了不少坑也总结出一些可以直接用的经验。如果你是Java后端想转全栈的开发者或者是正在准备毕业设计、求职项目的人这篇文章应该能帮上忙。我会从业务需求拆解、技术选型逻辑、数据库设计、后端接口实现、前端交互、环境部署到问题排查把整个系统的骨架和关键细节完整捋一遍。不是说代码给你贴满就完事而是让你知道每一步为什么这么做遇到问题怎么排查。1. 项目拆解船运物流管理系统到底在解决什么问题1.1 船运行业的业务痛点先说一个很现实的现象直到现在很多中小型船运公司和货代企业内部管理还是靠微信群加Excel。船舶到港时间靠电话问订单状态靠表格攒费用结算靠月底对账货主想查一下自己的货到哪了客服得翻聊天记录。整个链条上信息滞后非常严重尤其在船期变动、港口拥堵、天气影响这些突发情况下上下游信息不同步轻则产生滞港费纠纷重则丢客户。船运物流管理系统要解决的就是这几件事第一把船舶、航次、订单、货物、费用这些核心数据统一存到数据库里做成可查询、可统计的台账第二把业务流转线上化从订舱、派船、装货、离港、到港、签收每一步都有状态记录和时间戳第三让不同角色看到不同维度的数据高层看运营报表调度看船期和舱位财务看应收应付客服看货物动态。这个行业还有个特点业务单据类型多而且经常变化。一个订单从订舱开始可能涉及托书、提单、装货单、到货通知、结算单等五六种单据每种单据之间还有复杂的关联关系。如果不用关系型数据库把主表和明细表理清楚后面做查询、统计、导出会非常痛苦。这也是选择MySQL而不是NoSQL数据库的底层原因。1.2 为什么选SpringBootVueMyBatisMySQL这套组合在2025年依然不算过时反而因为生态成熟、学习资料多、招聘需求大成了做管理类系统最稳妥的选择。我给朋友公司做这个船运系统时没有选微服务也没有引入各种中间件原因很简单团队维护能力有限业务规模也撑不起复杂架构。SpringBoot负责后端接口它的价值在于“约定优于配置”。不用手动搭Tomcat不用写一堆XML配置文件一个Application启动类跑起来接口就能对外提供服务。配合Maven做依赖管理引入Web、MyBatis、MySQL驱动、安全框架这些依赖几行配置就能跑起来。SpringBoot内置的自动配置大大降低了搭建成本让开发者把精力放在业务逻辑上。MyBatis负责数据库操作层。为什么不用JPA因为船运系统的查询条件特别多订单可能按船名查、按货主查、按时间范围查、按状态组合查而且表格字段多、关联表多。MyBatis的动态SQL在这种场景下简直是神器一个XML里写几个if标签就能灵活拼接查询条件可控性强SQL写出来什么样执行就是什么样。对于需要DBA审核SQL的传统企业系统这一点非常重要。Vue负责前端页面。船运管理系统的界面本质上就是大量表格加表单再加几个数据看板。Vue的组件化开发模式能把船舶卡片、订单表格、费用明细这些UI拆成独立组件复用性很好。配合Element UI之类的组件库几个页面可以迅速搭建出来。Vue Router做权限路由Vuex做全局状态管理axios做接口请求这套模式已经非常成熟。MySQL负责数据存储。选择它不仅是出于成本考虑更关键的是船运系统天然适合关系型模型船舶、航次、订单、货物、结算单这些实体之间有明确的主外键关系需要事务保证数据一致性。比如一笔运输合同生成后同时要创建订单主表记录和货物明细记录还必须扣减对应航次的剩余舱位这三个操作必须在一个事务里完成MySQL的InnoDB引擎配合Spring事务管理可以很好地满足这个需求。1.3 系统角色与核心业务流程船运物流管理系统的角色一般分四类管理员、调度员、财务人员、客服或货主端。不同角色登录后看到的功能菜单差别很大这就需要做基于角色的权限控制。我从业务角度梳理一下核心流程。客户下单订舱客服在系统里创建运输订单选择起始港、目的港、货物品类、重量、体积系统自动根据航线费率计算预估运费。调度员看到新订单后安排合适船舶和航次生成配载计划。船舶离港后订单状态变为“运输中”货物每经过一个节点离港、中转、到港、清关、签收客服或现场操作员更新节点记录系统自动给货主推送状态变化。船舶到港后收货人提货确认无误后财务人员根据最终的计费重量和附加费用生成结算单推送发票信息客户付款后核销。这个流程看起来不复杂但每一个环节都涉及异常情况订单取消、船期延误、货物破损、费用争议。所以系统的状态机设计必须考虑全不能只设计正常流转路径。我建议在订单表里加一个状态字段并设计状态变更历史表每次变更都记录下来这样出了问题能追溯到是谁在什么时间改了状态。2. 数据库设计与后端核心实现2.1 核心数据表设计与关联关系数据库设计是整个系统的地基。表哥设计不好后面写SQL和前端页面都会难受。我根据实际开发经验把核心表分成几个模块来讲。船舶信息表字段包括船名、船型、载重吨、总吨、净吨、舱位数量、当前状态在港/航行中/维修、所属公司、证书有效期等。航线表记录港口代码、港口名称、航线名称、预计航行天数、基准运价。航次表则把船舶和航线关联起来包含航次编号、船名、航线、预计离港时间、实际离港时间、预计到港时间、实际到港时间、剩余舱位。订单主表是整个业务的核心我给它命名ship_order字段包括订单编号、客户ID、航次ID、起运港、目的港、运输方式整箱/拼箱、货物总重量、总体积、状态、下单时间、预计交货时间。货物明细表存放每个提单号下的货物信息包括品名、件数、包装类型、单件重量、单件体积、唛头信息。这里一定要记住订单和货物的关系是一对多一个订单可以有多个提单号对应多批货物。费用表设计比较讲究。我建议拆成费用项目和结算单两张表费用项目记录每一笔费用的类型海运费、港口费、报关费、仓储费、滞箱费等、金额、币种、汇率、应收应付方向结算单则是把多个费用项目汇总到一张账单里状态有未确认、已确认、已开票、已收款。这样设计的好处是财务可以单独调整某笔费用而不影响整个账单结构。再就是用户表、角色表、用户角色关联表、操作日志表、系统配置表这些基础框架表。用户表字段要包含登录名、密码BCrypt加密存储、姓名、手机号、状态操作日志表非常重要船运系统涉及钱和货出了问题必须能审计。2.2 SpringBoot工程结构与MyBatis集成要点工程的包结构我习惯这样分com.xxx.shipping ├── controller ├── service ├── mapper ├── entity ├── dto ├── vo ├── config ├── common └── utilscontroller层只做参数接收和结果返回service层写业务逻辑mapper层是MyBatis接口entity对应数据库表dto用于接口参数传输vo用于前端展示。这样的分层虽然多但好处是每个类的职责清晰协作开发时不容易冲突。MyBatis集成有两个关键点。第一是pom.xml里的依赖坐标dependency groupIdorg.mybatis.spring.boot/groupId artifactIdmybatis-spring-boot-starter/artifactId version2.3.2/version /dependency dependency groupIdcom.mysql/groupId artifactIdmysql-connector-j/artifactId scoperuntime/scope /dependency第二是application.yml里的配置。这里有个细节很多新手在这里卡半天新版MySQL连接器驱动类变了8.x版本要用com.mysql.cj.jdbc.Driver而且必须加上时区参数否则数据库连接会报错。spring: datasource: url: jdbc:mysql://localhost:3306/shipping_db?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai username: root password: 123456 driver-class-name: com.mysql.cj.jdbc.Driver mybatis: mapper-locations: classpath:mapper/*.xml type-aliases-package: com.xxx.shipping.entity configuration: map-underscore-to-camel-case: truemap-underscore-to-camel-case: true这个配置强烈建议打开数据库字段ships_status就能自动映射到Java属性shipsStatus省去大量ResultMap手写工作。2.3 关键接口设计运单生成与货物跟踪运单生成是船运系统最核心的接口。它的逻辑是前端提交一个订单主表数据和一组货物明细后端在同一个事务里完成三件事——插入订单主表、批量插入货物明细、扣减航次剩余舱位。我贴一段事务控制的伪代码思路比代码本身更重要Override Transactional(rollbackFor Exception.class) public Long createOrder(OrderCreateRequest request) { // 1. 校验航次是否存在且可订舱 Voyage voyage voyageMapper.selectById(request.getVoyageId()); if (voyage null || voyage.getRemainingSpace() 0) { throw new BusinessException(航次不存在或已无剩余舱位); } // 2. 生成订单主表 ShipOrder order new ShipOrder(); order.setOrderNo(generateOrderNo()); order.setCustomerId(request.getCustomerId()); order.setVoyageId(request.getVoyageId()); order.setStatus(OrderStatus.BOOKED.getCode()); orderMapper.insert(order); // 3. 插入货物明细 for (CargoItem item : request.getCargoItems()) { item.setOrderId(order.getId()); cargoMapper.insert(item); } // 4. 扣减剩余舱位 voyageMapper.decreaseRemainingSpace(request.getVoyageId(), request.getTotalWeight()); return order.getId(); }这里要注意几个细节。生成订单编号不能用简单的自增ID建议用日期加序列的格式比如SO20250612001既方便查询又不容易暴露业务量。扣减舱位时必须用乐观锁或UPDATE语句里的条件判断防止两个人同时下单超卖UPDATE voyage SET remaining_space remaining_space - #{weight} WHERE id #{voyageId} AND remaining_space #{weight}货物跟踪接口的核心是一张航迹节点表。每当船舶离港、到港、报关完成就在表里插入一条节点记录前端将查询结果按时间逆序渲染出来。接口返回的数据结构最好是嵌套的订单信息、当前状态、历史节点列表一次性返回减少前端请求次数。3. 前端Vue设计与核心交互逻辑3.1 前端工程结构与权限设计前端我建议直接使用Vite构建工具加Vue 3比Webpack热更新更快配置也更简单。项目的页面组织方式可以分为登录页、主布局、业务模块页面。主布局包含侧边菜单栏、顶部导航栏、面包屑和内容区登录后根据用户的角色动态渲染菜单。权限设计这里我多说几句。船运系统不像普通后台管理系统那样简单判断一个角色就完事经常会出现一个人身兼多职的情况客服主管同时可能要看财务报表调度员也可能需要查看客户信息。所以我在实际项目里用RBAC模型但增加了数据权限维度同一个功能菜单用户都能看到但查询数据时只能查到自己权限范围内的订单。Vue Router实现权限路由的常见思路是登录成功后后端返回该用户的角色编码和权限标识列表前端将这些权限标识和动态路由表做匹配过滤出可访问的页面再用router.addRoute()动态添加。这样用户在地址栏强行输入没有权限的URL时会被路由守卫拦截并跳转到403页面。3.2 核心页面拆解船期看板、运单列表与货物跟踪船期看板是调度员打开系统后最常看的页面。表格按时间轴排列横轴是日期纵轴是船舶每个格子代表一个航次。格子里显示航次编号、起止港、预计开航时间、剩余舱位。如果船期延误格子颜色变为红色并显示延误原因。实现船期看板的关键是数据结构。后端接口返回的每条记录包含startDate、endDate、shipName、voyageNo等字段前端根据日期范围生成表格坐标再用CSS Grid布局渲染。这个页面也可以用甘特图组件实现但中小型项目不值得引入重型图表库我建议用自绘的方式控制样式和交互。运单列表页是比较典型的表格加条件查询页面。顶部是筛选区域订单编号、客户名称、状态、起运日期范围。表格展示订单概要每个订单号是一个可点击链接点开后进入订单详情页。这里建议做成分页加懒加载因为订单表数据量增长很快一次查出几千条会让页面非常卡。我踩过的坑是表格列太多了。船运订单涉及的字段可能有二十多个全部放在一列不现实。后来按重要程度拆成两部分列表页只展示必要字段详情页用分步表单展示完整信息并用标签页把货物明细、费用明细、操作日志分开。这样页面简洁加载速度也快。3.3 axios封装与跨域处理前端请求后端接口统一走axios实例超时时间、基础URL、请求拦截器、响应拦截器都要在封装层配好。请求拦截器里从localStorage取出Token放到请求头service.interceptors.request.use(config { const token localStorage.getItem(token) if (token) { config.headers[Authorization] Bearer token } return config })响应拦截器里统一处理业务错误码和HTTP状态码比如401跳转登录页500弹出错误提示。这样业务页面里只需要关注接口返回值不需要每个请求都写一遍错误处理逻辑。跨域问题在开发环境用Vite的proxy配置解决在生产环境用Nginx反向代理解决。开发环境的配置如下server: { port: 3000, proxy: { /api: { target: http://localhost:8080, changeOrigin: true } } }这就意味着前端请求/api/login时Vite开发服务器会把请求转发到后端的http://localhost:8080/api/login。后端Controller的RequestMapping里统一加/api前缀前后端接口路径就对齐了。后端同时开启CORS配置允许前端开发服务器的请求跨域通过。4. 实操从零跑通环境准备与部署步骤4.1 开发环境版本选择这个项目我用的是JDK 8不要觉得老很多船运企业的生产服务器还在用8。JDK 8配SpringBoot 2.7兼容性最好。如果你用JDK 17SpringBoot 3.x也能跑但MyBatis Starter的版本要对应升级网上很多教程没写清楚版本关系照旧代码抄容易出事。Maven用3.6.3以上MySQL用5.7或8.0Node.js建议选18或20的LTS版本。这里特别提醒一个问题Node版本太新可能导致Vite脚手架下依赖时报错如果用的是老项目还会出现Node-sass编译失败。现在新项目基本都用Sass替代的Dart-Sass或者干脆不用SassCSS写起来也没问题。4.2 数据库初始化与后端启动拿到源码后不要直接启动后端先去看resources/sql目录下的初始化脚本。执行顺序很重要先建数据库再建用户表最后执行业务数据脚本。有些源码把表结构和数据写在一个文件里执行时容易因为排序问题报错。mysql -u root -p create database shipping_db default character set utf8mb4; use shipping_db; source /path/to/init.sql;执行完脚本后检查几张关键表的数据sys_user表有没有默认管理员账号dict_data字典表是否完整。没有字典数据的话前端下拉框会全部为空。启动后端之前把application.yml里的数据库账号密码改成你自己的。如果你用的是MySQL 8连接驱动和时区问题前面已经说过了。后端启动成功的标志是控制台输出Tomcat started on port 8080此时访问http://localhost:8080/api/health能返回JSON。4.3 前端启动与联调验证前端安装依赖时建议使用npm install不要图快使用cnpmcnpm经常导致node_modules目录结构异常运行起来各种莫名其妙的报错。安装完成后先启动开发服务器再检查控制台有没有代理请求报错。联调时要准备一份完整的业务数据走通流程。我最常用的验证路径是用管理员账号登录创建一个客户创建一个航次创建一笔包含两个货物明细的订单查看订单详情并推进状态然后生成结算单。这一条路径走通基本说明系统主要功能正常。5. 开发过船运系统之后才明白的几个深坑5.1 跨域问题和Cookie携带开发时用Vite代理跨域基本不会出问题。但如果前后端不在同一台服务器上部署生产环境跨域就要靠Nginx。我给某船运公司做生产部署时前端、后端分别部署在两台内网服务器上Nginx配置做了前后端分离转发静态前端页面放在一个server块请求/api前缀的路径统一转发到后端地址。这里有个容易漏的地方如果后端依赖Session而不是Token必须在Nginx转发时配置X-Forwarded-For头并后端开启对应支持否则登录状态一直失效。5.2 MySQL时区与SSL连接报错刚接触MySQL 8的人经常遇到两个报错。第一个是Server returns invalid timezone原因就是连接URL里没加serverTimezoneAsia/Shanghai。第二个是SSL connection error8.0版本默认开启SSL本地开发没必要用连接URL里加useSSLfalse关掉即可。5.3 MyBatis映射文件里的空格和逗号问题MyBatis动态SQL写多了就会遇到一个经典问题if标签拼接时多出逗号或多了AND。特别是明明是更新语句因为拼接顺序问题最后生成SQL多了空格导致语法错误。我的经验是动态SQL里面的逗号不要写在字段后面而是写在字段前面并配合WHERE之后的第一项永远不加连接符的习惯这样可以大大降低语法错误率。写完后养成一个习惯把mybatis.configuration.log-impl配置成StdOutImpl控制台打印完整SQL调试时无比省心。5.4 金额计算用BigDecimal而不是Double船运费用里的海运费、燃油附加费、港口费算下来动辄上万用Double会出精度丢失的问题。我的建议是数据库金额字段用decimal(18,2)Java对象用BigDecimal前端传输时保留两位字符串。计算不同币种的总额时汇率转换也必须在后端完成不要在多个接口里分散计算否则财务对账时发现几分钱对不上很难排查。5.5 运费的按航段拆分与附加费计算船运的运费计算比公路运输复杂得多很多时候同一个订单的货物要从起运港经过中转港再到目的港不同的航段费率不一样。设计费率表时要考虑「航线段」的概念一个完整的运输路径由若干个航线段拼接而成每个段有不同的基准费率和时效。订单创建时根据路径拆分航段分别计算费用再汇总。这块逻辑在需求阶段很容易被忽略但实际业务中一定是高频功能因为船运公司经常拿这个跟客户谈价格。我处理附加费时用了一个策略在订单创建完成后不直接锁定总费用而是保存费用计算快照后续如果有滞港费、改单费、超期堆存费再以追加费用的形式写入费用项目表最终汇总到结算单。这样既保留灵活的计费空间又保证账面清晰可追溯。5.6 权限和数据隔离的一个小坑船运公司集团化运作的话多个子公司在同一个系统里跑容易出现数据串门的问题。某用户登录后能查到另一家子公司的订单这非常严重。我的做法是在所有查询Mapper里都强制拼接company_id条件而不是在代码里用if判断是否拼接。这样即使开发者忘记传入公司IDSQL会因为缺少参数直接报错而不会默默查出全量数据。最后分享一个我自己的体会整个船运物流管理系统开发下来我最大的感受是技术本身不是瓶颈真正花时间的是把业务规则理解清楚。如果一开始拿到需求就急着建表写代码到了中期一定会因为费率计算、状态流转这些逻辑返工。建议第一次接触这类系统的朋友花两三天时间把业务流程图和状态图画出来确认清楚每个操作的前置条件和后续影响再动手建库表都不晚。另外有一点想单独提醒船运物流系统涉及的数据敏感性很高客户名单、价格信息、合同条款都属于商业机密。不管项目是自己练手还是给企业做交付从第一天起就要注意数据安全性。密码加密、接口鉴权、操作日志这些基础能力不能省前端页面展示也要留意脱敏手机号和地址在列表中默认打码显示。这个行业的口碑传播很快数据安全出了问题系统做得再好也没人会再用。 
长河君 · 2026/10/20 21:16:26 · 阅读 1.2k SpringBoot+Vue+MyBatis+MySQL船运物流管理系统实战
做船运物流管理系统SpringBootVueMyBatisMySQL这套组合说白了就是给船公司、货代企业做一个内部管理平台把船舶调度、海运订单、货物跟踪、账单结算这些事从Excel表格里捞出来变成一套前后端分离的Web系统。这个项目我在实际开发中完整落地过从数据库建模到前端看板再到最后上线部署整个过程踩了不少坑也总结出一些可以直接用的经验。如果你是Java后端想转全栈的开发者或者是正在准备毕业设计、求职项目的人这篇文章应该能帮上忙。我会从业务需求拆解、技术选型逻辑、数据库设计、后端接口实现、前端交互、环境部署到问题排查把整个系统的骨架和关键细节完整捋一遍。不是说代码给你贴满就完事而是让你知道每一步为什么这么做遇到问题怎么排查。1. 项目拆解船运物流管理系统到底在解决什么问题1.1 船运行业的业务痛点先说一个很现实的现象直到现在很多中小型船运公司和货代企业内部管理还是靠微信群加Excel。船舶到港时间靠电话问订单状态靠表格攒费用结算靠月底对账货主想查一下自己的货到哪了客服得翻聊天记录。整个链条上信息滞后非常严重尤其在船期变动、港口拥堵、天气影响这些突发情况下上下游信息不同步轻则产生滞港费纠纷重则丢客户。船运物流管理系统要解决的就是这几件事第一把船舶、航次、订单、货物、费用这些核心数据统一存到数据库里做成可查询、可统计的台账第二把业务流转线上化从订舱、派船、装货、离港、到港、签收每一步都有状态记录和时间戳第三让不同角色看到不同维度的数据高层看运营报表调度看船期和舱位财务看应收应付客服看货物动态。这个行业还有个特点业务单据类型多而且经常变化。一个订单从订舱开始可能涉及托书、提单、装货单、到货通知、结算单等五六种单据每种单据之间还有复杂的关联关系。如果不用关系型数据库把主表和明细表理清楚后面做查询、统计、导出会非常痛苦。这也是选择MySQL而不是NoSQL数据库的底层原因。1.2 为什么选SpringBootVueMyBatisMySQL这套组合在2025年依然不算过时反而因为生态成熟、学习资料多、招聘需求大成了做管理类系统最稳妥的选择。我给朋友公司做这个船运系统时没有选微服务也没有引入各种中间件原因很简单团队维护能力有限业务规模也撑不起复杂架构。SpringBoot负责后端接口它的价值在于“约定优于配置”。不用手动搭Tomcat不用写一堆XML配置文件一个Application启动类跑起来接口就能对外提供服务。配合Maven做依赖管理引入Web、MyBatis、MySQL驱动、安全框架这些依赖几行配置就能跑起来。SpringBoot内置的自动配置大大降低了搭建成本让开发者把精力放在业务逻辑上。MyBatis负责数据库操作层。为什么不用JPA因为船运系统的查询条件特别多订单可能按船名查、按货主查、按时间范围查、按状态组合查而且表格字段多、关联表多。MyBatis的动态SQL在这种场景下简直是神器一个XML里写几个if标签就能灵活拼接查询条件可控性强SQL写出来什么样执行就是什么样。对于需要DBA审核SQL的传统企业系统这一点非常重要。Vue负责前端页面。船运管理系统的界面本质上就是大量表格加表单再加几个数据看板。Vue的组件化开发模式能把船舶卡片、订单表格、费用明细这些UI拆成独立组件复用性很好。配合Element UI之类的组件库几个页面可以迅速搭建出来。Vue Router做权限路由Vuex做全局状态管理axios做接口请求这套模式已经非常成熟。MySQL负责数据存储。选择它不仅是出于成本考虑更关键的是船运系统天然适合关系型模型船舶、航次、订单、货物、结算单这些实体之间有明确的主外键关系需要事务保证数据一致性。比如一笔运输合同生成后同时要创建订单主表记录和货物明细记录还必须扣减对应航次的剩余舱位这三个操作必须在一个事务里完成MySQL的InnoDB引擎配合Spring事务管理可以很好地满足这个需求。1.3 系统角色与核心业务流程船运物流管理系统的角色一般分四类管理员、调度员、财务人员、客服或货主端。不同角色登录后看到的功能菜单差别很大这就需要做基于角色的权限控制。我从业务角度梳理一下核心流程。客户下单订舱客服在系统里创建运输订单选择起始港、目的港、货物品类、重量、体积系统自动根据航线费率计算预估运费。调度员看到新订单后安排合适船舶和航次生成配载计划。船舶离港后订单状态变为“运输中”货物每经过一个节点离港、中转、到港、清关、签收客服或现场操作员更新节点记录系统自动给货主推送状态变化。船舶到港后收货人提货确认无误后财务人员根据最终的计费重量和附加费用生成结算单推送发票信息客户付款后核销。这个流程看起来不复杂但每一个环节都涉及异常情况订单取消、船期延误、货物破损、费用争议。所以系统的状态机设计必须考虑全不能只设计正常流转路径。我建议在订单表里加一个状态字段并设计状态变更历史表每次变更都记录下来这样出了问题能追溯到是谁在什么时间改了状态。2. 数据库设计与后端核心实现2.1 核心数据表设计与关联关系数据库设计是整个系统的地基。表哥设计不好后面写SQL和前端页面都会难受。我根据实际开发经验把核心表分成几个模块来讲。船舶信息表字段包括船名、船型、载重吨、总吨、净吨、舱位数量、当前状态在港/航行中/维修、所属公司、证书有效期等。航线表记录港口代码、港口名称、航线名称、预计航行天数、基准运价。航次表则把船舶和航线关联起来包含航次编号、船名、航线、预计离港时间、实际离港时间、预计到港时间、实际到港时间、剩余舱位。订单主表是整个业务的核心我给它命名ship_order字段包括订单编号、客户ID、航次ID、起运港、目的港、运输方式整箱/拼箱、货物总重量、总体积、状态、下单时间、预计交货时间。货物明细表存放每个提单号下的货物信息包括品名、件数、包装类型、单件重量、单件体积、唛头信息。这里一定要记住订单和货物的关系是一对多一个订单可以有多个提单号对应多批货物。费用表设计比较讲究。我建议拆成费用项目和结算单两张表费用项目记录每一笔费用的类型海运费、港口费、报关费、仓储费、滞箱费等、金额、币种、汇率、应收应付方向结算单则是把多个费用项目汇总到一张账单里状态有未确认、已确认、已开票、已收款。这样设计的好处是财务可以单独调整某笔费用而不影响整个账单结构。再就是用户表、角色表、用户角色关联表、操作日志表、系统配置表这些基础框架表。用户表字段要包含登录名、密码BCrypt加密存储、姓名、手机号、状态操作日志表非常重要船运系统涉及钱和货出了问题必须能审计。2.2 SpringBoot工程结构与MyBatis集成要点工程的包结构我习惯这样分com.xxx.shipping ├── controller ├── service ├── mapper ├── entity ├── dto ├── vo ├── config ├── common └── utilscontroller层只做参数接收和结果返回service层写业务逻辑mapper层是MyBatis接口entity对应数据库表dto用于接口参数传输vo用于前端展示。这样的分层虽然多但好处是每个类的职责清晰协作开发时不容易冲突。MyBatis集成有两个关键点。第一是pom.xml里的依赖坐标dependency groupIdorg.mybatis.spring.boot/groupId artifactIdmybatis-spring-boot-starter/artifactId version2.3.2/version /dependency dependency groupIdcom.mysql/groupId artifactIdmysql-connector-j/artifactId scoperuntime/scope /dependency第二是application.yml里的配置。这里有个细节很多新手在这里卡半天新版MySQL连接器驱动类变了8.x版本要用com.mysql.cj.jdbc.Driver而且必须加上时区参数否则数据库连接会报错。spring: datasource: url: jdbc:mysql://localhost:3306/shipping_db?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai username: root password: 123456 driver-class-name: com.mysql.cj.jdbc.Driver mybatis: mapper-locations: classpath:mapper/*.xml type-aliases-package: com.xxx.shipping.entity configuration: map-underscore-to-camel-case: truemap-underscore-to-camel-case: true这个配置强烈建议打开数据库字段ships_status就能自动映射到Java属性shipsStatus省去大量ResultMap手写工作。2.3 关键接口设计运单生成与货物跟踪运单生成是船运系统最核心的接口。它的逻辑是前端提交一个订单主表数据和一组货物明细后端在同一个事务里完成三件事——插入订单主表、批量插入货物明细、扣减航次剩余舱位。我贴一段事务控制的伪代码思路比代码本身更重要Override Transactional(rollbackFor Exception.class) public Long createOrder(OrderCreateRequest request) { // 1. 校验航次是否存在且可订舱 Voyage voyage voyageMapper.selectById(request.getVoyageId()); if (voyage null || voyage.getRemainingSpace() 0) { throw new BusinessException(航次不存在或已无剩余舱位); } // 2. 生成订单主表 ShipOrder order new ShipOrder(); order.setOrderNo(generateOrderNo()); order.setCustomerId(request.getCustomerId()); order.setVoyageId(request.getVoyageId()); order.setStatus(OrderStatus.BOOKED.getCode()); orderMapper.insert(order); // 3. 插入货物明细 for (CargoItem item : request.getCargoItems()) { item.setOrderId(order.getId()); cargoMapper.insert(item); } // 4. 扣减剩余舱位 voyageMapper.decreaseRemainingSpace(request.getVoyageId(), request.getTotalWeight()); return order.getId(); }这里要注意几个细节。生成订单编号不能用简单的自增ID建议用日期加序列的格式比如SO20250612001既方便查询又不容易暴露业务量。扣减舱位时必须用乐观锁或UPDATE语句里的条件判断防止两个人同时下单超卖UPDATE voyage SET remaining_space remaining_space - #{weight} WHERE id #{voyageId} AND remaining_space #{weight}货物跟踪接口的核心是一张航迹节点表。每当船舶离港、到港、报关完成就在表里插入一条节点记录前端将查询结果按时间逆序渲染出来。接口返回的数据结构最好是嵌套的订单信息、当前状态、历史节点列表一次性返回减少前端请求次数。3. 前端Vue设计与核心交互逻辑3.1 前端工程结构与权限设计前端我建议直接使用Vite构建工具加Vue 3比Webpack热更新更快配置也更简单。项目的页面组织方式可以分为登录页、主布局、业务模块页面。主布局包含侧边菜单栏、顶部导航栏、面包屑和内容区登录后根据用户的角色动态渲染菜单。权限设计这里我多说几句。船运系统不像普通后台管理系统那样简单判断一个角色就完事经常会出现一个人身兼多职的情况客服主管同时可能要看财务报表调度员也可能需要查看客户信息。所以我在实际项目里用RBAC模型但增加了数据权限维度同一个功能菜单用户都能看到但查询数据时只能查到自己权限范围内的订单。Vue Router实现权限路由的常见思路是登录成功后后端返回该用户的角色编码和权限标识列表前端将这些权限标识和动态路由表做匹配过滤出可访问的页面再用router.addRoute()动态添加。这样用户在地址栏强行输入没有权限的URL时会被路由守卫拦截并跳转到403页面。3.2 核心页面拆解船期看板、运单列表与货物跟踪船期看板是调度员打开系统后最常看的页面。表格按时间轴排列横轴是日期纵轴是船舶每个格子代表一个航次。格子里显示航次编号、起止港、预计开航时间、剩余舱位。如果船期延误格子颜色变为红色并显示延误原因。实现船期看板的关键是数据结构。后端接口返回的每条记录包含startDate、endDate、shipName、voyageNo等字段前端根据日期范围生成表格坐标再用CSS Grid布局渲染。这个页面也可以用甘特图组件实现但中小型项目不值得引入重型图表库我建议用自绘的方式控制样式和交互。运单列表页是比较典型的表格加条件查询页面。顶部是筛选区域订单编号、客户名称、状态、起运日期范围。表格展示订单概要每个订单号是一个可点击链接点开后进入订单详情页。这里建议做成分页加懒加载因为订单表数据量增长很快一次查出几千条会让页面非常卡。我踩过的坑是表格列太多了。船运订单涉及的字段可能有二十多个全部放在一列不现实。后来按重要程度拆成两部分列表页只展示必要字段详情页用分步表单展示完整信息并用标签页把货物明细、费用明细、操作日志分开。这样页面简洁加载速度也快。3.3 axios封装与跨域处理前端请求后端接口统一走axios实例超时时间、基础URL、请求拦截器、响应拦截器都要在封装层配好。请求拦截器里从localStorage取出Token放到请求头service.interceptors.request.use(config { const token localStorage.getItem(token) if (token) { config.headers[Authorization] Bearer token } return config })响应拦截器里统一处理业务错误码和HTTP状态码比如401跳转登录页500弹出错误提示。这样业务页面里只需要关注接口返回值不需要每个请求都写一遍错误处理逻辑。跨域问题在开发环境用Vite的proxy配置解决在生产环境用Nginx反向代理解决。开发环境的配置如下server: { port: 3000, proxy: { /api: { target: http://localhost:8080, changeOrigin: true } } }这就意味着前端请求/api/login时Vite开发服务器会把请求转发到后端的http://localhost:8080/api/login。后端Controller的RequestMapping里统一加/api前缀前后端接口路径就对齐了。后端同时开启CORS配置允许前端开发服务器的请求跨域通过。4. 实操从零跑通环境准备与部署步骤4.1 开发环境版本选择这个项目我用的是JDK 8不要觉得老很多船运企业的生产服务器还在用8。JDK 8配SpringBoot 2.7兼容性最好。如果你用JDK 17SpringBoot 3.x也能跑但MyBatis Starter的版本要对应升级网上很多教程没写清楚版本关系照旧代码抄容易出事。Maven用3.6.3以上MySQL用5.7或8.0Node.js建议选18或20的LTS版本。这里特别提醒一个问题Node版本太新可能导致Vite脚手架下依赖时报错如果用的是老项目还会出现Node-sass编译失败。现在新项目基本都用Sass替代的Dart-Sass或者干脆不用SassCSS写起来也没问题。4.2 数据库初始化与后端启动拿到源码后不要直接启动后端先去看resources/sql目录下的初始化脚本。执行顺序很重要先建数据库再建用户表最后执行业务数据脚本。有些源码把表结构和数据写在一个文件里执行时容易因为排序问题报错。mysql -u root -p create database shipping_db default character set utf8mb4; use shipping_db; source /path/to/init.sql;执行完脚本后检查几张关键表的数据sys_user表有没有默认管理员账号dict_data字典表是否完整。没有字典数据的话前端下拉框会全部为空。启动后端之前把application.yml里的数据库账号密码改成你自己的。如果你用的是MySQL 8连接驱动和时区问题前面已经说过了。后端启动成功的标志是控制台输出Tomcat started on port 8080此时访问http://localhost:8080/api/health能返回JSON。4.3 前端启动与联调验证前端安装依赖时建议使用npm install不要图快使用cnpmcnpm经常导致node_modules目录结构异常运行起来各种莫名其妙的报错。安装完成后先启动开发服务器再检查控制台有没有代理请求报错。联调时要准备一份完整的业务数据走通流程。我最常用的验证路径是用管理员账号登录创建一个客户创建一个航次创建一笔包含两个货物明细的订单查看订单详情并推进状态然后生成结算单。这一条路径走通基本说明系统主要功能正常。5. 开发过船运系统之后才明白的几个深坑5.1 跨域问题和Cookie携带开发时用Vite代理跨域基本不会出问题。但如果前后端不在同一台服务器上部署生产环境跨域就要靠Nginx。我给某船运公司做生产部署时前端、后端分别部署在两台内网服务器上Nginx配置做了前后端分离转发静态前端页面放在一个server块请求/api前缀的路径统一转发到后端地址。这里有个容易漏的地方如果后端依赖Session而不是Token必须在Nginx转发时配置X-Forwarded-For头并后端开启对应支持否则登录状态一直失效。5.2 MySQL时区与SSL连接报错刚接触MySQL 8的人经常遇到两个报错。第一个是Server returns invalid timezone原因就是连接URL里没加serverTimezoneAsia/Shanghai。第二个是SSL connection error8.0版本默认开启SSL本地开发没必要用连接URL里加useSSLfalse关掉即可。5.3 MyBatis映射文件里的空格和逗号问题MyBatis动态SQL写多了就会遇到一个经典问题if标签拼接时多出逗号或多了AND。特别是明明是更新语句因为拼接顺序问题最后生成SQL多了空格导致语法错误。我的经验是动态SQL里面的逗号不要写在字段后面而是写在字段前面并配合WHERE之后的第一项永远不加连接符的习惯这样可以大大降低语法错误率。写完后养成一个习惯把mybatis.configuration.log-impl配置成StdOutImpl控制台打印完整SQL调试时无比省心。5.4 金额计算用BigDecimal而不是Double船运费用里的海运费、燃油附加费、港口费算下来动辄上万用Double会出精度丢失的问题。我的建议是数据库金额字段用decimal(18,2)Java对象用BigDecimal前端传输时保留两位字符串。计算不同币种的总额时汇率转换也必须在后端完成不要在多个接口里分散计算否则财务对账时发现几分钱对不上很难排查。5.5 运费的按航段拆分与附加费计算船运的运费计算比公路运输复杂得多很多时候同一个订单的货物要从起运港经过中转港再到目的港不同的航段费率不一样。设计费率表时要考虑「航线段」的概念一个完整的运输路径由若干个航线段拼接而成每个段有不同的基准费率和时效。订单创建时根据路径拆分航段分别计算费用再汇总。这块逻辑在需求阶段很容易被忽略但实际业务中一定是高频功能因为船运公司经常拿这个跟客户谈价格。我处理附加费时用了一个策略在订单创建完成后不直接锁定总费用而是保存费用计算快照后续如果有滞港费、改单费、超期堆存费再以追加费用的形式写入费用项目表最终汇总到结算单。这样既保留灵活的计费空间又保证账面清晰可追溯。5.6 权限和数据隔离的一个小坑船运公司集团化运作的话多个子公司在同一个系统里跑容易出现数据串门的问题。某用户登录后能查到另一家子公司的订单这非常严重。我的做法是在所有查询Mapper里都强制拼接company_id条件而不是在代码里用if判断是否拼接。这样即使开发者忘记传入公司IDSQL会因为缺少参数直接报错而不会默默查出全量数据。最后分享一个我自己的体会整个船运物流管理系统开发下来我最大的感受是技术本身不是瓶颈真正花时间的是把业务规则理解清楚。如果一开始拿到需求就急着建表写代码到了中期一定会因为费率计算、状态流转这些逻辑返工。建议第一次接触这类系统的朋友花两三天时间把业务流程图和状态图画出来确认清楚每个操作的前置条件和后续影响再动手建库表都不晚。另外有一点想单独提醒船运物流系统涉及的数据敏感性很高客户名单、价格信息、合同条款都属于商业机密。不管项目是自己练手还是给企业做交付从第一天起就要注意数据安全性。密码加密、接口鉴权、操作日志这些基础能力不能省前端页面展示也要留意脱敏手机号和地址在列表中默认打码显示。这个行业的口碑传播很快数据安全出了问题系统做得再好也没人会再用。