校园快递点排队一小时？我直接用Spring Boot撸了一套智能物流管理系统

每年九月份开学季，我站在学校快递站点门口，看着几百号人挤在三个窗口前等着报取件码，旁边还有一堆因为包裹找不到在跟快递员吵架的同学，那场面真的让人头大。校园物流这个场景太特殊了——单量高度集中、身份确认麻烦、包裹滞留率高，市面上的商业快递管理系统又大又重，根本不是给校园这种微型场景用的。

所以我自己动手设计了一套基于Spring Boot的校园智能物流管理系统。它解决的问题非常聚焦：让快递员入库效率翻倍，让学生不用排队就能查到包裹位置和取件码，让站点管理员能实时掌握滞留件、入库量这些核心数据。整个系统采用Spring Boot + Vue前后端分离架构，覆盖了快递入库、自动生成取件码、短信/微信通知、一键取件、滞留预警、数据看板这些完整闭环。

如果你正在做Java后端开发、准备毕业设计，或者想搞明白一个真实业务系统从零到上线要经历哪些坑，这篇文章值得认真看完。我会把整个系统的业务设计、表结构、核心代码逻辑、权限方案以及我在实际开发中踩过的各种坑全部拆开讲一遍，有些坑你可能在网上搜半天都搜不到答案。

1. 先从业务说起：校园站点和商业快递系统缺的是什么

很多同学一上来就问"用哪个框架""用MySQL还是Redis"，但我觉得做任何一个系统，第一件事永远是搞明白业务。校园物流站点跟顺丰、菜鸟这种商业体系完全不是一回事，需求也不一样。

1.1 校园场景的三个特殊性和一个核心矛盾

我在做需求分析时，梳理出了校园快递站的三个显著特点。

第一个特点是时间波峰极其明显。平时一天可能就几十个件，但赶上双十一、开学季，一天上千个包裹涌进来。这意味着系统必须能顶住短时高并发写入。我在设计时特意把快递入库接口做成批量操作，允许快递员一次导入几十个单号，避免循环单条插入。

第二个特点是取件人身份确认难。校园里学生多、流动性大，有的用手机尾号，有的用身份证后四位，有的压根不接电话。商业系统有实名认证、人脸识别那一套，校园里搞这么重没意义。我最终采用"取件码 + 手机尾号"双重校验，兼顾便捷和安全。

第三个特点是包裹滞留率偏高。很多学生出差、实习、上课，包裹放站点三天都没人取。这就需要一个定时任务每天扫描滞留包裹，自动发提醒消息。

核心矛盾则体现在：高峰期站点工作人员有限，但取件需求密集爆发。所以系统设计的主线非常明确——怎么用最少的人工干预，完成快递从入库到签收的整个闭环。

1.2 角色梳理与业务闭环

我把系统划分为三类角色，没有做超级复杂的RBAC权限模型，够用就行：

快递员（投递端）：负责批量录入包裹信息，系统自动生成取件码，打印或拍照张贴。
学生用户（取件端）：收到通知 → 凭取件码到站点 → 在自助终端或手机端操作取件。
站点管理员（管理端）：管理货架/站点、查看入库数据、处理滞留件、管理用户。

业务闭环是这样的：快递员送件到站 → 录入包裹 → 系统生成取件码 → 触发通知 → 学生前来取件 → 核对取件码 → 签收归档。整个流程里，唯一的线下人工动作就是最后"核对取件码"这一步，其余全在线上完成。

提示：这里的业务闭环是整个系统的核心，后面的数据库设计和接口设计全部围绕它展开。不要在需求还没理清楚时就开始写代码，否则后续改起来会非常痛苦。

1.3 需求取舍：哪些先砍掉

我见过很多项目死在不切实际的需求上。这套系统我主动砍掉了几个看起来很炫但实际用不上的功能——比如实时视频监控接入、智能柜硬件对接、在线支付。原因很简单：校园站点目前的核心痛点是"入库登记慢"和"找件难"，不是硬件自动化。如果一开始就把智能柜硬件对接加进来，光调试硬件协议就能拖垮整个项目周期。合理划分版本边界，把核心链路做扎实，是项目能落地的关键。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 技术选型：这套组合不是随便拍的

