简介:这是一套面向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 这种系统,数据错了比功能少了严重得多,宁可多写几行校验,也别给财务留后悔药。希望帮到你。

本文还有配套的精品资源,点击获取 menu-r.4af5f7ec.gif

Logo

电商企业物流数字化转型必备!快递鸟 API 接口,72 小时快速完成物流系统集成。全流程实战1V1指导,营造开放的API技术生态圈。

更多推荐