做物流信息系统的时候，很多团队一上来就堆功能，结果等到数据量上来、业务逻辑绕进去以后，改得想哭。我在实际开发中就踩过不少这样的坑，所以这次想把这个项目的完整思路和实现过程拆开聊一聊。这套系统用的是Java生态里非常经典的一套组合：SpringBoot做后端基础框架，Vue3做前端页面，MyBatis负责数据持久化，MySQL存数据，前后端完全分离。整个系统覆盖物流业务里的运单管理、车辆调度、司机任务、客户信息、在途跟踪、签收确认这些核心环节，适合做毕业设计、外包项目起步，或者中小型物流公司内部管理系统的基础版本。
写这篇东西的目的是把我从零搭建这套物流信息管理系统时的设计决策、核心表结构、接口思路、前端对接方式、以及最后部署时踩过的坑都整理出来。不管你是刚接触Java后端开发的学生，还是想快速搭一套管理后台的初级工程师，这篇文章的内容都能直接拿去做参考。我尽量把每一步为什么这么做的逻辑讲清楚，而不只是丢一堆代码出来。
1. 项目架构思路与技术选型
1.1 为什么选择前后端分离架构
物流信息管理系统这种业务型项目，天然就适合前后端分离。因为物流公司内部的使用场景通常是多个角色同时操作，比如前台开单员在录入运单，调度员在分配车辆，司机在手机端或者平板端更新状态，财务在看报表。如果做传统单体模板渲染，前端页面嵌在后端项目里，每一次页面调整都要重启后端服务，多角色并发操作时体验也会很糟糕。
前后端分离之后，后端只专注提供RESTful API，前端独立部署，两边通过JSON格式交换数据。这样做的好处非常直接：后端接口可以被多个客户端复用，比如管理员用的Web端、司机用的移动H5，甚至以后要接小程序，后端一套接口就够了。前端也可以独立迭代，不会因为页面样式改动影响到后端服务。
我在项目初始化时把整个工程分成了两个目录：logistics-server（后端SpringBoot工程）和logistics-web（前端Vue3工程）。开发环境里前端通过Vite代理转发请求到后端8080端口，生产环境则把前端构建后的静态文件交给Nginx托管，再通过Nginx反向代理到后端服务。这样部署方案清晰，也方便后续扩展负载均衡。
1.2 SpringBoot + MyBatis + MySQL这套组合的取舍
后端技术栈选SpringBoot、MyBatis、MySQL，是被市场验证过无数次的稳妥组合，不是盲目跟风。
SpringBoot的价值在于它把Spring生态里那些复杂的配置几乎都自动化了。以前用SSM框架的时候，要写一堆XML配置来管理Bean、事务、数据源，SpringBoot用约定大于配置的方式把这些都省掉了。内嵌Tomcat容器也省去了部署WAR包的麻烦，一个java -jar就能把服务跑起来，这对中小型项目来说非常友好。
MyBatis是我做这类管理系统的首选持久层框架。对比JPA/Hibernate，MyBatis的SQL是自己直接写的，控制力强，SQL语句做了什么都一目了然。物流系统里的查询往往比较复杂，比如运单列表要根据运单号、客户名、日期范围、状态等多个条件组合筛选，这种动态SQL在MyBatis里用XML写非常顺手。加上分页插件PageHelper，处理大数据量列表页也是标配级别的稳定。
MySQL这里没什么特别需要纠结的，选择社区版就够了。物流系统数据量再大，单表千万级以内MySQL都能扛得住。这活儿的重点在于索引设计和SQL优化，而不是频繁更换数据库。项目里统一使用InnoDB引擎，外键不用，通过业务代码维护数据关系的完整性。
提示：如果对版本兼容性没把握，后端SpringBoot建议使用2.7.x版本配合JDK8，这也是目前运行最稳定的组合。SpringBoot 3.x需要JDK17以上，Vue3相关生态虽然完整，但部分老依赖可能出现兼容问题。首次做项目不要给自己加难度，稳定版本足以应付绝大多数业务场景。
Vue3在前后端分离中扮演的是终端渲染角色。我用的是组合式API +<script setup>语法糖，这种写法比Options API更简洁，逻辑复用也更方便。配合Element Plus这个组件库，做后台管理系统的效率非常高，表格、表单、弹窗、日期选择器这些都是现成的，改改配置就能用。
2. 数据库设计：物流系统的核心是状态流
2.1 业务实体拆分与核心表结构
物流系统的数据模型看上去复杂，但拆开以后核心就是几个实体：运单、客户、车辆、司机、仓库、用户。真正有挑战的是运单在整个生命周期中的状态流转，这个后面会单独讲。
我设计的核心表包括：
customer：客户信息表，包含寄件人和收件人，统一用客户类型区分waybill：运单主表，记录货物基本信息、寄收件信息、当前状态、创建人vehicle：车辆信息表，存储车牌号、车型、载重、当前状态driver：司机信息表，包含姓名、手机号、驾驶证信息、状态transport_task：运输任务表，记录司机、车辆、发车时间、到达时间、关联运单waybill_track：运单轨迹表，记录每一次状态变更的时间和操作人sys_user：系统用户表，用于登录认证和权限控制
运单主表是这里面最核心的表，在设计的时候要特别注意字段的口径统一。比如运单号我用的是定长字符串，格式为WL + 年月日 + 4位流水号，这样方便人眼识别和后期检索。状态字段我直接用一个VARCHAR类型存储状态编码，对应关系在代码里维护枚举，这样在数据库层面看起来直观，排查问题时不用查字典表。
细说几个关键字段：
CREATE TABLE `waybill` ( `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键', `waybill_no` VARCHAR(32) NOT NULL COMMENT '运单号', `send_customer_id` BIGINT COMMENT '寄件客户ID', `receive_customer_id` BIGINT COMMENT '收件客户ID', `goods_name` VARCHAR(100) COMMENT '货物名称', `goods_weight` DECIMAL(10,2) COMMENT '货物重量(kg)', `goods_count` INT COMMENT '货物件数', `status` VARCHAR(20) NOT NULL DEFAULT 'CREATED' COMMENT '运单状态', `expect_arrival_time` DATETIME COMMENT '预计到达时间', `actual_arrival_time` DATETIME COMMENT '实际到达时间', `create_time` DATETIME NOT NULL COMMENT '创建时间', `update_time` DATETIME NOT NULL COMMENT '更新时间', PRIMARY KEY (`id`), UNIQUE KEY `uk_waybill_no` (`waybill_no`), KEY `idx_status` (`status`), KEY `idx_create_time` (`create_time`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='运单主表';订单号记得加唯一索引。这不是漂亮的习惯问题，而是防重的最直接手段。实际运营中人工录入运单，难免重复提交，数据库层面的唯一约束兜底最可靠。
时间字段全部用DATETIME，不要用TIMESTAMP。两者的区别在于TIMESTAMP有2038年问题，而且受时区影响，DATETIME存的是字面时间，不随数据库时区变化而变，对物流系统这种涉及跨区域操作的系统更安全。货物重量用DECIMAL(10,2)而不是FLOAT或DOUBLE，这个坑做财务相关功能的时候一定会碰到，浮点数在计算时会有精度丢失。
2.2 运单状态流转表设计思路
物流系统的核心业务本质上是运单状态的状态机：从创建、已装货、运输中、已到达、已签收，中间还可能穿插异常状态比如滞留、拒收。我强烈建议把状态变更记录独立成一张表，叫作waybill_track，不要简单地在运单主表里更新状态字段就完事。
为什么一定要独立状态表？因为运单的状态记录不仅对客户是透明的（要让他们看到货物走到哪一步了），对公司内部也是追溯责任的关键依据。谁在什么时间把状态从“运输中”改成了“已到达”，这些信息在出现货损、延误纠纷时，就是最直接的证据链。
waybill_track表的设计：
CREATE TABLE `waybill_track` ( `id` BIGINT NOT NULL AUTO_INCREMENT, `waybill_id` BIGINT NOT NULL COMMENT '运单ID', `from_status` VARCHAR(20) COMMENT '变更前状态', `to_status` VARCHAR(20) NOT NULL COMMENT '变更后状态', `operation_user_id` BIGINT NOT NULL COMMENT '操作人ID', `remark` VARCHAR(255) COMMENT '备注信息', `create_time` DATETIME NOT NULL, PRIMARY KEY (`id`), KEY `idx_waybill_id` (`waybill_id`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='运单轨迹记录';这里有个设计经验分享给读者：在写入轨迹的时候，顺便把操作人的信息冗余进去，这样查询轨迹列表时直接能展示“谁在什么时候做了什么”，避免再去关联用户表拿姓名。虽然理论上可以JOIN，但物流系统的轨迹查询频率极高，减少一次JOIN就少一次性能损耗，数据冗余在业务可接受的范围内是划算的选择。
2.3 索引设计的关键原则
很多新人在建表的时候不太重视索引，等数据量大了才开始补，那时候代价就高了。物流系统里，运单表、运输任务表都是写入频繁、查询更频繁的表，索引设计直接影响接口响应速度。
我的索引设计原则很简单：等值查询的字段加普通索引，范围查询的字段考虑放在复合索引的最后。比如运单列表页最常见的查询是“查某段时间内某个状态的运单”，这时候(status, create_time)复合索引是最优解。单字段索引和复合索引的区分是，复合索引能覆盖多个查询条件时，效率远高于分别加两个独立索引。
索引不是越多越好。每次INSERT的时候索引都要更新，索引过多会拖慢写入速度。物流系统运单录入频繁，索引必须克制，一张表的核心索引控制在3~5个以内就够了。
3. 后端核心实现细节
3.1 SpringBoot项目初始化与目录结构
后端工程我用Maven管理，项目结构遵循业界标准的包分层：
com.company.logistics ├── controller // 接口层 ├── service // 业务逻辑层 ├── mapper // MyBatis Mapper接口 ├── entity // 实体类 ├── dto // 数据传输对象 ├── common // 通用响应体、异常处理、工具类 └── config // 配置类这里要说明一个习惯：实体类（entity）尽量和数据库字段一一对应，而接口入参和返回参数单独定义DTO。很多新手图省事，直接用实体类接收前端参数，这样做短期开发快，但是一旦表结构调整，接口参数就跟着变了，耦合度很高。尤其是运单创建接口，前端传来的数据可能包含货物明细列表，而运单表和货物明细表是分开的，用DTO把这两组数据聚合起来，才是正确的做法。
3.2 MyBatis核心配置与动态SQL实战
MyBatis的配置有几处关键点直接影响开发体验和线上稳定，这里一一说明。
第一处是驼峰映射。数据库字段以下划线分隔，Java属性用驼峰命名，如果不在配置里开启驼峰映射，每次查询结果映射时都会因为字段名不匹配导致属性为null。配置就一行：
mybatis: configuration: map-underscore-to-camel-case: true第二处是SQL日志打印。开发阶段建议大家把SQL日志打印出来，方便调试：
logging: level: com.company.logistics.mapper: debug第三处是MyBatis中XML文件的动态SQL写法。运单列表查询是个典型的动态筛选场景：
<select id="selectWaybillPage" resultType="com.company.logistics.entity.Waybill"> SELECT * FROM waybill <where> <if test="waybillNo != null and waybillNo != ''"> AND waybill_no LIKE CONCAT('%', #{waybillNo}, '%') </if> <if test="status != null and status != ''"> AND status = #{status} </if> <if test="startTime != null"> AND create_time >= #{startTime} </if> <if test="endTime != null"> AND create_time <= #{endTime} </if> </where> ORDER BY create_time DESC </select>这里有几个细节。WHERE关键字用<where>标签包裹，MyBatis会自动处理首个子句前面的AND，比手动写WHERE 1=1要整洁得多。时间范围查询用>=和<=是因为XML中>和<不能直接使用，需要转义。LIKE查询要手动拼接CONCAT('%', #{waybillNo}, '%')，如果用'%${waybillNo}%'这种字符串拼接方式，会有SQL注入风险。
3.3 PageHelper分页插件的接入与避坑
列表分页我直接用的PageHelper，这是国内用的最多的MyBatis分页插件。使用方式很简单，在查询前调用PageHelper.startPage(pageNum, pageSize)，紧接着的第一次查询就会被自动加上LIMIT语句。
我的实际使用经验：PageHelper.startPage()之后必须紧跟查询语句，中间不能有其他数据库操作。如果中间穿插了其他查询，分页可能作用到错误的SQL上。另外PageHelper只对紧跟着的第一条查询生效，所以当业务代码里在一个方法中多次查询时，要保证分页查询放在最后一步，或者每次都单独声明PageHelper.startPage()。
分页查询的返回结果我用PageInfo对象包装，里面自带了total、pageNum、pageSize等属性，直接返回给前端就很方便。
3.4 统一响应体与全局异常处理
接口设计这块，我一开始就定了统一响应格式：
{ "code": 200, "message": "success", "data": {} }不管成功失败，后端都返回这个结构。前端在Axios拦截器里统一判断code，成功则取出data，失败则弹出message提示。这样做的好处是接口调用方不需要关心HTTP状态码的各种语义，只需要盯着业务码就行。
全局异常处理使用@RestControllerAdvice注解，把业务异常、参数校验异常、系统异常分类处理。特别注意参数校验异常，SpringBoot的@Validated注解配合@NotNull、@NotBlank这些约束，校验失败时抛出MethodArgumentNotValidException，在全局异常处理器中把具体的字段错误信息提取出来返回给前端，这样前端表单就能精准提示“运单号不能为空”而不是笼统的“系统错误”。
注意：统一异常处理里一定要记录完整的异常堆栈日志，尤其是
Exception级别的兜底捕获。只返回错误信息不打印日志，会让线上问题排查变成猜谜游戏。这一点开发初期就养成习惯，后面省很多事。
3.5 运单创建与状态流转的核心事务实现
运单创建这个操作不是单表写入，它要同时完成运单主表插入、货物明细插入、初始轨迹记录三个动作。这三个动作要么全部成功，要么全部失败，不能出现运单创建了但轨迹没记录的脏数据。
SpringBoot里用@Transactional注解解决事务问题。默认情况下，只有RuntimeException才会触发回滚，如果方法内部抛的是受检异常（Exception），需要显式指定rollbackFor = Exception.class。这是个经典坑点，很多人写@Transactional不指定rollbackFor，结果业务代码抛了自定义异常，事务没回滚，数据库出现半截数据。
状态流转逻辑我封装在了WaybillService里：
@Transactional(rollbackFor = Exception.class) public void updateWaybillStatus(Long waybillId, String toStatus, Long userId, String remark) { Waybill waybill = waybillMapper.selectById(waybillId); if (waybill == null) { throw new BusinessException("运单不存在"); } String fromStatus = waybill.getStatus(); // 校验状态流转是否合法 if (!StatusMachine.isValidTransition(fromStatus, toStatus)) { throw new BusinessException("非法的状态流转：" + fromStatus + " -> " + toStatus); } // 更新运单主表 waybillMapper.updateStatus(waybillId, toStatus); // 写入轨迹记录 WaybillTrack track = new WaybillTrack(); track.setWaybillId(waybillId); track.setFromStatus(fromStatus); track.setToStatus(toStatus); track.setOperationUserId(userId); track.setRemark(remark); waybillTrackMapper.insert(track); }状态合法性校验这里我单独抽了一个StatusMachine类，用Map或者枚举定义好所有允许的状态流转路径。比如“已签收”状态不允许直接跳回“运输中”，这种约束必须在后端强校验，不能只靠前端按钮控制。设计的时候把状态流转规则集中管理，比散落在各个业务方法里好维护得多。
4. Vue3前端页面与接口对接
4.1 前端工程结构与路由设计
前端工程我用的Vite构建，Vue3 + Vue Router + Pinia + Element Plus这套组合。工程结构按照模块划分：
src ├── api // 接口请求封装 ├── components // 公共组件 ├── views // 页面组件 │ ├── waybill // 运单管理 │ ├── vehicle // 车辆管理 │ ├── driver // 司机管理 │ ├── customer // 客户管理 │ ├── dashboard // 首页看板 │ └── login // 登录 ├── router // 路由配置 ├── store // Pinia状态管理 └── utils // 工具函数路由配置方面，后台管理系统我用了动态路由的思路，根据登录用户的角色动态生成可访问的路由表。简单来说，登录成功后后端返回当前用户的角色和权限标识，前端根据权限标识过滤出可访问的路由，再通过router.addRoute()动态添加。这样不同角色的用户登录后看到的菜单不一样，司机账号看不到财务模块，管理员能看到全部模块。
4.2 Axios封装与请求拦截
前端和后端的数据交互全部走Axios，我在utils/request.js里做了一层封装。核心逻辑是请求拦截器自动携带Token，响应拦截器统一处理业务错误和HTTP错误：
import axios from 'axios' import { ElMessage } from 'element-plus' import { useUserStore } from '../store/user' import router from '../router' const request = axios.create({ baseURL: '/api', timeout: 10000 }) // 请求拦截器 request.interceptors.request.use(config => { const userStore = useUserStore() if (userStore.token) { config.headers.Authorization = `Bearer ${userStore.token}` } return config }) // 响应拦截器 request.interceptors.response.use( response => { const res = response.data if (res.code !== 200) { ElMessage.error(res.message || '请求失败') if (res.code === 401) { userStore.logout() router.push('/login') } return Promise.reject(new Error(res.message)) } return res.data }, error => { ElMessage.error(error.message || '网络错误') return Promise.reject(error) } )Token的存储我放在了Pinia里，同时同步存储到localStorage，这样页面刷新后登录状态不会丢失。后端接口用JWT做无状态认证，Token设置了过期时间，过期后前端收到401状态码时，自动清理本地登录状态并跳转登录页。
4.3 运单列表页与核心组件实现
运单管理页面是整个系统使用频率最高的页面，它的前端实现很有代表性：顶部是筛选条件表单，中间是操作按钮区，下面是表格展示区，最下面是分页栏。
筛选这块我用Element Plus的el-form配合inline模式，把运单号、状态、创建时间范围这几个筛选条件放在一行，用户在输入框回车或点击查询按钮时触发数据加载。这里有一个我自己用的细节：把查询逻辑抽成一个fetchData方法，表格数据加载、分页变化、条件查询都复用这个方法来请求接口，避免在各个事件处理器里重复写请求逻辑。
状态标签展示用el-tag组件，根据状态码映射不同的标签颜色。这个映射关系跟前端协商好以后，写一个计算属性就行了：
const statusMap = { CREATED: { text: '已创建', type: 'info' }, LOADED: { text: '已装货', type: 'warning' }, IN_TRANSIT: { text: '运输中', type: 'primary' }, ARRIVED: { text: '已到达', type: 'warning' }, SIGNED: { text: '已签收', type: 'success' }, ABNORMAL: { text: '异常', type: 'danger' } }运单详情弹窗里嵌入了轨迹时间线组件。Element Plus的el-timeline组件非常适合展示运单的状态流转历史，按时间倒序把waybill_track表中的记录渲染成一条时间线，每一步显示状态变更内容、操作人和操作时间。这个页面做好以后，整个系统的核心体验就立起来了，客户打电话来问“我的货到哪了”，客服直接在系统里看一眼时间线就能回答。
4.4 Vue3组合式API的实战使用心得
在用Vue3写这个项目的时候，我强烈建议大家直接使用<script setup>组合式API，不要用Options API。组合式的核心优势是逻辑聚合，比如运单列表页需要管理筛选条件、表格数据、加载状态、分页信息，这些状态用ref和reactive定义在一起，相关的fetchData方法也放在附近，代码的阅读顺序就是业务的执行顺序。
跨组件状态共享用Pinia，比如用户登录信息、当前选中的车辆调度状态等。Pinia的设计比Vuex简单多了，没有那么多概念，就是一个defineStore组合式写法一把梭。
对于业务里的一些通用逻辑，比如导出Excel、重置表单，我会抽成自定义组合式函数（composables），放在src/composables目录。这样多个页面复用同一种逻辑时，不需要复制粘贴代码，直接引入函数即可。这个习惯一旦养成，后续扩展新模块的效率会明显提升。
5. 核心业务场景：运单全流程与车辆调度
5.1 完整的运单业务链路
物流系统表面上在管理数据，实际上管理的是一条完整业务链。我梳理一下这套系统涉及的流程，这决定了页面菜单的设定和接口的划分。
系统里首先要有客户信息，包括寄件人和收件人。前台开单员创建运单，录入货物名称、件数、重量，选择寄收件客户，此时运单状态为“已创建”。调度员看到待调度的运单列表，安排匹配的车辆和司机，生成运输任务，状态变为“已装货”或“运输中”。司机在运输途中通过系统更新位置信息或者到达信息，状态变为“已到达”。最终收件人签收货物后，运单状态变为“已签收”。如果运输过程中发生延误、破损等情况，状态置为“异常”。
这套流程看起来简单，但涉及到两个关键问题：一个是谁来触发状态更新，另一个是怎么保证状态流转的合法性。我的方案是每种状态的更新都有对应的接口：createWaybill（创建）、assignTransport（调度）、startTransport（发车）、arriveStation（到达）、signWaybill（签收）、markAbnormal（标记异常）。在Service层做状态合法性校验，确保不允许从“已签收”跳到“运输中”这种非法操作。
5.2 前端接口调用与状态流转展示的配合
前端在这一步要做的事情，是把不同状态下可执行的操作动态渲染出来。我根据运单详情中的当前状态返回，动态生成操作按钮。比如状态为“已创建”时显示“分配车辆”按钮，“运输中”时显示“标记到达”按钮。这样避免了前端写死逻辑，新增状态或者调整操作权限的时候，只需要改后端返回的availableActions列表。
后端接口返回的数据结构大概是：
{ "waybillInfo": { "waybillNo": "WL20250101001", "status": "IN_TRANSIT", ... }, "trackList": [ { "fromStatus": "CREATED", "toStatus": "LOADED", ... } ], "availableActions": ["markArrived", "markAbnormal"] }前端拿到availableActions之后，循环渲染按钮，没有权限的操作直接不出现。这种把按钮权限放到后端的做法，比前端用v-if判断当前状态要灵活得多，因为权限规则如果变了，后端改一下返回数据就行，前端不用重新发版。
5.3 车辆调度与司机任务分配
车辆调度是物流系统的另一块核心业务。我在设计上把调度环节拆成了两个步骤：先给运单匹配合适的车辆和司机，再把它们关联起来生成运输任务。为什么不一次性完成？因为实际业务中，一辆车可能捎带多个运单，比如同一批次从同一个仓库发往同一个城市的货物，往往合并到一辆车上。这种场景下，运输任务和运单是多对多的关系。
数据库里我需要三张表来支撑这个关系：transport_task（运输任务主表）、transport_task_waybill（任务与运单关联表）、task_driver（任务与司机关联表）。用关联表而不是冗余字段，是为了让“一车多单”“一单换车”这些操作都有地方记录。
调度接口的事务逻辑也很关键：创建运输任务、更新运单状态为“已调度”、分配司机、分配车辆，这四个动作要在一个事务里完成。我在实现中用@Transactional包住了整个调度方法，并且在校验阶段就检查车辆和司机是否是“空闲”状态，防止同一辆车被分配进两个任务。
车辆和司机的状态管理有一个细节：车辆状态分为“空闲”“运输中”“维修中”，司机状态分为“空闲”“出车中”“休假中”。每次车辆调度完成后，车辆状态改为“运输中”，司机改为“出车中”。运输任务完成后，这两者的状态要同步恢复为“空闲”。这个状态的一致性维护，我建议在任务完成接口中一并处理，不要分开两个接口调用，否则很容易漏掉一步导致状态残留。
6. 常见问题与排查技巧实录
6.1 日期格式与序列化问题
前后端日期格式不一致是联调阶段最常碰到的问题。后端返回的LocalDateTime默认格式是2025-01-15T10:30:00，前端表单或者表格里显示出来非常难看，而且如果前端要回传日期参数，这种格式还容易被解析出错。
我的统一解决方案是，在SpringBoot配置里全局定义日期格式化：
spring: jackson: date-format: yyyy-MM-dd HH:mm:ss time-zone: GMT+8对于LocalDateTime类型，光配date-format是不够的，还要配合Jackson的JavaTimeModule，或者在字段上加@JsonFormat注解。为了统一，我在项目里直接写了一个JacksonConfig配置类，注册JavaTimeModule并设置日期格式，这样所有接口返回的日期都是yyyy-MM-dd HH:mm:ss格式，前端的el-date-picker直接就能解析。
6.2 跨域配置与代理方案
前后端分离开发的时候，跨域是绕不开的问题。前端开发服务器默认跑在http://localhost:5173，后端跑在http://localhost:8080，直接调用接口会被浏览器拦截。
开发环境的解法是在Vite配置文件里加代理：
server: { proxy: { '/api': { target: 'http://localhost:8080', changeOrigin: true } } }这样前端请求/api/waybill/list时，Vite开发服务器自动转发到后端的/api/waybill/list，浏览器看到的还是同一个域名端口，不存在跨域问题。
如果是生产环境用Nginx部署，同样在Nginx配置里做一层location /api反向代理。我个人的习惯是开发环境走代理，生产环境走Nginx，后端接口真正设置@CrossOrigin的场景反而不常见，因为开放跨域意味着任何人都可以跨域调接口，不利于安全控制。
6.3 MyBatis常见运行期错误总结
Invalid bound statement (not found)：这个报错几乎每个用MyBatis的人都会遇到。原因是Mapper接口的方法在XML文件中找不到对应的SQL。检查顺序是：XML文件中的namespace是否指向Mapper接口全限定名、XML中的id是否和接口方法名完全一致、YAML中的mapper-locations是否扫描到了XML文件路径。
Parameter 'xxx' not found：当Mapper方法参数个数超过一个且没有用@Param注解时，MyBatis无法识别参数名。解决方式是每个参数都加上@Param("xxx")注解，或者在XML中用#{0}、#{1}这种位置参数引用，但可读性差，不推荐。
二级缓存引起的脏读：MyBatis的二级缓存默认关闭，但有些教程会让你打开。在涉及多表关联查询的时候，二级缓存会导致更新某张表后，关联查询的结果还是旧数据。物流系统数据实时性要求高，我的建议是保持二级缓存关闭，不要为了那点性能提升引入这种难排查的问题。
6.4 数据库连接池与并发问题排查
系统上线后如果遇到接口偶尔报错，且错误信息里有Connection is not available之类的提示，十有八九是数据库连接池的配置问题。SpringBoot默认使用的HikariCP连接池，理论上性能很好，但默认的maximum-pool-size是10，如果并发请求比较多，连接池打满后新的请求就要等待，超时就会报错。
我在实际项目中的配置如下：
spring: datasource: hikari: maximum-pool-size: 30 minimum-idle: 10 connection-timeout: 30000这个数值不是越大越好，数据库服务器本身能承受的连接数有限。对中小型物流系统来说，30个连接基本够用。如果同时在线用户量大，还要考虑的是扩容数据库而不是无限调大连接池。
6.5 数据库密码安全配置
最后一个比较容易被忽视的点：不要在application.yml里明文写数据库密码。尤其是项目发到网上的时候，数据库密码暴露等于整个系统裸奔。我的做法是使用jasypt-spring-boot加密组件，把真实密码用密文配置在文件中，部署时通过环境变量传入解密密钥。
spring: datasource: password: ENC(加密后的密文)Env环境变量里配置JASYPT_ENCRYPTOR_PASSWORD，运行时再解密。这个操作花不了多少时间，但对系统的安全性提升非常大。很多新手的项目源码直接发布到网上，打开application.yml就能看到数据库密码、Redis密码，这是很不专业的做法。
项目部署的最终几个细节
部署这套系统的时候，我踩过几次坑，把最终稳定运行的方案罗列出来。
后端打包用的是mvn clean package，加上配置文件外置。我习惯把application-prod.yml放在打包后的jar包同级目录下，SpringBoot启动时自动读取外部配置文件：
java -jar logistics-server.jar --spring.profiles.active=prod数据库脚本我在项目里维护了一个sql/init.sql，包含建库建表语句和初始管理员账号数据。新环境部署的时候先执行脚本，再启动后端，这比用代码自动建表要稳，因为表结构的字段注释和索引设计可以在SQL脚本里写得很明确，数据库管理团队看起来也直观。
前端构建用npm run build，产物是dist目录下的静态文件，扔到Nginx的html目录下。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; }前端路由用的createWebHistory()模式，Nginx需要配置try_files把所有未匹配的路径回退到index.html，否则刷新页面时会出现404。这个坑我在第一次部署时踩了，印象很深。
最后，这套系统开发完成后，我最大的体会是：技术栈本身并不值钱，值钱的是对业务流转的理解和对细节的把控。SpringBoot+Vue3这套技术组合，网上能搜到一堆现成模板，但真正决定项目能不能落地的，是运单状态流转是否严谨、数据权限是否清晰、异常流程是否兜住。如果你正在开发类似系统，建议把业务状态流转画出来，先把状态机盘明白，再写代码，会省掉后面大量返工的痛苦。