技术选型可能是被问得最多的问题。我的选择是：Spring Boot 2.7.18 + MyBatis Plus 3.5.x + MySQL 8.0 + Redis + Vue 3 + Element Plus，部署在Docker上。下面逐个说理由。

2.1 为什么卡在Spring Boot 2.7.18而不是直接上3.x

Spring Boot 3.x 已经发布很久了，但我最终选择了2.7.18，这是2.x的最后一个版本。核心原因是生态兼容性。

Spring Boot 3.x 基于Jakarta EE规范，很多老牌库的兼容版本更新滞后。像一些企业级工作流引擎、特定的Netty版本、部分生成静态代码的工具，在Spring Boot 3.x下都要额外折腾。对于校园物流这种以稳定为主的项目，没必要为新技术买单。我选2.7.18，它支持JDK 8和17，兼容性问题少，社区资料最多，遇到问题随便一搜就有答案。

如果你遇到"springboot版本太高"导致某些依赖冲突，最稳妥的办法不是一直升级版本，而是明确项目需要什么JDK版本和什么第三方库，然后反过来锁定Spring Boot版本。版本这东西，能跑稳定就是好版本。

2.2 持久层为什么要用MyBatis Plus

持久层我选了MyBatis Plus而不是JPA或者原生MyBatis。原因有三个：

第一，单表CRUD不用写XML。MyBatis Plus内置了BaseMapper，像根据ID查询、分页查询、条件构造器这些常用操作都封装好了，开发效率提升非常明显。物流系统里大部分操作都是单表操作，用起来特别顺手。

第二，代码生成器能直接生成实体类、Mapper、Service、Controller。对于快递单、用户、通知记录这种标准表结构，生成完再手动改业务逻辑，比全手写快一倍。

第三，MyBatis Plus的LambdaQueryWrapper写起来可读性好。比如查询今天入库的快递单：

java复制LambdaQueryWrapper<ExpressInfo> wrapper = new LambdaQueryWrapper<>();
wrapper.eq(ExpressInfo::getSiteId, siteId)
       .ge(ExpressInfo::getCreateTime, LocalDate.now().atStartOfDay())
       .orderByDesc(ExpressInfo::getCreateTime);
List<ExpressInfo> list = expressInfoMapper.selectList(wrapper);

这种写法在代码审查时别人一眼就能看懂在查什么，比写XML拼SQL更好维护。

2.3 前端和后端的工程结构设计

前端选了Vue 3 + Vite + Element Plus，通过Axios调用后端接口。工程上采用前后端完全分离的模式：

code复制express-campus
├── express-server         # Spring Boot后端
│   ├── src/main/java
│   │   └── com/campus/express
│   │       ├── controller   # 接口层
│   │       ├── service      # 业务逻辑层
│   │       ├── mapper       # 数据访问层
│   │       ├── entity       # 实体类
│   │       ├── common       # 通用返回、异常、工具类
│   │       └── config       # 配置类（拦截器、WebMvc等）
│   └── src/main/resources
│       ├── mapper           # MyBatis XML文件
│       └── application.yml
└── express-web            # Vue3前端
    ├── src
    │   ├── api             # 接口封装
    │   ├── views           # 页面组件
    │   ├── router          # 路由配置
    │   └── store           # 状态管理（Pinia）
    └── vite.config.js

这种结构的最大好处是接口边界清晰，前后端可以并行开发。我负责后端接口定义，前端同学可以拿Mock数据先开发页面，联调时再切换到真实接口。

2.4 自动装配机制：为什么Spring Boot能"自动配置"

很多初学者用Spring Boot时会有个疑惑：为什么引入一个依赖，配置一堆参数就能直接用了？其实这背后就是Spring Boot的核心机制——自动装配。

简单来说，Spring Boot在启动时会扫描META-INF/spring.factories文件，加载大量XxxAutoConfiguration类。这些自动配置类上有一个关键注解：@ConditionalOnMissingBean、@ConditionalOnProperty等条件注解。比如DataSourceAutoConfiguration会检查classpath下有没有DataSource类，有的话就自动创建一个数据源Bean。你在application.yml里写的spring.datasource.url这些配置，会被绑定到DataSourceProperties上，然后注入到自动配置类里。

