Java后端TMS物流运输系统实战：运单状态机、调度派单与计费规则设计

简介：本资源为基于Java开发的TMS物流运输系统后端设计源码，面向具备一定Java基础、希望深入理解企业级物流系统架构的开发者与学习者。项目围绕订单管理、运输路线规划、货物跟踪等核心业务展开，涵盖调度、结算、车队管理、网关及通用模块，可用于学习后端分层设计与业务逻辑实现。压缩包共193个文件，约536KB，其中144个Java源码文件承载主要业务逻辑，28个XML与10个YAML文件负责框架及环境配置，另含JAR打包文件、Properties配置、Markdown说明文档以及mvnw构建脚本，结构完整、便于部署与二次开发。目前已有635人学习下载。通过研读源码，读者可掌握TMS系统从订单委托、调度派发到结算处理的完整链路，理解配置管理与项目构建方式，并借鉴其并发处理与模块划分思路，为物流类后端项目开发提供可复用的参考。

1. 从一张运单说起：Java 后端在 TMS 物流运输系统里到底扛了什么

一张运单从货主下单到签收回单，中间要经过调度分配、承运商确认、司机接单、在途轨迹上报、到达卸货、回单上传、对账结算至少七个状态节点。每个节点都可能出现改单、取消、拆分、合单、异常滞留。用 Excel 加微信群撑到日均三百单还行，过了这个量级，调度员会开始怀疑人生——运单状态对不上、运费算错、司机说没收到派单、财务说回单少了两张。TMS（Transportation Management System，物流运输系统）后端要解决的核心问题就一句话：让每一张运单的状态流转可追溯、可计算、可对账。

用 Java 做这套后端，不是因为 Java 时髦，而是这个场景天然需要强类型、事务边界清晰、生态里现成的状态机、规则引擎、定时调度、消息队列组件足够成熟。热搜里「java面试题」「mybatis源码」「spring boot + mybatis」这些词频繁出现，说明大量从业者正在用 Spring Boot + MyBatis 这套组合做业务系统，TMS 恰好是这套技术栈最典型的落地场景之一。这篇文章面向两类人：一是手里有 TMS 后端源码、想读懂架构再动手改的开发者；二是准备从零搭一套 TMS 后端、需要知道表怎么设计、状态怎么流转、运费怎么算的工程师。下面按「领域模型 → 核心链路 → 落地实现 → 避坑 → 进阶」的顺序拆开讲，每一步都落到能抄的代码和参数上。

2. TMS 后端的领域模型与表结构：先想清楚运单、运力、计费三件事

2.1 运单主表与状态机的字段设计

TMS 后端最容易翻车的地方不是代码写得多烂，而是表结构一开始就没把「状态」和「状态变更记录」分开。常见做法是把status字段直接放在运单主表上，改一次状态就 update 一次，结果出了问题查不到是谁在什么时间改的、改之前是什么状态。我一般会拆成两张表：tms_waybill存当前快照，tms_waybill_status_log存每一次流转记录。

