企业官网建设流程全解析

简介：基于Java物流管理系统的毕业设计文档，围绕电商成熟背景下物流公司订单管理系统展开，面向需要完成Java Web课程设计或毕业设计的计算机专业学生，也适合开发人员参考B/S架构管理系统设计思路。资源为单个doc文档，压缩包约1.09MB，正文从摘要、Abstract到目录、绪论、需求分析、系统设计、功能实现均完整覆盖。目前已有1705人学习下载。文档对客户信息管理、物流信息管理、客户订单管理与货物配送管理等模块做了说明，并给出需求用例、可行性分析、数据库E-R图、数据表设计、连接处理与乱码处理等核心内容，可帮助读者掌握从用户角色划分到管理员功能实现的设计脉络；无论用于课程设计还是论文写作，都能获得可直接借鉴的系统框架、功能结构以及开发流程参考。

1. 为什么靠 Java 做物流管理系统：课程设计与交付里都被验证过的选择

以「基于Java的物流管理系统设计与实现」作为课程设计或毕业设计题目的人非常多，几乎每年 Java 课设答辩都能看到一批类似选题。原因不复杂：物流管理系统贯通订单、库存、运输、财务四条业务线，既能完整演练面向对象编程 Java 的封装继承多态，又逼着你处理并发扣库存、精确状态流转、报表导出这些会原样出现在 java 面试题里的硬问题。

对新手来说，在一套系统里把 CRUD 做干净、把事务边界划清楚，比背一百道 Java 八股文更有价值；对中小物流企业，单体 Java 应用也足够支撑日均十万单以内的分拨场景。下面这套落地方案我在课程设计与真实上线项目里反复调过，按这个顺序推进能省掉大量返工时间。

2. 系统架构与模块划分：单体 Java 怎么撑住完整物流链路

物流管理系统最容易犯的第一个错误，不是代码写得烂，而是模块边界模糊。订单、库存、运单、结算四套数据混在一张表里，需求一变更就是灾难。这一章先把架构定住，后面写代码才不会东改一块、西补一块。

2.1 技术栈选型：Spring Boot 2.7 + MyBatis 是最稳的默认答案

在课程设计和大部分中小物流项目的真实交付里，Spring Boot + MyBatis + MySQL 的组合是资料密度最高、踩坑成本最低的选择。Spring Boot 负责自动装配和依赖管理，MyBatis 把 SQL 写在 Mapper 里，订单状态、运单轨迹这类需要复杂 join 和条件更新的场景，一眼就能看出 SQL 在做什么。相比 JPA 的隐式查询，MyBatis 的显式 SQL 对新手更友好，也更容易做 SQL 优化；相比 SSM，Spring Boot 又省掉大量 XML 配置。

工程骨架我一般用 Spring Initializr 命令行拉，不用 IDE 向导。向导会默认勾选一堆用不到的依赖，生成的工程多出十几个无关 starter，对理解系统结构反而是干扰。

# 用 Spring Initializr 生成 Maven 工程骨架 curl https://start.spring.io/starter.zip \ -d dependencies=web,mysql,security,lombok,thymeleaf \ -d type=maven-project \ -d language=java \ -d bootVersion=2.7.18 \ -o logistics-system.zip unzip logistics-system.zip -d logistics-system

这段命令里，dependencies 中的 web、mysql、security、lombok、thymeleaf 分别对应控制器、数据库驱动、登录鉴权、代码精简和渲染模板。注意 Spring Initializr 官方依赖列表里没有 mybatis-spring-boot-starter，这一项要等骨架拉完再手工补进 pom.xml。bootVersion 固定用 2.7.18，这是 Spring Boot 2.x 的最后一个维护版本，javax 包名与绝大部分课程设计模板完全兼容；如果选 3.x，大量范例代码里的 javax.servlet 要整体改成 jakarta.servlet，迁移成本对新人并不友好。

mvn spring-boot:run

