基于Java的TMS物流运输系统后端源码:运单状态机与计费引擎设计
简介:这是一套面向Java后端开发者与物流信息化学习者的TMS物流运输系统后端源码,适合需要理解企业级运输管理系统架构、或希望以此为基础进行二次开发与课程设计的技术人员。项目围绕订单管理、运输路线规划、货物跟踪等核心业务展开,涵盖委托、调度、结算、车队、网关等模块,目录划分清晰,便于按业务域阅读与拆解。压缩包共193个文件,约536KB,其中144个Java源文件承载主要业务逻辑,28个XML与10个YAML文件负责框架与参数配置,另有JAR包、Properties配置、Markdown说明及mvnw构建脚本,覆盖开发、打包与部署环节。目前已有635人学习下载,可作为理解TMS后端分层设计、接口组织与配置管理的实战参考,帮助读者快速把握物流系统从订单接入到运输跟踪的完整链路,并借鉴其模块化组织方式用于自身项目。
1. 从一张运单说起:Java TMS 物流运输系统后端到底在解决什么问题
一张运单从货主下单到签收回单,中间要经过调度派车、司机接单、在途上报、到达卸货、回单上传、对账结算至少六个状态节点。很多中小物流公司还在用 Excel 加微信群管这些事,调度员一天要打几十个电话确认车到哪了,财务月底对账靠翻聊天记录。TMS(Transportation Management System,物流运输系统)要干的事,就是把这套流程搬到线上,让状态流转有记录、运费计算有依据、异常情况能追溯。
这个标题里的关键词是「基于 Java」「后端」「源码」。它指向的是一套用 Java 技术栈实现的 TMS 服务端工程,通常采用 Spring Boot + MyBatis 的分层结构,对外提供 REST 接口给调度端、司机端、货主端调用。适合谁看?一是要做课程设计或毕业设计的学生,需要一套结构完整、能跑起来的后端参考;二是中小物流公司内部想自建系统的开发者,需要知道运单状态机、计费规则、车辆调度这些模块怎么落地;三是想从 CRUD 项目进阶到业务系统的 Java 后端,TMS 的领域模型比商城、博客复杂得多,是个不错的练手方向。
我做过两版 TMS 后端,第一版把运单状态硬编码在 Service 里,后来加「部分签收」「拒收退回」两个状态时改了十几个文件,血泪经验告诉我:运输系统的核心不是增删改查,而是状态机和计费引擎的设计。下面按「领域建模 → 工程搭建 → 核心模块 → 避坑 → 进阶」的顺序,把一套可复现的 Java TMS 后端方案讲清楚。
2. 领域建模与工程骨架:先把运单状态机和计费模型定下来
2.1 运单状态机:为什么不能用一个 status 字段打天下
新手最容易犯的错,是在 tms_order 表里放一个 status 字段,值从 0 到 9 表示不同状态,然后在 Service 里写一堆 if (status == 3) 。这种写法在状态少于 5 个、流转路径单一的时候能跑,但 TMS 的运单状态是典型的有限状态机:待调度 → 已派车 → 已装货 → 运输中 → 已到达 → 已签收,中间还可能插入「取消」「异常」「拒收」等分支,而且每个状态允许的操作不同(比如「运输中」不能改收货地址)。
常见做法是用枚举加状态流转表来约束。先定义状态枚举:
public enum OrderStatus {
PENDING_DISPATCH(10, "待调度"),
DISPATCHED(20, "已派车"),
LOADED(30, "已装货"),
IN_TRANSIT(40, "运输中"),
ARRIVED(50, "已到达"),
SIGNED(60, "已签收"),
CANCELLED(90, "已取消"),
EXCEPTION(99, "异常");
private final int code;
private final String desc;
// 构造、getter 省略
}
然后用一张流转规则表约束「从哪个状态能到哪个状态」:
public class OrderStateMachine {
private static final Map<OrderStatus, Set<OrderStatus>> TRANSITIONS = new HashMap<>();
static {
TRANSITIONS.put(PENDING_DISPATCH, Set.of(DISPATCHED, CANCELLED));
TRANSITIONS.put(DISPATCHED, Set.of(LOADED, CANCELLED, EXCEPTION));
TRANSITIONS.put(LOADED, Set.of(IN_TRANSIT, EXCEPTION));
TRANSITIONS.put(IN_TRANSIT, Set.of(ARRIVED, EXCEPTION));
TRANSITIONS.put(ARRIVED, Set.of(SIGNED, EXCEPTION));
// 终态不再流转
}
public static boolean canTransfer(OrderStatus from, OrderStatus to) {
return TRANSITIONS.getOrDefault(from, Set.of()).contains(to);
}
}
逻辑说明: TRANSITIONS 用静态块初始化,key 是当前状态,value 是允许到达的下一状态集合。每次改状态前调 canTransfer 校验,不合法就抛业务异常。参数上,状态码用 10、20 这种间隔值而不是 1、2、3,是为了以后在中间插入新状态时不用改已有数据。这套写法比在 Service 里堆 if-else 清晰得多,加状态只需要改枚举和流转表两处。
2.2 计费模型:按重计费、按方计费、按趟计费怎么抽象
运费计算是 TMS 里第二个容易翻车的地方。不同客户签的合同不一样:有的按重量(元/吨),有的按体积(元/方),有的按趟包干,还有的起步价加超出部分。如果给每种规则写一个 Service 方法,客户一多就爆炸。
我一般会抽象一个计费策略接口:
public interface FreightCalculator {
BigDecimal calculate(FreightContext context);
}
public class FreightContext {
private BigDecimal weight; // 重量(吨)
private BigDecimal volume; // 体积(方)
private BigDecimal distance; // 距离(公里)
private BigDecimal startPrice; // 起步价
private BigDecimal unitPrice; // 单价
// getter/setter 省略
}
按重计费的实现:
public class WeightBasedCalculator implements FreightCalculator {
@Override
public BigDecimal calculate(FreightContext ctx) {
BigDecimal base = ctx.getStartPrice() == null ? BigDecimal.ZERO : ctx.getStartPrice();
BigDecimal freight = ctx.getWeight().multiply(ctx.getUnitPrice());
return base.add(freight).setScale(2, RoundingMode.HALF_UP);
}
}
逻辑说明: FreightContext 把所有可能用到的计费因子都装进去,策略实现按需取用。 setScale(2, HALF_UP) 保证金额保留两位小数且四舍五入,避免 double 精度问题——金额一律用 BigDecimal ,这是铁律。参数上, startPrice 允许为空,为空时按 0 处理,这样按趟包干的场景只需要传 startPrice 即可。策略选择用工厂模式根据客户合同里的 billingType 字段决定,新增计费方式只需要加一个实现类,不动已有代码。
2.3 工程骨架:Spring Boot 分层与依赖选型
一套能跑的 TMS 后端,我一般用 Spring Boot 2.7 或 3.x(看 JDK 版本,JDK 8 用 2.7,JDK 17 用 3.x),核心依赖如下:
| 依赖 | 用途 | 选型理由 |
|---|---|---|
| spring-boot-starter-web | REST 接口 | 标配,不用多说 |
| mybatis-plus | ORM | 比原生 MyBatis 少写 XML,分页插件开箱即用 |
| mysql-connector-java | 数据库驱动 | MySQL 8 用 8.x 驱动 |
| spring-boot-starter-validation | 参数校验 | @NotNull 、 @Valid 省掉手写校验 |
| hutool-all | 工具类 | 日期、加密、Excel 导出都能用 |
| spring-boot-starter-data-redis | 缓存 | 运单号生成、司机位置缓存 |
包结构按领域划分,不要按技术分层:
com.example.tms
├── order // 运单域
│ ├── controller
│ ├── service
│ ├── mapper
│ ├── entity
│ └── dto
├── dispatch // 调度域
├── vehicle // 车辆域
├── driver // 司机域
├── billing // 计费域
└── common // 公共:异常、拦截器、工具
按领域分包的好处是,改运单相关逻辑时只在一个目录里动,不会像按 controller/service/mapper 分层那样满工程找文件。这个结构在若依框架前后端分离版本里也是类似思路,可以直接参考它的目录组织。
3. 核心模块落地:运单、调度、计费、回单四块的实现细节
3.1 运单模块:运单号生成与幂等创建
运单号是 TMS 的门面,格式一般是「前缀 + 日期 + 流水号」,比如 TMS202405200001 。用数据库自增 ID 拼日期最简单,但并发下容易重复。我一般用 Redis 的 INCR 保证原子性:
@Service
public class OrderNoGenerator {
@Autowired
private StringRedisTemplate redisTemplate;
public String generate() {
String date = LocalDate.now().format(DateTimeFormatter.ofPattern("yyyyMMdd"));
String key = "tms:order:no:" + date;
Long seq = redisTemplate.opsForValue().increment(key);
// 首次设置过期时间为 2 天,避免 key 堆积
if (seq != null && seq == 1) {
redisTemplate.expire(key, Duration.ofDays(2));
}
return "TMS" + date + String.format("%04d", seq);
}
}
逻辑说明: increment 是原子操作,多实例部署也不会重复。 seq == 1 时设置过期时间,保证每天一个 key,两天后自动清理。参数上, %04d 表示流水号补零到 4 位,一天超过 9999 单的物流公司要改成 %06d 。如果 Redis 挂了,降级方案是用数据库的 order_no 唯一索引兜底,插入冲突时重试。
创建运单还要考虑幂等:同一个客户短时间内重复提交,不能生成两张单。常见做法是客户端传一个 requestId ,服务端用 Redis setIfAbsent 做去重:
public Order createOrder(CreateOrderDTO dto) {
String idempotentKey = "tms:order:idem:" + dto.getRequestId();
Boolean success = redisTemplate.opsForValue()
.setIfAbsent(idempotentKey, "1", Duration.ofMinutes(10));
if (Boolean.FALSE.equals(success)) {
throw new BizException("请勿重复提交");
}
// 后续创建逻辑
}
参数说明: requestId 由前端生成(一般是 UUID),10 分钟过期意味着同一请求 10 分钟内只能创建一次。这个 key 要在创建成功后保留,不能提前删,否则幂等失效。
3.2 调度模块:车辆司机匹配与派车单生成
调度是 TMS 里业务最复杂的模块。核心逻辑是:根据运单的起点、终点、货物重量体积,从可用车辆里筛选匹配的车,然后生成派车单。筛选条件一般包括:车辆状态为空闲、载重够、车型匹配(厢式/平板/冷藏)、司机有对应驾照。
public List<Vehicle> matchVehicles(DispatchQuery query) {
LambdaQueryWrapper<Vehicle> wrapper = new LambdaQueryWrapper<>();
wrapper.eq(Vehicle::getStatus, VehicleStatus.IDLE.getCode())
.ge(Vehicle::getLoadCapacity, query.getWeight())
.eq(query.getVehicleType() != null, Vehicle::getType, query.getVehicleType())
.orderByAsc(Vehicle::getLastDispatchTime); // 优先派最近没出车的
return vehicleMapper.selectList(wrapper);
}
逻辑说明: ge 是大于等于,保证载重够; eq 带条件参数, vehicleType 为空时不参与筛选; orderByAsc 按上次派车时间升序,实现简单的公平调度。参数上, loadCapacity 单位是吨,要和运单重量单位一致,单位不统一是常见 bug 来源。
派车单生成后,要把车辆状态改成「已派车」,这一步必须和派车单插入在同一个事务里:
@Transactional(rollbackFor = Exception.class)
public DispatchOrder dispatch(Long orderId, Long vehicleId, Long driverId) {
// 1. 校验运单状态
Order order = orderMapper.selectById(orderId);
if (!OrderStateMachine.canTransfer(order.getStatus(), OrderStatus.DISPATCHED)) {
throw new BizException("当前状态不可派车");
}
// 2. 插入派车单
DispatchOrder dispatch = new DispatchOrder();
dispatch.setOrderId(orderId);
dispatch.setVehicleId(vehicleId);
dispatch.setDriverId(driverId);
dispatchMapper.insert(dispatch);
// 3. 更新运单状态
order.setStatus(OrderStatus.DISPATCHED);
orderMapper.updateById(order);
// 4. 更新车辆状态
vehicleMapper.updateStatus(vehicleId, VehicleStatus.DISPATCHED.getCode());
return dispatch;
}
@Transactional(rollbackFor = Exception.class) 是关键,默认只回滚 RuntimeException ,加上 rollbackFor 保证任何异常都回滚。四步操作要么全成功要么全失败,否则会出现「派车单有了但车辆还是空闲」的脏数据。
3.3 计费模块:合同价与临时价的优先级
实际业务里,运费有两种来源:一是客户签的合同价,二是临时议价。优先级一般是合同价优先,没有合同才用临时价。实现上,先查客户合同:
public BigDecimal calcFreight(Long orderId) {
Order order = orderMapper.selectById(orderId);
// 1. 查客户合同
Contract contract = contractMapper.selectByCustomerId(order.getCustomerId());
FreightContext ctx = buildContext(order);
if (contract != null) {
ctx.setStartPrice(contract.getStartPrice());
ctx.setUnitPrice(contract.getUnitPrice());
FreightCalculator calculator = FreightCalculatorFactory.get(contract.getBillingType());
return calculator.calculate(ctx);
}
// 2. 无合同,用临时价
if (order.getTempPrice() == null) {
throw new BizException("无合同且无临时价,无法计费");
}
return order.getTempPrice();
}
逻辑说明: buildContext 从运单里取重量、体积、距离等因子; FreightCalculatorFactory.get 根据合同的 billingType 返回对应策略。参数上,合同表要有 customerId 和 billingType 字段, billingType 用枚举字符串(WEIGHT/VOLUME/TRIP)而不是数字,可读性更好。临时价直接存在运单表上,调度员录入。
计费结果要落库到 order_freight 表,不能每次查询都重算,否则合同改了历史运单金额会变,这是财务大忌。
3.4 回单模块:文件上传与状态回写
回单是签收凭证,司机拍照片上传。后端要处理文件存储和运单状态回写。文件存储常见做法是存本地磁盘或对象存储,数据库只存路径:
@PostMapping("/receipt/upload")
public Result<String> uploadReceipt(@RequestParam("file") MultipartFile file,
@RequestParam("orderId") Long orderId) {
// 1. 校验文件类型
String originalName = file.getOriginalFilename();
String suffix = originalName.substring(originalName.lastIndexOf(".") + 1).toLowerCase();
if (!Set.of("jpg", "jpeg", "png", "pdf").contains(suffix)) {
throw new BizException("不支持的文件类型");
}
// 2. 按日期分目录存储
String datePath = LocalDate.now().format(DateTimeFormatter.ofPattern("yyyy/MM/dd"));
String fileName = UUID.randomUUID() + "." + suffix;
Path target = Paths.get("/data/tms/receipt", datePath, fileName);
Files.createDirectories(target.getParent());
file.transferTo(target.toFile());
// 3. 回写运单
String url = "/receipt/" + datePath + "/" + fileName;
orderMapper.updateReceipt(orderId, url);
return Result.ok(url);
}
逻辑说明:后缀白名单校验防止上传脚本文件,这是安全底线;按日期分目录避免单目录文件过多;文件名用 UUID 防止覆盖和路径猜测。参数上, /data/tms/receipt 是存储根路径,生产环境要挂独立数据盘,不要和系统盘混用。回单上传后运单状态是否自动改成「已签收」,要看业务:有的公司要求调度确认后才签收,那就只存文件不改状态。
注意:文件上传接口一定要限制大小,Spring Boot 默认单文件 1MB、单请求 10MB,在
application.yml里按需调整,别让司机传个 20MB 的原图把服务打挂。
4. 避坑与排查:TMS 后端上线后最容易翻车的五个地方
4.1 运单状态被并发改乱
现象:两个调度员同时操作同一张运单,一个派车一个取消,结果运单状态变成「已取消」但派车单还在,车辆被占用。
原因:状态校验和更新之间没有加锁,两个请求都通过了 canTransfer 校验,然后各自更新。
解决:用乐观锁。在 tms_order 表加 version 字段,更新时带上版本号:
UPDATE tms_order SET status = #{status}, version = version + 1
WHERE id = #{id} AND version = #{version}
影响行数为 0 说明被别人改过,抛异常让前端重试。MyBatis-Plus 的 @Version 注解能自动处理,不用手写 SQL。
4.2 计费金额出现小数精度错误
现象:运费算出来是 1234.5600000000002 这种值,财务对不上账。
原因:用了 double 或 float 做金额运算,浮点数本身有精度损失。
解决:所有金额字段用 BigDecimal ,数据库用 DECIMAL(12,2) ,Java 里运算用 BigDecimal 的方法,最后 setScale(2, RoundingMode.HALF_UP) 。别用 new BigDecimal(0.1) ,要用 new BigDecimal("0.1") ,前者会带入 double 的误差。
4.3 运单号在 Redis 重启后重复
现象:Redis 没设持久化,重启后 INCR 从 1 开始,生成的运单号和当天已有的重复,插入报唯一索引冲突。
原因:运单号生成强依赖 Redis 的计数器,Redis 数据丢了计数器就归零。
解决:两个办法。一是 Redis 开 AOF 持久化;二是数据库 order_no 加唯一索引,插入冲突时捕获异常重新生成。我一般两个都做,唯一索引是最后一道防线。另外可以在生成时先查一下数据库当天最大流水号,取 max(redis值, db值+1) ,多一次查询换安全。
4.4 派车后车辆状态没同步
现象:派车单生成了,但车辆列表里这辆车还是「空闲」,被重复派出去。
原因:派车逻辑里更新车辆状态的代码在事务外,或者更新时没加车辆状态的条件判断。
解决:更新车辆状态时带上原状态条件:
UPDATE tms_vehicle SET status = 'DISPATCHED'
WHERE id = #{id} AND status = 'IDLE'
影响行数为 0 说明车已经被别人派了,回滚整个派车事务。这个「条件更新」模式在库存扣减、状态流转场景都通用,是防并发的基础手段。
4.5 回单文件把磁盘写满
现象:服务跑几个月后磁盘告警,一看回单目录几百 GB。
原因:司机上传的原图没压缩,一张 5MB,一天几千张。
解决:上传时压缩。用 Thumbnails 库把图片压到长边 1920、质量 0.8,一般能压到 300KB 以内。PDF 不压缩但限制页数。另外加定时任务清理超过保留期的回单(比如 2 年),归档到冷存储。存储路径按日期分目录的好处这时候也体现出来了,清理时按目录删,不用扫全表。
5. 进阶:用状态机引擎和领域事件把 TMS 后端做扎实
前面用枚举加流转表实现的状态机,在状态少于 10 个、流转规则固定时够用。但如果要支持不同客户自定义流程(比如大客户要求「到达后先预约再卸货」),硬编码的流转表就不够了。这时候可以引入 Spring StateMachine 或轻量的 squirrel-foundation ,把状态、事件、动作、守卫条件配置化。我一般用 Spring StateMachine,因为它和 Spring 生态集成好,配置类里定义状态和转移:
@Configuration
@EnableStateMachineFactory
public class OrderStateMachineConfig extends StateMachineConfigurerAdapter<OrderStatus, OrderEvent> {
@Override
public void configure(StateMachineTransitionConfigurer<OrderStatus, OrderEvent> transitions) throws Exception {
transitions
.withExternal().source(OrderStatus.PENDING_DISPATCH).target(OrderStatus.DISPATCHED)
.event(OrderEvent.DISPATCH).action(dispatchAction())
.and()
.withExternal().source(OrderStatus.DISPATCHED).target(OrderStatus.LOADED)
.event(OrderEvent.LOAD);
}
}
dispatchAction() 里做派车单生成和车辆状态更新,状态流转和业务动作绑在一起,不会漏。代价是学习成本高,小项目没必要上。
另一个进阶方向是领域事件。运单签收后要触发一系列动作:通知货主、生成对账单、更新司机绩效。如果全写在签收方法里,方法会越来越长。用 Spring 的 ApplicationEventPublisher 发一个 OrderSignedEvent ,各个监听器各管各的:
// 发布
applicationEventPublisher.publishEvent(new OrderSignedEvent(orderId));
// 监听
@EventListener
public void onOrderSigned(OrderSignedEvent event) {
billingService.generateStatement(event.getOrderId());
}
这样签收逻辑只负责改状态和发事件,对账、通知、绩效都是独立监听器,加需求不动主流程。注意事件监听默认同步执行,耗时操作要加 @Async 并配线程池,否则签收接口会变慢。
验证一套 TMS 后端是否做扎实,我一般看三个指标:一是并发派车同一辆车,只有一单成功;二是同一运单重复提交创建,只生成一张单;三是合同价改了之后,历史运单金额不变。这三个过了,基本盘就稳了。
最后说个习惯:我每加一个状态流转,都会在测试类里写一条「非法流转必须抛异常」的用例,比如从「已签收」直接改「运输中」。这种用例写起来快,但能挡住后面无数次手滑。TMS 这种系统,数据错了比功能少了严重得多,宁可多写几行校验,也别给财务留后悔药。希望帮到你。
更多推荐




所有评论(0)