-- 运单主表：只存当前状态快照 CREATE TABLE tms_waybill ( id BIGINT PRIMARY KEY AUTO_INCREMENT, waybill_no VARCHAR(32) NOT NULL COMMENT '运单号，业务唯一键', customer_id BIGINT NOT NULL COMMENT '货主ID', carrier_id BIGINT COMMENT '承运商ID，调度后回填', driver_id BIGINT COMMENT '司机ID，接单后回填', origin_code VARCHAR(16) NOT NULL COMMENT '起运地行政区划码', dest_code VARCHAR(16) NOT NULL COMMENT '目的地行政区划码', cargo_weight DECIMAL(12,3) NOT NULL DEFAULT 0 COMMENT '货物重量(kg)', cargo_volume DECIMAL(12,3) NOT NULL DEFAULT 0 COMMENT '货物体积(m³)', freight_amount DECIMAL(12,2) COMMENT '运费金额，计费后回填', status TINYINT NOT NULL DEFAULT 10 COMMENT '当前状态码', version INT NOT NULL DEFAULT 0 COMMENT '乐观锁版本号', created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, UNIQUE KEY uk_waybill_no (waybill_no), KEY idx_customer_status (customer_id, status), KEY idx_carrier_status (carrier_id, status) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='运单主表'; -- 状态流转日志：只追加，不修改 CREATE TABLE tms_waybill_status_log ( id BIGINT PRIMARY KEY AUTO_INCREMENT, waybill_no VARCHAR(32) NOT NULL, from_status TINYINT NOT NULL COMMENT '变更前状态', to_status TINYINT NOT NULL COMMENT '变更后状态', operator_id BIGINT NOT NULL COMMENT '操作人ID', operator_type TINYINT NOT NULL COMMENT '1-货主 2-调度 3-司机 4-系统', remark VARCHAR(255) COMMENT '变更备注', created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, KEY idx_waybill_no (waybill_no) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='运单状态流转日志';

逻辑说明：主表用version字段做乐观锁，防止两个调度员同时抢一张运单派给不同司机。状态日志表只 insert 不 update，任何状态变更都必须先写日志再改主表，顺序反了就会出现「主表状态变了但日志没记上」的黑匣子。参数上，status用 TINYINT 而不是 VARCHAR，是因为状态码在代码里要参与条件判断和索引，字符串比较在百万级运单下会明显拖慢查询。origin_code和dest_code用行政区划码而不是自由文本，是为了后续按区域做运力匹配和线路报价。

2.2 运力资源表与司机承运商的关系

运力侧要回答的问题是：谁有车、车能拉多少、司机归哪个承运商管、司机当前是否可接单。常见做法是拆成tms_carrier（承运商）、tms_driver（司机）、tms_vehicle（车辆）三张表，司机和车辆是多对多关系，用一张tms_driver_vehicle关联表维护。

CREATE TABLE tms_driver ( id BIGINT PRIMARY KEY AUTO_INCREMENT, carrier_id BIGINT NOT NULL COMMENT '所属承运商', name VARCHAR(32) NOT NULL, phone VARCHAR(16) NOT NULL, id_card_no VARCHAR(32) COMMENT '证件号，脱敏存储', status TINYINT NOT NULL DEFAULT 1 COMMENT '1-空闲 2-在途 3-休息 4-停用', max_load_kg DECIMAL(12,3) NOT NULL DEFAULT 0 COMMENT '可承接最大重量', created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, UNIQUE KEY uk_phone (phone), KEY idx_carrier_status (carrier_id, status) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='司机表';

逻辑说明：status字段是调度匹配的核心过滤条件，派单时只查status=1的司机。max_load_kg用来做重量匹配，避免把 30 吨的货派给一辆限载 10 吨的车。注意id_card_no这类敏感字段，生产环境要么加密存储要么只存后四位，源码里如果直接明文存，上线前必须改掉，这是合规红线。

2.3 计费规则表：运费不是算出来的，是配出来的

运费计算是 TMS 后端最容易被低估的模块。不同客户、不同线路、不同货物类型，计费方式可能完全不同：有的按重量，有的按体积，有的按趟次，有的按重量加体积取大值。硬编码 if-else 写到第三十个客户就会失控。我一般用一张tms_freight_rule表把规则配置化。

逻辑说明：计费时按customer_id精确匹配优先、origin_code最长前缀匹配次之的顺序选规则，取effective_from <= now < effective_to的那条。charge_type=4时分别算重量费和体积费取大值。这套设计的好处是运营改价格不用发版，坏处是规则冲突时排查麻烦，所以每次计费必须把命中的rule_id记到运单上，方便对账时回溯。

3. 核心链路落地：下单、调度、在途、结算四段代码怎么写

3.1 下单接口：幂等、校验、落库三步不能少

下单是 TMS 后端的入口，也是最容易出重复单的地方。货主网络抖动重试一次，后端就多一张运单，调度员看到两张一样的单会直接骂人。幂等键用customer_id + 外部单号做唯一索引，插入冲突就返回已有运单。

@Service public class WaybillCreateService { @Autowired private WaybillMapper waybillMapper; @Autowired private WaybillStatusLogMapper statusLogMapper; @Transactional(rollbackFor = Exception.class) public String createWaybill(WaybillCreateCmd cmd) { // 1. 幂等校验：外部单号已存在直接返回 Waybill exist = waybillMapper.selectByCustomerAndOuterNo( cmd.getCustomerId(), cmd.getOuterNo()); if (exist != null) { return exist.getWaybillNo(); } // 2. 基础校验：起终点不能为空，重量体积不能为负 if (StringUtils.isBlank(cmd.getOriginCode()) || StringUtils.isBlank(cmd.getDestCode())) { throw new BizException("起运地或目的地为空"); } if (cmd.getCargoWeight().compareTo(BigDecimal.ZERO) < 0) { throw new BizException("货物重量不能为负"); } // 3. 生成运单号并落库 String waybillNo = "TMS" + System.currentTimeMillis() + String.format("%04d", ThreadLocalRandom.current().nextInt(10000)); Waybill waybill = new Waybill(); waybill.setWaybillNo(waybillNo); waybill.setCustomerId(cmd.getCustomerId()); waybill.setOriginCode(cmd.getOriginCode()); waybill.setDestCode(cmd.getDestCode()); waybill.setCargoWeight(cmd.getCargoWeight()); waybill.setCargoVolume(cmd.getCargoVolume()); waybill.setStatus(WaybillStatus.CREATED.getCode()); // 10 waybillMapper.insert(waybill); // 4. 写状态日志 statusLogMapper.insert(buildLog(waybillNo, WaybillStatus.NONE.getCode(), WaybillStatus.CREATED.getCode(), cmd.getOperatorId(), "货主下单")); return waybillNo; } }

逻辑说明：@Transactional保证运单主表和状态日志表要么都成功要么都回滚。幂等校验放在最前面，避免重复插入触发唯一索引异常。运单号用时间戳加随机数，生产环境如果并发量高，建议换成雪花算法或数据库序列，时间戳在毫秒级并发下仍有碰撞可能。参数上，WaybillStatus.CREATED对应状态码 10，这个码值要和前端、调度端约定一致，改码值等于改协议，必须走版本管理。

3.2 调度派单：乐观锁抢单与运力匹配

调度派单的本质是「把一张待派运单分配给一个可用司机」。多个调度员同时操作时，必须防止一张单被派两次。用主表的version字段做乐观锁，update 时带上版本号，影响行数为 0 就说明被别人抢先了。

public boolean dispatch(String waybillNo, Long driverId, Long operatorId) { // 1. 查运单当前状态，必须是待调度 Waybill waybill = waybillMapper.selectByNo(waybillNo); if (waybill.getStatus() != WaybillStatus.CREATED.getCode()) { throw new BizException("运单当前状态不可调度"); } // 2. 查司机是否空闲且载重足够 Driver driver = driverMapper.selectById(driverId); if (driver.getStatus() != DriverStatus.IDLE.getCode()) { throw new BizException("司机当前不可接单"); } if (driver.getMaxLoadKg().compareTo(waybill.getCargoWeight()) < 0) { throw new BizException("司机载重不足"); } // 3. 乐观锁更新运单 int rows = waybillMapper.updateDispatch(waybillNo, driverId, driver.getCarrierId(), WaybillStatus.DISPATCHED.getCode(), waybill.getVersion()); if (rows == 0) { throw new BizException("运单已被其他调度员派单"); } // 4. 更新司机状态为在途 driverMapper.updateStatus(driverId, DriverStatus.ON_ROAD.getCode()); // 5. 写状态日志 statusLogMapper.insert(buildLog(waybillNo, WaybillStatus.CREATED.getCode(), WaybillStatus.DISPATCHED.getCode(), operatorId, "调度派单给司机" + driverId)); return true; }

逻辑说明：updateDispatch的 SQL 里WHERE waybill_no = ? AND version = ?，版本号不匹配就更新不到，这是乐观锁的标准写法。参数上，WaybillStatus.DISPATCHED对应状态码 20，DriverStatus.ON_ROAD对应 2。注意司机状态更新和运单更新不在同一个事务里会有不一致风险，实际项目里要么加分布式事务，要么用本地消息表补偿，源码里如果只是简单 update，高并发下会出现「运单派了但司机还是空闲」的脏数据。

3.3 在途轨迹上报：高频写入怎么不拖垮数据库

司机端每隔几十秒上报一次位置，一张运单在途几小时就是几百条轨迹。直接往 MySQL 写，单表很快到千万级，查询和写入都会变慢。常见做法是轨迹先写消息队列，再由消费端批量落库，或者直接写时序数据库。如果源码里用的是 MySQL，至少要做两件事：按运单号分表，或者按时间分区。

@RestController @RequestMapping("/api/track") public class TrackController { @Autowired private KafkaTemplate<String, String> kafkaTemplate; @PostMapping("/report") public Result<Void> report(@RequestBody TrackReportCmd cmd) { // 轨迹不直接落库，先发消息队列削峰 String key = cmd.getWaybillNo(); String value = JSON.toJSONString(cmd); kafkaTemplate.send("tms-track-topic", key, value); return Result.ok(); } }

逻辑说明：用waybillNo做 Kafka 的 key，保证同一张运单的轨迹进同一分区，消费端可以按运单顺序处理。参数上，tms-track-topic的分区数建议按日均轨迹量除以单分区承载量来定，一般单分区每秒几千条没问题。消费端批量攒够 500 条或每 2 秒 flush 一次，用INSERT INTO ... VALUES (...),(...)批量插入，比逐条插入快一个数量级。如果源码里没有消息队列直接写库，先加索引idx_waybill_time (waybill_no, report_time)，再考虑分表。

3.4 结算对账：运费计算与回单核销

结算段要做两件事：算运费、核销回单。运费按第 2.3 节的规则表算，回单核销是确认司机上传的回单和运单匹配。对账时最怕的是「运费算出来和客户预期不一致」，所以每次计算都要把命中的规则和计算过程记下来。

public BigDecimal calculateFreight(Waybill waybill) { // 1. 按货主+线路匹配计费规则 FreightRule rule = ruleMapper.matchRule( waybill.getCustomerId(), waybill.getOriginCode(), waybill.getDestCode()); if (rule == null) { throw new BizException("未匹配到计费规则"); } // 2. 按计费类型计算 BigDecimal amount; switch (rule.getChargeType()) { case 1: // 按重量 amount = waybill.getCargoWeight().multiply(rule.getUnitPrice()); break; case 2: // 按体积 amount = waybill.getCargoVolume().multiply(rule.getUnitPrice()); break; case 3: // 按趟次 amount = rule.getUnitPrice(); break; case 4: // 取大值 BigDecimal byWeight = waybill.getCargoWeight().multiply(rule.getUnitPrice()); BigDecimal byVolume = waybill.getCargoVolume().multiply(rule.getUnitPrice()); amount = byWeight.max(byVolume); break; default: throw new BizException("未知计费类型"); } // 3. 最低消费兜底 if (amount.compareTo(rule.getMinCharge()) < 0) { amount = rule.getMinCharge(); } // 4. 记录命中的规则，方便对账回溯 waybillMapper.updateFreight(waybill.getWaybillNo(), amount, rule.getRuleId()); return amount; }

逻辑说明：matchRule的 SQL 按customer_id精确匹配优先、origin_code和dest_code前缀匹配次之排序，取第一条。参数上，unit_price用 DECIMAL(10,4) 是为了支持「每公斤 0.35 元」这种精度，用 float 会出现 0.1+0.2 不等于 0.3 的经典问题。min_charge兜底逻辑不能省，否则短途单算出来运费几块钱，连油费都不够。

4. 避坑与排查：TMS 后端上线后最常被叫去救火的五件事

4.1 运单状态对不上，日志表却是空的

现象：调度端显示运单已派单，司机端显示待接单，查状态日志表发现最后一条还是「货主下单」。原因：状态变更代码里先 update 主表再 insert 日志，中间抛异常导致日志没写进去，或者两个操作不在同一事务里。解决：把状态变更封装成一个统一方法，强制「先写日志再改主表」，并且加@Transactional。如果已经出现脏数据，用主表当前状态反推补一条日志，备注写「数据修复」。

4.2 运费算出来和客户合同差几块钱

现象：财务对账时发现某张运单运费比合同少 3.5 元。原因：计费规则匹配到了旧版本的unit_price，或者effective_to边界处理有问题，now < effective_to写成了now <= effective_to，导致失效当天的单子用了旧价。解决：规则匹配 SQL 里时间边界统一用左闭右开，并且每次计费把rule_id和unit_price快照到运单上，对账时直接比对快照而不是重新算。

4.3 司机状态卡在「在途」，新单派不出去

现象：司机明明已经签收，状态还是「在途」，调度派单时提示「司机当前不可接单」。原因：签收接口只更新了运单状态，忘了把司机状态改回「空闲」，或者更新司机状态时抛了异常被吞掉。解决：签收逻辑里把「运单签收」和「司机置闲」放在同一事务，并且加一个定时任务，每天凌晨扫描超过 24 小时仍在途的司机，人工确认后强制置闲。

4.4 轨迹表写入变慢，接口超时

现象：司机端上报轨迹接口 P99 从 200ms 涨到 3s。原因：轨迹表没有按时间分区，单表数据量过亿，insert 时索引维护开销变大。解决：短期加idx_waybill_time覆盖索引，长期按report_time做月度分区，或者把轨迹迁到时序数据库。如果源码里轨迹和运单同库，先把轨迹表拆到独立库，避免拖累运单查询。

4.5 并发下单出现重复运单号

现象：两个货主同一毫秒下单，运单号后四位随机数相同，唯一索引冲突报错。原因：运单号生成用时间戳加四位随机数，并发高时碰撞概率不可忽略。解决：换成雪花算法，或者用数据库序列表tms_sequence每次UPDATE ... SET current_val = current_val + 1再取，虽然多一次数据库交互但绝对不重复。源码里如果是时间戳方案，上线前压测一下并发下单，碰撞率超过万分之一就得换。

5. 进阶技巧：用状态机引擎把流转规则从代码里抽出来

前面几章的状态流转都是硬编码 if-else，运单状态少的时候没问题，状态一多、流转条件一复杂，代码就会变成一坨。我一般会在项目中期引入轻量状态机，把「什么状态可以转到什么状态、需要什么条件」配置化。Spring StateMachine 是常见选择，但配置偏重，小项目用枚举加转移表更轻。

public enum WaybillStatus { NONE(0), CREATED(10), DISPATCHED(20), ACCEPTED(30), PICKED_UP(40), IN_TRANSIT(50), ARRIVED(60), SIGNED(70), SETTLED(80), CANCELLED(99); private final int code; WaybillStatus(int code) { this.code = code; } public int getCode() { return code; } // 允许的流转关系：key 是当前状态，value 是可达状态集合 private static final Map<WaybillStatus, Set<WaybillStatus>> TRANSITIONS = new HashMap<>(); static { TRANSITIONS.put(CREATED, EnumSet.of(DISPATCHED, CANCELLED)); TRANSITIONS.put(DISPATCHED, EnumSet.of(ACCEPTED, CANCELLED)); TRANSITIONS.put(ACCEPTED, EnumSet.of(PICKED_UP, CANCELLED)); TRANSITIONS.put(PICKED_UP, EnumSet.of(IN_TRANSIT)); TRANSITIONS.put(IN_TRANSIT, EnumSet.of(ARRIVED)); TRANSITIONS.put(ARRIVED, EnumSet.of(SIGNED)); TRANSITIONS.put(SIGNED, EnumSet.of(SETTLED)); } public static boolean canTransfer(WaybillStatus from, WaybillStatus to) { Set<WaybillStatus> targets = TRANSITIONS.get(from); return targets != null && targets.contains(to); } }

逻辑说明：TRANSITIONS用 EnumSet 存可达状态，canTransfer在每次状态变更前调用，不满足直接抛异常。这样新增状态或调整流转关系只改这一张表，不用满项目找 if-else。参数上，状态码 10 到 80 每 10 一个间隔，留出插入空间，比如以后要在「已接单」和「已提货」之间加「已到达装货点」，可以用 35。注意CANCELLED设为 99 而不是 90，是为了和正常流转区分开，查询时status < 90就是有效运单。

验证状态机是否生效，最直接的办法是写单元测试覆盖所有非法流转。

@Test public void testIllegalTransition() { // 已签收的运单不能再取消 assertFalse(WaybillStatus.canTransfer( WaybillStatus.SIGNED, WaybillStatus.CANCELLED)); // 已创建的运单可以取消 assertTrue(WaybillStatus.canTransfer( WaybillStatus.CREATED, WaybillStatus.CANCELLED)); // 已提货的运单不能回到已接单 assertFalse(WaybillStatus.canTransfer( WaybillStatus.PICKED_UP, WaybillStatus.ACCEPTED)); }

这套状态机加单元测试的组合，我在三个 TMS 项目里都用过，最大的好处是新人接手时不用问「这个状态能不能改」，看枚举定义就清楚了。血泪经验是：状态机一定要在项目早期引入，等到三十个 if-else 写完再重构，测试用例能写到你怀疑人生。另外，状态变更日志的from_status和to_status必须从状态机里取，不要手写数字，手写迟早写错。

最后说一个我自己的习惯：每次上线新状态或改流转规则前，先把生产库的运单状态分布拉出来看一眼，确认没有卡在中间状态的异常单，否则新规则一上，那些异常单可能永远流转不下去。这个习惯帮我省过至少两次半夜回滚。希望帮到你。

本文还有配套的精品资源，点击获取