如果这一步报「mvn 不是内部或外部命令」，优先检查 JAVA_HOME 环境变量配置，而不是重装 Maven。这是项目里新人翻车频率最高的第一道坎。骨架能启动后，往 pom.xml 里追加 MyBatis 和连接池依赖：

<!-- pom.xml 中手动补充的 MyBatis 依赖 --> <dependency> <groupId>org.mybatis.spring.boot</groupId> <artifactId>mybatis-spring-boot-starter</artifactId> <version>2.3.2</version> </dependency> <dependency> <groupId>com.alibaba</groupId> <artifactId>druid-spring-boot-starter</artifactId> <version>1.2.20</version> </dependency>

mybatis-spring-boot-starter 2.3.2 与 Spring Boot 2.7 的兼容性经过充分验证，不要贪新用 3.x 的 mybatis starter，否则自动配置类扫描路径会出问题。druid 连接池的价值在于开发环境能看到实时 SQL 监控，对排查慢 SQL 比直接看日志高效得多。依赖配好后再把配置文件里的数据库连接改到本机 MySQL，创建好数据库 logistics，Spring Boot 启动日志出现「Started LogisticsApplication」才算环境闭环。

2.2 模块怎么拆：订单、仓储、运输、财务四条业务线互不越界

课程设计最常见的翻车点是包结构乱来：entity、service、controller 三个包打天下，业务类全堆在 service 里，一个类动辄两千行。物流系统业务域明确，我一般按业务线拆包，而不是按技术层次拆包。

com.example.logistics ├── controller # 接口层，只做参数校验与结果封装 ├── service # 业务层，事务边界与业务规则都在这里 │ ├── order # 订单域：下单、支付回调、取消、签收 │ ├── inventory # 库存域：入库、出库、盘点、冻结 │ ├── shipment # 运单域：揽收、在途、派送、异常 │ └── finance # 结算域：对账、账单、发票 ├── mapper # MyBatis 数据访问层 ├── entity # 与表结构一一对应的实体类 ├── dto # 接口出入参对象，不直接暴露实体 ├── enums # 订单状态、运单状态、费用类型等枚举 ├── task # 定时任务：超时取消、催派、对账补拉 └── config # 安全配置、拦截器、线程池、全局异常处理

这个结构的核心约束是：controller 不写业务判断，service 不直接操作 HttpServletRequest，mapper 不出现业务 if/else，entity 不允许直接作为接口返回值。坚持这三条，等到需要调整「订单取消后库存回滚」的逻辑时，代码位置是确定的，不用在一堆 Controller 里翻同样的实现。

调用链也要提前定好。我习惯让 service 之间的调用单向流动：orderService 可以调 inventoryService，但 inventoryService 不能反过来调 orderService。双向依赖在单体应用里短期不出事，一旦事务嵌套和循环调用出现，排查成本成倍上升。

2.3 下单动作的调用链：事务边界画在哪里最合理

订单创建是物流系统里最典型的事务场景，涉及校验客户、扣库存、建订单、建运单、记日志五件事。事务边界如果画在整个方法上，日志表也会被拖进同一事务，日志写入失败会导致下单失败，这是常见过度设计。合理做法是：库存扣减和订单创建必须同事务，日志写入单独提交，因为日志丢失可以容忍，库存和订单不一致不能容忍。