理解这个机制对排查问题很有帮助。比如你发现某个配置不生效，大概率是条件注解没满足，或者自定义的Bean把自动配置的Bean覆盖了。我当时遇到过一次循环依赖的问题，就是因为在自定义配置类里手动创建了某个Bean，而它又依赖另一个被自动配置的Bean，导致初始化顺序冲突。

3. 数据库设计：一个物流系统的地基这样打

数据库设计我花了整整两天，因为表结构一旦定下来，后续改动的成本非常高。快递单、站点、用户、通知记录这几张核心表，我在这里直接给出设计思路，可以直接借鉴。

3.1 核心表结构设计

**快递单表（express_info）**是系统的核心表，字段设计如下：

sql复制CREATE TABLE `express_info` (
  `id` bigint(20) NOT NULL AUTO_INCREMENT COMMENT '主键ID',
  `express_no` varchar(64) NOT NULL COMMENT '快递单号',
  `company_code` varchar(32) DEFAULT NULL COMMENT '快递公司编码（sf、yt、zt等）',
  `site_id` bigint(20) NOT NULL COMMENT '所属站点ID',
  `receiver_name` varchar(64) DEFAULT NULL COMMENT '收件人姓名',
  `receiver_phone` varchar(32) NOT NULL COMMENT '收件人手机号',
  `receiver_student_no` varchar(32) DEFAULT NULL COMMENT '收件人学号/工号',
  `pickup_code` varchar(16) NOT NULL COMMENT '取件码',
  `shelf_no` varchar(32) DEFAULT NULL COMMENT '货架编号',
  `status` tinyint(4) NOT NULL DEFAULT '0' COMMENT '状态：0-待入库 1-已入库 2-已签收 3-滞留 4-异常',
  `warehouse_time` datetime DEFAULT NULL COMMENT '入库时间',
  `sign_time` datetime DEFAULT NULL COMMENT '签收时间',
  `create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `update_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_express_no` (`express_no`),
  KEY `idx_receiver_phone` (`receiver_phone`),
  KEY `idx_status` (`status`),
  KEY `idx_site_id` (`site_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='快递单信息表';

几个字段的设计细节值得说明：

express_no 加上唯一索引，防止同一单号重复入库。
receiver_phone 建普通索引，因为学生查询自己的包裹时最常用手机号匹配。
status 是状态机设计，后续所有业务逻辑都围绕这个状态流转。

站点表（express_site）：

sql复制CREATE TABLE `express_site` (
  `id` bigint(20) NOT NULL AUTO_INCREMENT,
  `site_name` varchar(128) NOT NULL COMMENT '站点名称',
  `site_address` varchar(255) DEFAULT NULL COMMENT '站点地址',
  `manager_id` bigint(20) DEFAULT NULL COMMENT '管理员用户ID',
  `status` tinyint(4) DEFAULT '1' COMMENT '状态：1-营业中 0-已关闭',
  `create_time` datetime DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='快递站点表';

通知记录表（notice_record）：

sql复制CREATE TABLE `notice_record` (
  `id` bigint(20) NOT NULL AUTO_INCREMENT,
  `express_id` bigint(20) NOT NULL COMMENT '快递单ID',
  `receiver_phone` varchar(32) NOT NULL COMMENT '接收方手机号',
  `notice_type` tinyint(4) DEFAULT '0' COMMENT '通知类型：0-入库通知 1-滞留提醒 2-签收确认',
  `content` varchar(500) DEFAULT NULL COMMENT '通知内容',
  `status` tinyint(4) DEFAULT '0' COMMENT '发送状态：0-待发送 1-已发送 2-失败',
  `create_time` datetime DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`),
  KEY `idx_express_id` (`express_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='通知记录表';

3.2 状态机设计：一个包裹的完整生命旅程

快递状态流转是整个系统最核心的业务规则。我用状态机来定义，避免业务逻辑散落在各个Service方法里：

code复制状态0（待入库） → 状态1（已入库） → 状态2（已签收）
                          ↓
                      状态3（滞留）→ 状态2（已签收）
                          ↓
                      状态4（异常/退回）

快递员创建快递单记录后，状态默认为0（待入库），等包裹实际放到货架上后，通过"确认入库"操作变成1。
已入库的包裹超过48小时未取件，定时任务自动将其标记为状态3（滞留），并发送提醒。
用户取件时，状态从1或3变为2（已签收），写入签收时间。
如果包裹破损、地址错误等原因无法投递，管理员将其标记为4（异常）。

状态流转这个设计建议用状态机模式来管理，不要在每个接口里随便改状态。我实现了一个简单的状态校验器：

java复制@Component
public class ExpressStatusValidator {

    private static final Map<Integer, List<Integer>> TRANSITION_MAP = new HashMap<>();

    static {
        // 定义每个状态允许流转到哪些状态
        TRANSITION_MAP.put(0, Arrays.asList(1, 4));
        TRANSITION_MAP.put(1, Arrays.asList(2, 3, 4));
        TRANSITION_MAP.put(3, Arrays.asList(2, 4));
        TRANSITION_MAP.put(2, Collections.emptyList());
        TRANSITION_MAP.put(4, Collections.emptyList());
    }

    public void validate(int fromStatus, int toStatus) {
        List<Integer> allowed = TRANSITION_MAP.get(fromStatus);
        if (allowed == null || !allowed.contains(toStatus)) {
            throw new BizException("非法状态流转：" + fromStatus + " -> " + toStatus);
        }
    }
}

这套机制的好处是，哪怕未来增加新的状态（比如"已出库待配送"），只需要改这个Map，不用满世界找setStatus调用点。

3.3 取件码生成方案：安全与效率如何兼顾

取件码是整个系统的关键凭证。我采用的方案是"站点编号 + 4位数字随机码"，比如 A-1328。取件码生成后存入pickup_code字段，并设置唯一索引防止重复。

生成逻辑使用了Redis的INCR命令保证同站点下的取件码不冲突：

java复制public String generatePickupCode(Long siteId) {
    // 以站点ID为维度自增，解决多站点并发生成取件码冲突问题
    Long seq = redisTemplate.opsForValue().increment("pickup:seq:" + siteId, 1);
    int code = (int)(seq % 10000);
    return String.format("%c-%04d", (char)('A' + siteId % 26), code);
}

这里有一个需要注意的点：seq % 10000在超过9999后会重复。我的处理方式是每次生成前检查该取件码在本站点是否已存在，如果存在就继续递增直到不冲突。理论上10000个周期内不会冲突，但严谨起见还是加了一层检查。

4. 核心模块实现：从快递入库到自动通知的完整链路

这一章直接上核心模块的具体实现思路，从快递员端到学生端到管理端，把每个环节的关键代码和设计逻辑讲透。

4.1 快递员端批量入库与缓存加速

快递员入库是最频繁的操作，高峰期可能一次性来几十个包裹。如果逐个插入数据库，性能一定扛不住。我设计了批量入库接口，一次请求可以携带最多100条快递单号。

接口设计示例：

java复制@PostMapping("/express/batch-import")
public R<?> batchImport(@RequestBody @Valid BatchImportRequest request) {
    Long siteId = request.getSiteId();
    List<String> expressNos = request.getExpressNos();
    List<ExpressInfo> list = expressNos.stream().map(no -> {
        ExpressInfo info = new ExpressInfo();
        info.setExpressNo(no);
        info.setSiteId(siteId);
        info.setStatus(0); // 待入库
        // 生成取件码
        info.setPickupCode(pickupCodeService.generate(siteId));
        return info;
    }).collect(Collectors.toList());
    expressInfoService.saveBatch(list, 50); // MyBatis Plus批量插入，每50条一个批次
    return R.ok(list.size());
}

这里有个细节：快递单号虽然设置了唯一索引，但如果重复导入，保存时会导致DuplicateKeyException。我的处理方案是先按单号批量查询已存在的记录，过滤后再插入，这样能避免报错中断整个批次。用selectBatchIds或者LambdaQueryWrapper.in实现。

入库成功后，后台会发送通知。如果对时效要求高，可以用消息队列异步处理，但对于校园这种量级，直接用Spring的@Async异步方法就够了，不需要引入Kafka或者RabbitMQ增加系统复杂度。

4.2 学生端：一键查询与取件闭环

学生端的核心需求非常朴素：输入手机号或单号，就能看到自己在哪个站点、哪个货架、取件码是多少、包裹是什么状态。

查询接口实现：

java复制@GetMapping("/express/my")
public R<?> myExpresses(@RequestParam String phone) {
    LambdaQueryWrapper<ExpressInfo> wrapper = new LambdaQueryWrapper<>();
    wrapper.eq(ExpressInfo::getReceiverPhone, phone)
           .in(ExpressInfo::getStatus, Arrays.asList(0, 1, 3)) // 未签收的包裹
           .orderByDesc(ExpressInfo::getCreateTime);
    List<ExpressInfo> list = expressInfoMapper.selectList(wrapper);
    // 隐私处理：手机号脱敏
    list.forEach(item -> item.setReceiverPhone(desensitizePhone(item.getReceiverPhone())));
    return R.ok(list);
}

取件操作是另一个核心接口。学生在自助终端或手机上点击"确认取件"，后端需要校验取件码是否匹配，然后完成状态流转：

java复制@PostMapping("/express/pickup")
public R<?> pickup(@RequestBody PickupRequest request) {
    // 1. 根据取件码和手机号校验
    LambdaQueryWrapper<ExpressInfo> wrapper = new LambdaQueryWrapper<>();
    wrapper.eq(ExpressInfo::getPickupCode, request.getPickupCode())
           .eq(ExpressInfo::getReceiverPhone, request.getPhone())
           .in(ExpressInfo::getStatus, Arrays.asList(1, 3));
    ExpressInfo info = expressInfoMapper.selectOne(wrapper);
    if (info == null) {
        throw new BizException("取件码或手机号不正确，请核对后重试");
    }

    // 2. 校验状态流转 1或3 -> 2
    statusValidator.validate(info.getStatus(), 2);

    // 3. 更新状态
    ExpressInfo update = new ExpressInfo();
    update.setId(info.getId());
    update.setStatus(2);
    update.setSignTime(LocalDateTime.now());
    expressInfoMapper.updateById(update);

    // 4. 记录签收日志（异步）
    signLogService.saveSignLog(info.getId(), request.getOperator());
    return R.ok();
}

这个接口的关键点在于取件码和手机号必须同时匹配，只拿取件码就能取件的话，等于谁捡到纸条谁就能拿走包裹，安全性太差。我刻意把取件码显示在快递单上，是为了让工作人员快速找件，真正的身份校验靠手机号完成。

4.3 管理后台：滞留件预警、数据看板和定时任务

管理端我需要重点讲两个功能：滞留件预警和数据看板。

滞留件预警的一个核心实现是：用Spring Boot自带的@Scheduled定时任务，每天凌晨2点扫描一次已入库超过48小时且状态仍为1的包裹，批量标记为状态3并触发提醒。

java复制@Component
public class OverdueScanTask {

    @Resource
    private ExpressInfoMapper expressInfoMapper;

    @Resource
    private NoticeService noticeService;

    @Scheduled(cron = "0 0 2 * * ?")
    public void scanOverdueExpress() {
        LocalDateTime deadline = LocalDateTime.now().minusHours(48);
        LambdaQueryWrapper<ExpressInfo> wrapper = new LambdaQueryWrapper<>();
        wrapper.eq(ExpressInfo::getStatus, 1)
               .lt(ExpressInfo::getWarehouseTime, deadline);
        List<ExpressInfo> overdueList = expressInfoMapper.selectList(wrapper);
        if (CollectionUtils.isEmpty(overdueList)) {
            return;
        }
        for (ExpressInfo info : overdueList) {
            ExpressInfo update = new ExpressInfo();
            update.setId(info.getId());
            update.setStatus(3);
            expressInfoMapper.updateById(update);
            noticeService.sendOverdueNotice(info);
        }
    }
}

数据看板则通过聚合SQL查询实现，统计今日入库量、已签收量、滞留量、各快递公司单量占比等指标。这里我直接用了MyBatis的@Select注解写统计SQL，比用QueryWrapper简单：

java复制@Select("SELECT company_code, COUNT(*) AS cnt FROM express_info " +
        "WHERE site_id = #{siteId} AND create_time >= #{startTime} " +
        "GROUP BY company_code")
List<CompanyStatVO> countByCompany(@Param("siteId") Long siteId, @Param("startTime") LocalDateTime startTime);

提示：管理看板的数据如果每次打开都实时查数据库，高峰期会拖垮主库。我当时用Redis缓存了看板数据，5分钟过期。这个优化很轻量，但对页面响应速度的提升非常明显。

5. 权限与安全：JWT认证、密码加密和接口防刷

一个物流系统里涉及用户的姓名、手机号、学号等隐私数据，安全这块不能应付。我的做法是JWT做登录态管理 + BCrypt做密码加密 + 拦截器做接口鉴权，同时针对敏感接口做防刷限制。

5.1 三端角色如何用一套JWT统一管理

系统里有三类角色，如果每一种都单独写登录逻辑和Token校验，代码会非常冗余。我的做法是统一用用户表 + role字段区分角色，登录成功后发放JWT Token。

这里用到了jjwt库：

java复制public String generateToken(User user) {
    long nowMillis = System.currentTimeMillis();
    Date now = new Date(nowMillis);
    long expMillis = nowMillis + expireTime; // 过期时间，默认24小时
    Date expDate = new Date(expMillis);

    return Jwts.builder()
            .setSubject(String.valueOf(user.getId()))
            .claim("role", user.getRole())  // 把角色写进Token
            .claim("siteId", user.getSiteId())
            .setIssuedAt(now)
            .setExpiration(expDate)
            .signWith(secretKey)
            .compact();
}

然后在拦截器里统一解析Token。这里有一个容易被忽视的点：如果接口既允许登录用户访问，又需要区分角色权限，建议用两个拦截器。第一个拦截器只负责Token校验和用户信息注入，第二个拦截器才做角色权限匹配。分开的好处是职责清晰，某个接口如果不需要鉴权，只配置第一层拦截器即可。

我的权限注解如下：

java复制@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface RequireRole {
    String[] value(); // 角色编码，如ADMIN、COURIER、STUDENT
}

使用方式：

java复制@RequireRole({"ADMIN"})
@GetMapping("/admin/stats")
public R<?> getStats() { ... }

5.2 密码加密与配置信息加密

用户的登录密码绝对不允许明文存储。我选择的加密方案是BCryptPasswordEncoder，它是Spring Security里的标准密码加密器，自带随机盐，同一密码每次加密结果都不同，防止彩虹表攻击。

java复制@Bean
public PasswordEncoder passwordEncoder() {
    return new BCryptPasswordEncoder();
}

注册时存密文，登录时用encoder.matches(rawPassword, encodedPassword)校验。不要为了省事直接MD5加密，MD5的碰撞攻击和彩虹表攻击风险太高。

配置信息加密同样重要。用户提到过"数据库用户密码采用SM4加密并在JasyptStringEncrypt中使用"的做法。Jasypt就是一个很好的配置加密工具，我在application.yml里对数据库密码、第三方API密钥等敏感信息做了加密处理：

yaml复制spring:
  datasource:
    url: jdbc:mysql://localhost:3306/express_campus
    username: root
    password: ENC(Xk9x...加密后的密文)

启动时通过JasyptStringEncryptor解密。注意，加密的密钥（salt）不要写在application.yml里，建议通过环境变量注入，否则等于没加密。我实测过，Jasypt在Spring Boot 2.x中集成很简单，依赖引入后配置一个StringEncryptor即可。

5.3 接口防刷与敏感操作二次校验

物流系统有几个接口容易被恶意调用，最典型的就是"查询快递"和"确认取件"。如果被人写脚本遍历手机号，就能批量查询他人快递信息。我的防护措施有两个：

第一个是Redis计数器限流，对按IP + 接口路径维度做每分钟调用次数限制：

java复制@Component
public class RateLimitInterceptor implements HandlerInterceptor {

    @Resource
    private RedisTemplate<String, Integer> redisTemplate;

    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {
        String ip = getIpAddr(request);
        String key = "rate:limit:" + ip + ":" + request.getRequestURI();
        Long count = redisTemplate.opsForValue().increment(key);
        if (count != null && count == 1) {
            redisTemplate.expire(key, 1, TimeUnit.MINUTES);
        }
        if (count != null && count > 30) {
            throw new BizException("请求过于频繁，请稍后再试");
        }
        return true;
    }
}

第二个是取件时增加再次确认弹窗，前端必须显示取件码和手机尾号，用户点击确认后才发请求。这个虽然只是前端交互，但能过滤掉大部分误操作和恶意脚本。

6. 实战排错：事务失效、IDEA配置不提示、Docker部署失败

做这个项目的过程中我踩了不少坑，有些坑查了很久才找到原因。这一章全部记录下来，希望能帮你少走弯路。

6.1 同一个类内部方法调用导致事务失效

在开发批量入库时，我希望"批量创建快递单 + 记录操作日志"这两个操作在同一个事务里，要么都成功，要么都失败。于是我在Service里写了一个方法，内部调用另一个事务方法：

java复制@Service
public class ExpressServiceImpl implements ExpressService {

    @Transactional(rollbackFor = Exception.class)
    public void batchCreateWithLog(List<ExpressInfo> list) {
        expressInfoMapper.saveBatch(list);
        this.writeLog(list.size()); // 同类的内部调用，事务不生效！
    }

    @Transactional(propagation = Propagation.REQUIRES_NEW)
    public void writeLog(int count) { ... }
}

结果测试时发现：如果writeLog抛出异常，已经插入的快递单竟然没有回滚。排查了很久才发现这是Spring事务代理的经典陷阱。@Transactional生效的前提是方法被Spring的AOP代理调用，但同一个类内部通过this调用时，走的是原始对象而不是代理对象，所以事务注解完全被忽略了。

解决办法是把内部方法拆到另一个Service，让Spring代理去拦截：

java复制@Service
public class ExpressLogService {
    @Transactional(propagation = Propagation.REQUIRES_NEW)
    public void writeLog(int count) { ... }
}

然后注入ExpressLogService，在batchCreateWithLog中调用expressLogService.writeLog(list.size())，事务就能正常生效了。

6.2 IDEA里application.yml不提示的处理

用IDEA开发Spring Boot项目时，application.yml里写spring.datasource等配置一般有自动提示。但有时候引入某些自定义配置后，提示就失效了。

这个问题的本质原因是IDEA的Spring插件没有识别到对应的ConfigurationProperties元数据。处理方案有两种：

第一种，引入spring-boot-configuration-processor依赖：

xml复制<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-configuration-processor</artifactId>
    <optional>true</optional>
</dependency>

插件会扫描项目里的@ConfigurationProperties类，生成spring-configuration-metadata.json文件，然后IDEA就基于这个文件做提示。

第二种，如果某个第三方库的配置没有提示，手动下载它的配置元数据文件放到META-INF目录下。但这比较繁琐，优先用第一种方案。

6.3 Spring Boot打包到Docker Desktop的几个坑

我用Docker Desktop做本地部署验证，踩了两个印象深刻的坑。

第一个坑是镜像构建时下载依赖超时。用mvn package打好Jar包后写Dockerfile，基于openjdk:8-jdk-alpine镜像。构建时因为网络问题，apk add或者Maven下载依赖经常超时。解决办法是给Maven配置阿里云镜像，同时在Docker构建时把Maven仓库挂载为本地缓存：

dockerfile复制FROM maven:3.8-openjdk-8 AS builder
COPY settings.xml /root/.m2/settings.xml  # 配置阿里云镜像
COPY . /app
WORKDIR /app
RUN mvn clean package -DskipTests -o  # 使用离线模式构建，依赖已在本地缓存

FROM openjdk:8-jre-alpine
COPY --from=builder /app/target/*.jar /app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "/app.jar"]

第二个坑是容器内访问宿主机MySQL失败。默认的localhost指向了容器本身，连接MySQL时明明账号密码正确却提示Connection refused。这需要把数据库地址改成host.docker.internal：

yaml复制spring:
  datasource:
    url: jdbc:mysql://host.docker.internal:3306/express_campus

Docker Desktop在Mac和Windows上默认支持这个域名，Linux上需要加--add-host=host.docker.internal:host-gateway参数。

6.4 静态资源映射：头像和取件凭证图片怎么处理

还有一个开发时容易忽略的点——Spring Boot静态资源映射。项目里学生可以上传头像，快递员可以上传取件凭证照片。这些文件如果直接放在前端项目里，前端重新部署就全没了。我的方案是单独建一个文件存储目录，然后通过WebMvcConfigurer配置资源映射：

java复制@Configuration
public class WebMvcConfig implements WebMvcConfigurer {

    @Value("${file.upload-path}")
    private String uploadPath;

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/files/**")
                .addResourceLocations("file:" + uploadPath + "/");
    }
}

这样前端访问/files/avatar/xxx.jpg就能直接加载到本地磁盘上的文件。这里我踩过一个坑：addResourceLocations的路径必须以/结尾，否则映射不生效。另外生产环境建议用云存储（阿里云OSS或MinIO），本地磁盘存储只适合开发环境和小规模部署。

7. 项目上线后的思考：日志、监控与下一步优化

系统开发完成后，我在学校站点试运行了两周。功能基本稳定，但在运维和性能方面有一些新的体会。这一章更像是一份操作记录，分享一下上线后的真实情况和可扩展的方向。

7.1 日志与慢SQL监控怎么做

试运行期间我最担心的是"某天上午入库高峰，数据库被打挂"。因此我做了两个监控手段。

第一个是SQL日志打印。在application.yml中开启MyBatis Plus的SQL日志，排查问题时能看到实际执行的SQL和参数：

yaml复制mybatis-plus:
  configuration:
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl

第二个是慢SQL统计。MySQL本身有慢查询日志，也可以在业务层用切面统计耗时超过500ms的Mapper操作。当时我用一个简单的AOP切面做了拦截：

java复制@Aspect
@Component
public class SlowSqlAspect {

    @Around("execution(* com.campus.express.mapper.*.*(..))")
    public Object logSlowSql(ProceedingJoinPoint pjp) throws Throwable {
        long start = System.currentTimeMillis();
        try {
            return pjp.proceed();
        } finally {
            long cost = System.currentTimeMillis() - start;
            if (cost > 500) {
                log.warn("慢SQL警告：{} 耗时 {}ms", pjp.getSignature(), cost);
            }
        }
    }
}

试运行期间确实抓到了几个慢SQL，基本都是没有命中索引的查询。后来给电商常用的查询字段补了联合索引后，慢SQL数量大幅下降。

7.2 从单机到集群：哪些地方需要改

如果站点规模扩大，比如接入多个校区多个站点，当前的单机部署方案可能需要演进。我梳理了需要改动的几个关键点：

第一，Redis必须独立部署，并开启持久化。现在取件码生成依赖Redis的INCR指令，如果Redis崩了又没持久化，取件码可能会重复，这是不能接受的。

第二，定时任务需要分布式锁。目前@Scheduled任务在同一台机器上没问题，但如果部署多个实例，同一个定时任务会被执行多次。解决办法是引入Redisson的分布式锁，或者把定时任务抽成独立的调度服务。

第三，文件存储从本地磁盘迁移到MinIO或OSS。本地磁盘在单机下够用，但多实例部署时每个实例的文件不一致，必须使用集中存储。

第四，前端部署需要Nginx做反向代理，同时开启Gzip压缩和静态资源缓存。

7.3 可以扩展的方向：Flowable、Quartz、WebSocket

最后说一下几个我计划中但还没有实施的方向：

流程引擎Flowable。如果站点需要更复杂的工单处理流程，比如"丢件申诉 → 站点核实 → 理赔审批 → 财务打款"，用Flowable工作流引擎会比硬编码状态流转清晰得多。Spring Boot整合Flowable相当方便，直接引入依赖后配置数据源即可，官方还提供了在线流程设计器。

定时任务框架Quartz。Spring自带的@Scheduled只适合简单任务，如果任务多了需要做任务调度、失败重试、任务编排，Quartz是更合适的选择。比如每个站点可以单独配置滞留时间阈值（有的站点48小时，有的72小时），这种动态配置的定时任务用Quartz的CronTrigger加数据库持久化会更合适。

WebSocket实时推送。目前取件通知是短信/微信推送，但学生登录系统后在页面端也可以收到实时通知。比如快递员确认入库的那一瞬间，学生如果正在网页上查看快递列表，可以通过WebSocket实时刷新状态，体验会好很多。

另外，springboot整合activemq也是一个可参考的方向。当系统里的通知任务量再多一些，或者异步任务执行时间一旦过长，可以考虑用消息队列做削峰和重试，ActiveMQ在这个体量下完全够用。

做这套系统最大的心得是：一个真实业务系统的难点从来不在于用了什么高深框架，而在于把每个细节都考虑到位。从业务调研、数据库设计、状态流转，到安全策略、部署上线，每个环节都在打磨。希望这篇文章能给你一些启发，不管是做毕业设计还是学习Spring Boot实战，都能少踩几个坑。

校园快递排队？用Spring Boot撸一个智能物流管理系统