简介这份资源是面向Java后端开发者与物流信息化学习者的TMS物流运输系统后端源码适合需要理解企业级运输管理系统架构、或希望以此为基础进行二次开发与课程设计的技术人员。项目围绕订单管理、运输路线规划、货物跟踪等核心业务展开涵盖调度、结算、车队、网关等模块能帮助读者快速把握物流后端的分层设计与业务逻辑组织方式。压缩包共193个文件约536KB其中144个Java源文件构成主要业务实现28个XML与10个YAML文件负责框架及环境配置另有JAR包、Properties配置、Markdown文档、CMD脚本与mvnw构建文件便于部署与运行。目前已有635人学习下载可作为理解TMS后端结构、梳理模块职责与排错思路的参考素材。1. 从一张运单说起Java 写的 TMS 后端到底在管什么一张运单从客服录单到客户签收中间要经过调度分配、司机接单、在途上报、到达卸货、回单上传、财务对账六个环节。每个环节的数据都散在不同角色手里靠微信群和 Excel 传递丢件、错单、对账扯皮就成了日常。TMSTransportation Management System物流运输系统要解决的核心问题就是把这六个环节的状态和责任人锁在一条数据链上让每一票货的当前位置和下一动作都有据可查。这套后端用 Java 写主流选型是 Spring Boot MyBatis-Plus MySQL Redis权限层常见做法是接 RuoYi 或 Sa-Token。它适合两类人一是做 Java 课程设计或毕业设计、需要一套能跑通业务闭环的参考实现二是中小物流团队想自建调度系统、又不想从零搭权限和基础模块。下面按「数据模型怎么定 → 核心接口怎么写 → 状态机怎么防错 → 部署怎么落地」的顺序拆开讲参数和坑都给到能直接抄的程度。2. 运单、车辆、司机三张主表怎么定字段与索引的取舍2.1 先定状态字段再定业务字段TMS 后端最容易翻车的地方不是接口写不出来而是状态字段设计得太随意。我一般先把运单的生命周期画成一条单向链CREATED → ASSIGNED → PICKED_UP → IN_TRANSIT → DELIVERED → SIGNED → SETTLED每个状态对应一个枚举值存成tinyint而不是直接存中文字符串。原因很实际字符串状态在联合索引里占空间且改文案时容易漏改查询条件。运单主表tms_waybill的核心字段如下注意status和assign_status是两个维度——前者是货物物理状态后者是调度分配状态混在一起会导致「已分配但未揽收」这类中间态无法表达。字段名类型说明是否索引idbigint主键雪花 ID主键waybill_novarchar(32)运单号业务唯一唯一索引customer_idbigint客户 ID普通索引statustinyint货物状态枚举联合索引assign_statustinyint调度状态枚举联合索引origin_cityvarchar(32)起运城市联合索引dest_cityvarchar(32)目的城市联合索引vehicle_idbigint分配车辆普通索引driver_idbigint分配司机普通索引create_timedatetime创建时间普通索引联合索引建议建在(status, assign_status, create_time)上因为调度看板最常见的查询是「查所有待分配且未完成的运单按时间倒序」。如果只给status单列索引MySQL 在数据量过十万后大概率走全表扫描这是血泪经验。2.2 车辆与司机表的关键约束车辆表tms_vehicle要区分「自有车」和「外协车」用owner_type字段标记。司机表tms_driver必须存license_no驾驶证号和vehicle_id当前绑定车辆但不要用外键约束——物流场景里司机换车频繁外键会导致更新顺序死锁。常见做法是在应用层用事务保证一致性。CREATE TABLE tms_waybill ( id BIGINT NOT NULL COMMENT 雪花ID, waybill_no VARCHAR(32) NOT NULL COMMENT 运单号, customer_id BIGINT NOT NULL COMMENT 客户ID, status TINYINT NOT NULL DEFAULT 0 COMMENT 0创建 1已分配 2已揽收 3在途 4已送达 5已签收 6已结算, assign_status TINYINT NOT NULL DEFAULT 0 COMMENT 0待分配 1已分配 2已取消, origin_city VARCHAR(32) NOT NULL, dest_city VARCHAR(32) NOT NULL, vehicle_id BIGINT DEFAULT NULL, driver_id BIGINT DEFAULT NULL, create_time DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (id), UNIQUE KEY uk_waybill_no (waybill_no), KEY idx_status_assign_time (status, assign_status, create_time) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4 COMMENT运单主表;这段建表语句里status和assign_status都用TINYINT而不是ENUM因为ENUM加值要改表结构线上改表风险高。create_time默认CURRENT_TIMESTAMP省去应用层赋值但要注意时区——MySQL 连接串必须带serverTimezoneAsia/Shanghai否则跨时区部署时运单时间会差 8 小时对账直接对不上。3. 调度分配接口怎么写从 Controller 到 Service 的完整链路3.1 分配车辆的核心逻辑与并发控制调度分配的本质是「给一张待分配运单绑定一辆可用车辆和司机」。这里有两个并发问题同一辆车不能被同时分配给两张运单同一张运单不能被两个调度员同时分配。常见做法是用 Redis 分布式锁 数据库乐观锁双保险。Service public class DispatchService { Autowired private WaybillMapper waybillMapper; Autowired private VehicleMapper vehicleMapper; Autowired private RedisTemplateString, String redisTemplate; public void assign(Long waybillId, Long vehicleId, Long driverId) { String lockKey tms:dispatch:waybill: waybillId; Boolean locked redisTemplate.opsForValue() .setIfAbsent(lockKey, 1, 10, TimeUnit.SECONDS); if (Boolean.FALSE.equals(locked)) { throw new BizException(该运单正在被其他调度员处理); } try { // 乐观锁更新只有 assign_status0 才能分配 int rows waybillMapper.assignVehicle(waybillId, vehicleId, driverId); if (rows 0) { throw new BizException(运单状态已变更请刷新后重试); } // 车辆状态置为占用 vehicleMapper.updateStatus(vehicleId, 1); } finally { redisTemplate.delete(lockKey); } } }setIfAbsent的 10 秒过期时间是经验值调度操作正常在 2 秒内完成10 秒足够覆盖网络抖动又不会因为宕机导致锁永久不释放。assignVehicle对应的 SQL 必须带AND assign_status 0条件这是乐观锁的关键——即使 Redis 锁失效数据库层也能兜住。update idassignVehicle UPDATE tms_waybill SET vehicle_id #{vehicleId}, driver_id #{driverId}, assign_status 1, status 1 WHERE id #{waybillId} AND assign_status 0 /update参数说明assign_status 0是前置条件status 1表示进入已分配状态。如果返回影响行数为 0说明运单已被别人分配或已取消Service 层直接抛业务异常前端提示刷新。3.2 在途上报接口的幂等设计司机在途上报位置和节点是高频操作网络差时司机会连点接口必须幂等。常见做法是用「运单号 节点类型 上报时间戳」做唯一键重复插入直接忽略。public void reportNode(NodeReportDTO dto) { // 幂等键运单号节点分钟级时间戳 String idempotentKey dto.getWaybillNo() : dto.getNodeType() : (dto.getReportTime().getTime() / 60000); Boolean first redisTemplate.opsForValue() .setIfAbsent(tms:report: idempotentKey, 1, 5, TimeUnit.MINUTES); if (Boolean.FALSE.equals(first)) { return; // 重复上报直接返回成功 } nodeMapper.insert(dto.toEntity()); // 更新运单主状态 waybillMapper.updateStatusByNode(dto.getWaybillNo(), dto.getNodeType()); }分钟级时间戳做幂等粒度是权衡结果秒级太细司机正常操作也可能触发重复小时级太粗同一小时内两次真实上报会被误判。5 分钟过期是因为上报节点本身有先后顺序超过 5 分钟的重复上报大概率是补录应该放行。4. 状态机与对账怎么防止运单状态被改乱4.1 用状态机替代散落的 if-else运单状态流转如果写成if (status 1) { status 2; }这种散落判断三个月后没人能说清哪些流转合法。我一般引入一个轻量状态机把合法流转定义成配置。public enum WaybillStatus { CREATED(0), ASSIGNED(1), PICKED_UP(2), IN_TRANSIT(3), DELIVERED(4), SIGNED(5), SETTLED(6); private final int code; WaybillStatus(int code) { this.code code; } private static final MapWaybillStatus, SetWaybillStatus TRANSITIONS Map.of( CREATED, Set.of(ASSIGNED), ASSIGNED, Set.of(PICKED_UP, CREATED), PICKED_UP, Set.of(IN_TRANSIT), IN_TRANSIT, Set.of(DELIVERED), DELIVERED, Set.of(SIGNED), SIGNED, Set.of(SETTLED) ); public static boolean canTransfer(WaybillStatus from, WaybillStatus to) { return TRANSITIONS.getOrDefault(from, Set.of()).contains(to); } }ASSIGNED可以回退到CREATED是因为调度分配后司机可能拒单需要重新分配。其他状态一律单向不允许回退。每次状态变更前调用canTransfer校验不合法直接抛异常并记录操作日志这样出问题时能查到是谁在什么时间试图做非法流转。4.2 对账接口的金额精度处理物流对账涉及运费、油费、过路费、补贴多项加减用double算必然出现0.1 0.2 0.30000000000000004这类问题。Java 里必须用BigDecimal且除法要指定精度和舍入模式。public BigDecimal calcSettlement(Long waybillId) { Waybill wb waybillMapper.selectById(waybillId); BigDecimal freight wb.getFreight(); // 运费 BigDecimal fuelSurcharge wb.getFuelSurcharge(); // 油补 BigDecimal toll wb.getToll(); // 过路费 BigDecimal subsidy wb.getSubsidy(); // 补贴 return freight.add(fuelSurcharge) .subtract(toll) .add(subsidy) .setScale(2, RoundingMode.HALF_UP); }setScale(2, RoundingMode.HALF_UP)是必须的因为数据库DECIMAL(12,2)只存两位小数不显式设置精度会在插入时抛异常或静默截断。HALF_UP是财务惯例不要用HALF_EVEN否则对账时客户会质疑为什么 0.005 被舍掉了。5. 避坑与排查TMS 后端上线后最容易翻车的五件事5.1 运单号重复现象是插入报唯一键冲突原因是雪花 ID 时钟回拨现象高峰期批量录单时偶发Duplicate entry异常但运单号生成逻辑看起来没问题。原因雪花算法依赖系统时钟如果服务器做了 NTP 同步导致时钟回拨同一毫秒内可能生成重复 ID。解决在 ID 生成器里加时钟回拨检测回拨超过 5 毫秒就等待超过 100 毫秒直接抛异常让上层重试或者运单号改用「日期 数据库自增序列」的组合牺牲一点性能换稳定。5.2 调度看板数据延迟现象是刚分配的运单在列表里看不到原因是 Redis 缓存没失效现象调度员 A 分配完运单调度员 B 刷新看板还是旧数据。原因看板列表走了 Redis 缓存分配操作只更新了数据库没删缓存。解决分配成功后主动delete看板缓存 key或者用Caffeine Redis两级缓存本地缓存过期时间设短一点比如 3 秒接受短暂不一致。5.3 在途轨迹丢失现象是司机上报成功但后台查不到原因是事务里发了 MQ 但消息没落库现象司机端提示上报成功但后台轨迹列表缺了几个节点。原因上报接口在事务里先发 MQ 再写库MQ 发送成功但数据库回滚了。解决改成先写库再发 MQ或者用本地消息表 定时补偿。更简单的做法是轨迹上报不走 MQ直接同步写库量级不大的话完全够用。5.4 对账金额差几分钱现象是系统算的和 Excel 算的对不上原因是 BigDecimal 除法没指定精度现象财务用 Excel 算的运费和系统差 0.01。原因某处用了BigDecimal.divide()没传scale遇到除不尽的情况抛ArithmeticException被全局异常吞掉走了默认值。解决全局搜索所有divide调用强制传scale和RoundingMode在代码规范里把这条列为必检项。5.5 部署后接口 404现象是本地跑得好好的Tomcat 部署后部分接口找不到原因是前后端分离项目 context-path 配错现象/api/waybill/list本地能通部署到服务器返回 404。原因application.yml里server.servlet.context-path配了/tms但前端请求没带前缀或者 Nginx 转发时把前缀吃掉了。解决统一约定——后端不配context-path所有接口以/api开头Nginx 转发规则写成location /api/ { proxy_pass http://127.0.0.1:8080/api/; }前后端都按这个约定来别各自发挥。6. 进阶技巧用 MyBatis-Plus 分页插件把调度列表查询压到 50ms 内调度看板是 TMS 后端压力最大的查询数据量上来后分页查询很容易超过 500ms。我一般从三个地方下手分页插件配置、查询字段裁剪、覆盖索引。先看分页插件配置MyBatis-Plus 的分页插件必须显式设置maxLimit否则前端传pageSize10000会把数据库拖死。Configuration public class MybatisPlusConfig { Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor new MybatisPlusInterceptor(); PaginationInnerInterceptor page new PaginationInnerInterceptor(DbType.MYSQL); page.setMaxLimit(200L); // 单页最大 200 条 page.setOverflow(false); // 超过最大页返回空而不是首页 interceptor.addInnerInterceptor(page); return interceptor; } }setMaxLimit(200L)是硬限制前端传再大也最多返回 200 条。setOverflow(false)很重要——默认true时请求第 999 页会返回第一页数据调度员会以为数据错乱设成false返回空列表更符合预期。然后是查询字段裁剪。调度列表只需要运单号、起止城市、状态、创建时间不要SELECT *。在 Mapper 里显式指定字段配合覆盖索引(status, assign_status, create_time, waybill_no, origin_city, dest_city)让查询完全走索引不回表。select idselectDispatchPage resultTypeDispatchVO SELECT waybill_no, origin_city, dest_city, status, create_time FROM tms_waybill WHERE assign_status 0 AND status lt; 6 ORDER BY create_time DESC LIMIT #{offset}, #{limit} /select这个查询在 50 万行数据下实测能压到 30-50ms关键就是覆盖索引——WHERE、ORDER BY、SELECT涉及的字段全在索引里MySQL 不需要回表。如果加了customer_name这种需要 join 的字段性能会掉到 200ms 以上这时候要么冗余字段要么把 join 拆成两次查询在应用层拼。最后说一个验证方法在 MySQL 里对慢查询开slow_query_log阈值设long_query_time 0.1跑一天后看mysqldumpslow排前几的 SQL基本都是缺索引或SELECT *导致的。我自己的习惯是每次加新查询接口先在测试库用EXPLAIN看一眼type是不是ref或range出现ALL就直接打回重写。这套 TMS 后端从建表到调度接口再到对账真正花时间的不是写代码而是把状态流转和索引这两件事想清楚。希望帮到你。本文还有配套的精品资源点击获取