@Service public class OrderServiceImpl implements OrderService { private final InventoryService inventoryService; private final OrderMapper orderMapper; private final ShipmentMapper shipmentMapper; @Transactional(rollbackFor = Exception.class) public CreateOrderResult createOrder(CreateOrderRequest request) { // 幂等校验：同一 orderNo 重复提交直接返回原结果 Order existing = orderMapper.selectByOrderNo(request.getOrderNo()); if (existing != null) { return CreateOrderResult.of(existing); } // 扣减库存，乐观锁实现，失败抛 BizException inventoryService.deduct(request.getSkuId(), request.getCount()); // 写订单主表 Order order = Order.create(request); orderMapper.insert(order); // 写运单，初始状态为待揽收 Shipment shipment = Shipment.createPending(order.getId(), order.getOrderNo()); shipmentMapper.insert(shipment); return CreateOrderResult.of(order); } }

参数说明：orderNo 是幂等键，由前端生成，后端只认这个号；重复提交时直接返回已有订单，而不是再插一条。deduct 方法内部用的是 UPDATE 语句自带原子判断，影响行数为 0 时抛异常，让整个事务回滚。rollbackFor = Exception.class 是为了让 BizException 这类自定义运行时异常也能触发回滚，Spring 默认只回滚 RuntimeException，这点不写就是给自己埋雷。

事务边界为什么画在这一层而不是 mapper 层，原因在于 createOrder 里四步操作只要任何一步失败，前面已经扣掉的库存和插入的订单都要一起撤销。如果把事务画在 inventoryService.deduct 内部，库存扣减成功但订单插入失败时，库存就被白白扣掉了。课程设计里常见的「订单取消后库存没回来」，多半就是事务边界画错了地方。

3. 数据库设计：把订单状态主线理顺，其他模块都是附属

物流系统的数据库设计，核心不是表多，而是状态模型清晰。订单状态、运单状态、库存流水这三张表设计到位，后续所有查询和报表都会顺畅；这三张表关系乱，后面写再多缓存和索引也救不回来。

3.1 订单主表与运单表：字段和索引都为高频查询让路

订单主表有一个设计原则：业务订单号 order_no 必须与自增主键分离。自增 id 只做内部关联，对外暴露的订单号、运单号要能唯一识读，后续对账、支付回调、客户报障都只认业务号。

CREATE TABLE `orders` ( `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '内部主键', `order_no` VARCHAR(32) NOT NULL COMMENT '业务订单号', `customer_id` BIGINT NOT NULL COMMENT '客户ID', `receiver_name` VARCHAR(64) NOT NULL COMMENT '收件人', `receiver_phone` VARCHAR(20) NOT NULL COMMENT '收件电话', `receiver_address` VARCHAR(255) NOT NULL COMMENT '收件地址', `status` TINYINT NOT NULL DEFAULT 0 COMMENT '0待支付 1已支付 2已出库 3运输中 4已签收 5已取消 6异常', `pay_amount` DECIMAL(12,2) NOT NULL DEFAULT 0.00 COMMENT '支付金额', `remark` VARCHAR(255) DEFAULT NULL COMMENT '备注', `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, `updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, PRIMARY KEY (`id`), UNIQUE KEY `uk_order_no` (`order_no`), KEY `idx_status_created` (`status`, `created_at`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='订单主表';

字段里值得解释的有三处。status 用 TINYINT 而不是 VARCHAR，是为了 Java 侧能用一个枚举类精确映射，避免代码里到处写魔法字符串，也为状态机校验提供明确的类型边界。idx_status_created 是复合索引不是单列索引，因为管理后台最常见的查询是「按状态筛订单、按创建时间倒序」，单列索引在排序阶段会退化成 filesort。order_no 上的唯一索引是幂等的最后一道数据库防线，即便应用层漏了查重，数据库也会把重复单号挡下来。

运单表与订单表是一对一关系，但必须单独建表。订单状态和运单状态的声明周期不同：订单可以已支付等待出库，此时运单不存在；订单已签收后，运单还有可能进入异常退回流程。

CREATE TABLE `shipment` ( `id` BIGINT NOT NULL AUTO_INCREMENT, `shipment_no` VARCHAR(32) NOT NULL COMMENT '运单号', `order_id` BIGINT NOT NULL COMMENT '订单内部主键', `status` TINYINT NOT NULL DEFAULT 0 COMMENT '0待揽收 1运输中 2派送中 3已签收 4异常', `carrier_name` VARCHAR(64) DEFAULT NULL COMMENT '承运商', `tracking_no` VARCHAR(64) DEFAULT NULL COMMENT '承运商单号', `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, `updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, PRIMARY KEY (`id`), UNIQUE KEY `uk_shipment_no` (`shipment_no`), KEY `idx_order_id` (`order_id`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='运单表';

运单表的 idx_order_id 是低频索引，因为在订单详情页通过 order_id 反查运单是最高频访问路径。承运商信息不拆到第三张表，是因为中小物流系统的承运商往往就是几个固定物流公司，冗余字段比反复 join 更划算。真要做到几十家承运商动态接入时再来拆表，前期不需要为这个扩展性买单。

3.2 Java 枚举与订单状态机：非法流转在编译期就被拦住

订单状态流转是物流系统里最容易被轻视的环节。很多课程设计在每个 Service 方法里 if (order.getStatus() == 0) 判断，状态流转规则散落在十几个方法里。更稳的写法是用 Java 枚举把状态和流转规则收敛到一处。

public enum OrderStatus { PENDING_PAYMENT(0, "待支付"), PAID(1, "已支付"), SHIPPED(2, "已出库"), IN_TRANSIT(3, "运输中"), DELIVERED(4, "已签收"), CANCELED(5, "已取消"), EXCEPTION(6, "异常"); private final int code; private final String desc; OrderStatus(int code, String desc) { this.code = code; this.desc = desc; } public int getCode() { return code; } public String getDesc() { return desc; } public static OrderStatus fromCode(int code) { for (OrderStatus status : values()) { if (status.code == code) return status; } throw new IllegalArgumentException("非法状态码: " + code); } }

枚举类本身不难，难在状态流转的校验规则。我通常独立一个 StatusFlow 类来定义允许流转关系，把校验方法放在里面：

public final class OrderStatusFlow { private static final Map<OrderStatus, Set<OrderStatus>> ALLOWED = new EnumMap<>(OrderStatus.class); static { ALLOWED.put(OrderStatus.PENDING_PAYMENT, Set.of(OrderStatus.PAID, OrderStatus.CANCELED)); ALLOWED.put(OrderStatus.PAID, Set.of(OrderStatus.SHIPPED, OrderStatus.CANCELED)); ALLOWED.put(OrderStatus.SHIPPED, Set.of(OrderStatus.IN_TRANSIT, OrderStatus.EXCEPTION)); ALLOWED.put(OrderStatus.IN_TRANSIT, Set.of(OrderStatus.DELIVERED, OrderStatus.EXCEPTION)); ALLOWED.put(OrderStatus.DELIVERED, Set.of(OrderStatus.EXCEPTION)); ALLOWED.put(OrderStatus.EXCEPTION, Set.of(OrderStatus.CANCELED)); ALLOWED.put(OrderStatus.CANCELED, Set.of()); } public static void check(OrderStatus from, OrderStatus to) { if (!ALLOWED.getOrDefault(from, Set.of()).contains(to)) { throw new IllegalStateException( String.format("非法状态流转: %s -> %s", from.getDesc(), to.getDesc())); } } }

这套写法的价值在于：当需求方说「取消订单必须从待支付状态才能发起」时，只需要改 ALLOWED 这 7 行映射，不用去所有写状态的地方翻代码。注意 ALLOWED 用了 EnumMap，遍历效率比 HashMap 更高；Set.of 在 Java 9 以后可用，如果你的课程设计环境是 JDK 8，要换成 Collections.unmodifiableSet。

下面把订单允许的流转关系列出来，编码时对应到 Service 方法的动作上：

状态机校验的调用点放在 Service 层，而不是 Controller。Controller 拿到的是 DTO 里的目标状态，Service 才能拿到数据库里的当前状态，只有 Service 层能完成「当前状态到目标状态」的完整判断。

3.3 库存扣减与并发控制：乐观锁加唯一约束双保险

库存扣减是物流系统数据一致性最容易出问题的地方。用户下单扣库存、取消订单回补库存，两件事同时发生时，如果代码里没有并发控制，库存会出现负数或凭空多出来。推荐做法是乐观锁加条件更新，SQL 里同时带版本号和库存余量的判断：

UPDATE inventory SET stock = stock - #{count}, version = version + 1 WHERE sku_id = #{skuId} AND stock >= #{count} AND version = #{version}

这段 SQL 的三重保障是：stock >= #{count} 防止扣成负数，version = #{version} 防止丢失更新，version + 1 让下一次更新必须基于最新版本。返回的影响行数为 0 时，说明要么库存不足、要么版本冲突，Service 层判断后抛业务异常，由上层事务统一回滚。

乐观锁的取舍要讲清楚：它适合冲突概率不高的普通订单场景，单量不大时基本一次成功；碰到秒杀、大促这类高并发场景，乐观锁重试次数会急剧上升，这时候才需要升级为分布式锁或 Redis 预扣方案。物流系统的常态是分散下单，乐观锁足够，不要一上来就上 Redisson，复杂度换不来实际收益。

库存流水表还要单独建一张，记录每次扣减和回补操作。流水不参与业务判断，只在排查数据不一致时作为审计依据。这也是常被忽略的点：没有流水表，库存对不上账时连从哪一步开始错的都查不到。

3.4 列表查询性能：索引顺序和深分页才是大头

订单列表页是管理后台最常访问的页面，状态筛选加时间倒序加翻页。索引设计对的，百万级数据也能稳定在百毫秒内；索引设计错的，几万条数据就会把数据库 CPU 打满。常见误区是以为在 status 和 created_at 上分别建两个单列索引就够了，实际上 MySQL 一次查询通常只选择一个索引，另一个字段在回表后做排序，数据量大时就出现 filesort。正确做法是建联合索引 (status, created_at)，让索引同时满足筛选和排序。

深分页是另一个坑。LIMIT 900000, 20 这种写法，MySQL 要先扫 90 万行再丢弃前 90 万行，查询时间随页码线性增长。物流后台的普通查询，我一般限制最大翻页深度，超过 100 页强制走时间范围筛选。如果确实需要深翻页，改成基于上一页最后一条记录 id 的游标分页：

-- 基于游标的分页，替代 LIMIT 大偏移 SELECT id, order_no, status, created_at FROM orders WHERE status = 2 AND id < #{lastId} ORDER BY id DESC LIMIT 20;

这里的排序键是 id 而不是 created_at，因为 id 单调递增且天然有索引，游标分页的边界判断更可靠。若业务上必须按创建时间排序，就在 created_at 上也建索引，并把游标字段换成 created_at 加 id 的组合条件。这个细节在 java 面试里经常被追问，数据库原理和项目实践对不上时最容易露馅。

4. 核心功能实现：下单、轨迹、报表三条线的落地代码

架构和表结构定了之后，真正花时间的其实是三块业务编码：订单创建链路、物流轨迹记录、报表导出。这三块写扎实了，物流系统的骨架基本立住。

4.1 订单创建服务：幂等键、冻结库存、事务边界一次讲清

createOrder 的骨架在前面讲过，这里把幂等和阶段式库存的细节补齐。幂等判断不能只在内存里做，因为服务重启后内存状态会丢，所以幂等键要落到数据库。

@Transactional(rollbackFor = Exception.class) public CreateOrderResult createOrder(CreateOrderRequest request) { String orderNo = request.getOrderNo(); Order existing = orderMapper.selectByOrderNo(orderNo); if (existing != null) { return CreateOrderResult.of(existing); } // 冻结库存后再落订单，避免极端并发下的重复扣减 int rows = inventoryMapper.freezeStock(request.getSkuId(), request.getCount()); if (rows == 0) { throw new BizException("库存不足"); } Order order = new Order(); order.setOrderNo(orderNo); order.setCustomerId(request.getCustomerId()); order.setStatus(OrderStatus.PENDING_PAYMENT.getCode()); order.setPayAmount(request.getPayAmount()); orderMapper.insert(order); return CreateOrderResult.of(order); }

说明：这里的 freezeStock 语义和直接扣库存不同。冻结表示预留但未实际扣减，支付成功后才真正扣减；用户超时未支付，定时任务再执行解冻回补。这套「冻结-扣减-解冻」三段式比直接扣库存更符合物流订单的支付流程，避免用户下单未支付时库存被占死。

事务边界要解释的是为什么日志表不放进来。日志写入如果和订单创建同事务，日志表磁盘满了会导致正常下单失败。物流系统的操作日志允许丢失，订单数据不允许错乱，一致性级别不同，不该共用同一个事务。

4.2 物流轨迹记录：按时间线追加，不按状态覆盖

物流轨迹在数据模型上是追加表，每次揽收、转运、派送都插入一条流水，而不是更新一条「最新状态」。这样客户看到的轨迹是完整时间线，运营排查问题也能还原包裹经过的每个节点。

public void recordTrace(Long shipmentId, String node, String description) { ShipmentTrace trace = new ShipmentTrace(); trace.setShipmentId(shipmentId); trace.setNode(node); trace.setDescription(description); trace.setCreatedAt(LocalDateTime.now()); shipmentTraceMapper.insert(trace); // 同步更新运单主表状态 shipmentMapper.updateStatus(shipmentId, ShipmentStatus.fromNode(node).getCode()); }

这里的同步更新运单主表状态是关键。轨迹表保存历史，运单表只保存当前状态，二者通过 shipmentId 关联。如果只写轨迹表不更主表，每次查询运单状态都要去扫轨迹表最后一条，索引和性能都会出问题；如果只更主表不写轨迹，客户端的物流时间线就断了。两个写入在同一事务里，要么都成功，要么都回滚。

节点字段的取值我习惯固定为 PICKED_UP、IN_TRANSIT、OUT_FOR_DELIVERY、DELIVERED、EXCEPTION 五个枚举，而不是让业务方自由填中文。节点不定死，后面做轨迹趋势分析、时效统计时，数据根本无法聚合。

4.3 用 Java POI 生成 Word 报表：图表先渲染成图片再嵌入

物流系统里几乎都有一个「导出月度报表」的需求，常见格式是 Word。很多人问 java poi word 能不能生成图表，答案是可以但不直接：POI 的 XWPF 组件只能写 Word 文档结构和表格，不能像 Excel 的图表 API 那样内置原生图表。实际做法是把图表先渲染成 PNG，再插入到 Word 文档中。

public void exportMonthlyReport(List<DeliveryStat> stats, String outputPath) throws Exception { XWPFDocument document = new XWPFDocument(); // 标题 XWPFParagraph title = document.createParagraph(); title.setAlignment(ParagraphAlignment.CENTER); XWPFRun titleRun = title.createRun(); titleRun.setText("物流月度时效报表"); titleRun.setBold(true); titleRun.setFontSize(18); // 先用 JFreeChart 渲染折线图 JFreeChart chart = ChartFactory.createLineChart( "近30天日均妥投量", "日期", "件数", createDataset(stats), PlotOrientation.VERTICAL, true, true, false); BufferedImage chartImage = chart.createBufferedImage(600, 320); File imageFile = new File(System.getProperty("java.io.tmpdir"), "trend.png"); ImageIO.write(chartImage, "png", imageFile); // 把图片嵌入 Word XWPFParagraph imageParagraph = document.createParagraph(); XWPFRun imageRun = imageParagraph.createRun(); try (FileInputStream fis = new FileInputStream(imageFile)) { imageRun.addPicture(fis, XWPFDocument.PICTURE_TYPE_PNG, "trend.png", Units.toEMU(520), Units.toEMU(280)); } // 明细表格 XWPFTable table = document.createTable(stats.size() + 1, 4); String[] headers = {"日期", "下单量", "妥投量", "妥投率"}; for (int i = 0; i < headers.length; i++) { table.getRow(0).getCell(i).setText(headers[i]); } for (int i = 0; i < stats.size(); i++) { DeliveryStat stat = stats.get(i); XWPFTableRow row = table.getRow(i + 1); row.getCell(0).setText(stat.getDate()); row.getCell(1).setText(String.valueOf(stat.getOrderCount())); row.getCell(2).setText(String.valueOf(stat.getDeliveredCount())); row.getCell(3).setText(String.format("%.2f%%", stat.getDeliveryRate())); } try (FileOutputStream fos = new FileOutputStream(outputPath)) { document.write(fos); } document.close(); }

参数说明：addPicture 方法里的 Units.toEMU(520) 是把像素换算成 Word 内部的 EMU 单位，520 对应约 13 厘米宽度，超过这个宽度文档排版会被撑破，A4 纸正文宽度最长建议不超过 560 像素。表格用 document.createTable(rows, cols) 创建后，getRow(0).getCell(i).setText 是稳定写入中文表头的方式；不要先调 getParagraph 再往里塞 Run，低层 API 容易抛空指针。

导出大文档时的内存问题也要提前规避。XWPFDocument 是整文档驻留内存的模型，导出 2000 行以上的表格建议分页生成多个文件。课程设计的数据量通常不大，XWPF 就够；线上报表动不动几万行时，XWPF 会直接 OOM。

报表里的中文乱码则几乎都出在字体上。POI 对中文字体的处理依赖运行环境的字体库，Linux 服务器上没装中文字体，生成的就是方块。解决方法是两点并用：渲染图表时把默认字体改成「Microsoft YaHei」或「SimSun」，服务器安装对应的中文字体包。这不是代码 bug，是环境问题，排查时别只盯着代码。

5. 避坑排查：物流系统交付前最容易翻车的 5 个场景

这一章把我自己做物流系统时踩过、以及帮别人排查过的五个高频问题记下来。每条都按现象、原因、解决三步写，可以直接对照自查。

5.1 并发扣库存出现负数

现象：大促期间的订单表里，同一 SKU 的库存余量变成负值，但订单状态全是「已支付」。

原因：库存扣减 SQL 只写了 UPDATE inventory SET stock = stock - #{count}，没有 AND stock >= #{count} 条件，也没有版本号。两个请求同时读到库存为 5，同时执行扣减，后一个更新把前一个的结果覆盖，库存变成 2 而不是 0。

解决：把扣减 SQL 改成带乐观锁和余量判断的原子更新，影响行数为 0 时抛库存不足异常。注意 Service 层拿到 0 行时要抛业务异常而不是静默返回，否则事务不会回滚，订单表写入也会残留。改完后写一段并发脚本模拟 20 个线程同时下单同一个 SKU，确认库存最终不为负。

5.2 订单状态回退，已签收变成已支付

现象：用户端显示订单已签收，后台刷新后状态又变回「已支付」，日志里出现两次状态更新记录。

原因：状态更新 SQL 用了 UPDATE orders SET status = #{target} WHERE id = #{id}，没有带上「当前状态必须等于前置状态」的条件。延迟到达的历史请求或补偿任务把新状态覆盖回去了。

解决：所有状态更新都改成 WHERE id = #{id} AND status = #{currentStatus}，并在 Service 层先查当前状态，调用 OrderStatusFlow.check 校验允许流转再执行更新。影响行数为 0 时说明状态已被其他请求抢先变更，直接抛并发冲突异常，不要重试。

5.3 POI 生成的 Word 报表打开乱码或文件损坏

现象：本地生成的 docx 用 WPS 打开正常，放到服务器上生成后要么中文乱码，要么文件损坏。

原因：乱码和损坏是两回事。乱码是 Linux 服务器缺中文字体或图形渲染时字体名不合法；文件损坏通常是 document 没有 close，或输出流没 flush。

解决：渲染图表前在代码里指定字体名，确保服务器安装了中文字体；导出方法用 try-with-resources 保证 document 一定关闭。另外 POI 生成 docx 时不要用 FileWriter 写二进制文件，必须用 FileOutputStream，字符流会把字节写坏。这个坑很隐蔽，Java 基础概念不清晰时特别容易踩。

5.4 定时任务重复执行，同一批运单被处理两次

现象：凌晨 2 点的催派任务执行后，同一批运单收到两条重复的短信通知。

原因：课程设计阶段只有一个实例运行，定时任务看似没问题。部署到多节点环境后，或者开发时手动重启服务，@Scheduled 注解在每个实例上都会执行一遍，任务没有全局互斥。

解决：引入 Redisson 的分布式锁，任务方法开头 tryLock，拿不到锁就跳过本次执行；或者退一步，在数据库用 task_lock 表以任务名做唯一键，插入成功才能继续执行。后者实现简单，适合课程设计演示，但锁的过期时间要大于任务最长执行时间，否则任务没跑完锁就释放了。

5.5 订单列表深翻页越来越慢，最后直接卡死

现象：订单管理页翻到几十页后，接口响应从几百毫秒涨到几秒，数据库 CPU 持续飙高。

原因：LIMIT offset, size 的深分页需要扫描并丢弃大量行。offset 是 900000 时，MySQL 要读 90 万行，即使有索引也避免不了排序和回表消耗。

解决：最优解是限制翻页深度，后台超过 100 页强制走时间范围查询；技术上的替代是改游标分页，用上一页最后一条 id 作为边界条件，避免大偏移。注意游标分页对排序字段有要求，无法稳定排序的页面不适合这个方案，只能退回时间范围筛选。

6. 交付前这样验证：状态流转用例集与并发测试把问题提前暴露

系统写完到交付之间，最大的风险不是功能缺失，而是状态流转在组合场景下失控。我养成的习惯是维护一套状态流转用例集，每次需求变更后回归跑一遍。

6.1 维护一套状态流转回归用例

状态流转用例的核心是覆盖每条合法流转和至少一条非法流转。合法流转要验证「待支付 - 已支付 - 已出库 - 运输中 - 已签收」这条主链；非法流转要验证「已取消 - 已支付」「已签收 - 运输中」这些操作会被 OrderStatusFlow.check 拒绝。用例集可以用 JUnit 参数化测试写，一组参数对应一条流转路径，跑完就知道状态机有没有被新需求改坏。

6.2 并发测试的检查清单

并发验证安排在交付前一天做。方法很简单，开一个线程池模拟 100 个用户同时操作同一 SKU 的下单，跑完后用 SQL 检查库存是否为预期值、有没有负数、订单号有没有重复。这一步能暴露乐观锁、幂等键、事务边界的所有问题。我在评审里见过太多系统，演示时功能全对，一上并发测试就现原形。

数据库备份和测试数据脱敏也要顺手做掉。物流系统里客户手机号、收件地址都是敏感字段，测试环境尽量用生成器造数据，不要直接拿生产数据导入。如果你时间只够做一件事，那就把状态机用例集写好。这套用例相当于整个系统的后悔药——需求方改口说「签收后应该允许退回」，改完 ALLOWED 映射后跑一遍用例，立刻知道哪些调用链受影响，而不是靠肉眼翻代码。

我从第一次做物流系统到现在，最大的变化是不再把「能跑通」当作完成标准。能跑通只是起点，状态不乱、库存不差、重复操作不产生脏数据，这些看不见的部分才是系统真正的价值。希望你也能在自己的项目里用上这套验证思路。希望帮到你。

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