无人共享图书借阅平台Java实战：分布式锁与状态机踩坑全记录-代码聚汇网

接手这个"无人共享图书借阅平台"的Java项目时，我还没意识到后面会踩这么多坑。表面上这是一个典型的图书管理业务系统，真正深挖下去，无人值守带来的分布式锁、会话保活、异常订单补偿、书格状态一致性，每个点都能单独写一篇排查实录。这篇博文就把整个从零搭建的过程拆开揉碎，从需求建模、核心模块设计到高并发借阅场景下的踩坑修复，完整复现一遍，希望能给正在做同类Java源码项目的朋友省点时间。

1. 无人共享借阅平台的核心需求域拆解：借什么书、谁来还、怎么确保书不丢

先别急着写代码。做这类平台型Java项目，第一件事是把"无人"两个字背后的业务语义想清楚。传统的图书管理系统是管理员坐在前台，借书还书都有人工确认环节，而共享图书平台完全依赖用户自助操作，平台方只能通过硬件设备和后端逻辑去约束用户行为。

这个平台的核心参与方有三类：借阅者、图书所有者（可能也是普通用户）、平台运营方。需求域可以拆成四个主要板块：

图书资源管理：图书上架、下架、库存状态维护、封面与ISBN信息管理。共享场景下，图书来源有两类，一是平台自营书库，二是用户个人共享上架。这两类书在后续的借阅规则、押金策略、损坏赔付上需要区分处理。
自助借阅流程：用户扫码或搜索找到图书、提交借阅申请、系统校验资格、分配具体书格、生成取书码、用户到柜取书。整个流程必须无人介入，因此每个环节都要设计超时和异常兜底。
自助还书流程：用户还书、选择空余书格、柜门打开、用户放入图书、系统确认还书成功、更新订单状态。这个流程比借阅更容易出问题，因为涉及物理世界的不确定性，比如用户放错格子、柜门故障、图书RFID读取失败等。
信用与违约管理：借阅超时未取、逾期未还、图书损坏丢失，都需要自动化的信用扣减和赔付结算体系。

在技术建模上，我们最终确定了五张核心业务表：用户表、图书表、书格表、借阅订单表、违规记录表。订单表是整个系统的核心，几乎所有并发问题都围绕订单状态流转展开。

订单状态机需要精心设计，借阅侧的流转是"待取书 -> 已借出 -> 已逾期 -> 已归还"，还书侧是"待还书 -> 已确认归还 -> 已结算"。每个状态的迁移必须有明确的时间戳和操作来源，这样后续做超时任务、对账、异常补偿时才能有据可依。

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

2. 技术选型和项目骨架搭建：Spring Boot 3 + MyBatis-Plus + Redis + MySQL的组合逻辑

2.1 为什么选这套组合而不是更重的微服务架构

很多人一看到"无人共享平台"就想上微服务，把用户、图书、订单、支付拆成四个服务，再用Spring Cloud Alibaba做注册发现。如果你是学习性质或者中小规模部署，这个架构在当前阶段没有意义，反而引入分布式事务、服务间调用链追踪等一大堆复杂度。

这个项目我用的是单体内聚 + 模块化分包的单体架构，固定技术栈为Spring Boot 3.2.x + MyBatis-Plus 3.5.x + Redis 6.x + MySQL 8.x + Redisson 3.x。单体架构在这个阶段有明确优势：事务边界清晰，借书流程中扣减库存、创建订单、分配书格可以放在同一个本地事务里直接完成，不需要考虑分布式事务；部署运维简单，一个Jar包加一个Nginx就能跑完整套服务；调试方便，业务链路在同一进程内能快速定位问题。

那Redis用来做什么？有两个不可替代的用途。第一是分布式锁，后面会详细讲，借书和还书时对同一本书、同一个书格的操作必须加锁；第二是订单状态机和用户会话的缓存加速，高频读取的低变数据放到Redis里，能显著降低数据库压力。

2.2 项目目录结构与关键配置

分包设计上采用了按业务域划分的package结构，而不是传统的controller/service/mapper三层平铺：

code复制com.example.bookshare
├── common          // 通用返回体、异常处理、工具类
├── config          // Redis、Redisson、MybatisPlus、线程池配置
├── controller      // 接口层
├── service         // 业务逻辑层，接口与实现分离
├── mapper          // 数据访问层
├── entity          // 数据库实体
├── dto             // 入参出参对象
├── enums           // 订单状态、书格状态、用户角色枚举
├── task            // 定时任务（超时未取、逾期提醒等）
├── mq              // 事件生产者与消费者（基于Redis Stream）
└── lock            // 分布式锁封装

配置文件里几个关键项需要注意。MyBatis-Plus的逻辑删除全局配置和乐观锁插件要提前配好，因为共享图书场景下可能会有管理后台删书、用户并发借同一本书这类操作，没有乐观锁很容易出现脏更新。数据源连接池我用的HikariCP，MySQL的隔离级别设置为读已提交（READ_COMMITTED），而不是MySQL默认的可重复读（REPEATABLE_READ）。原因在于借阅场景的核心诉求是防止超卖，并不需要事务内多次读取结果一致，读已提交配合行锁已经足够，还能减少间隙锁带来的死锁概率。

Redis方面，key设计要带着业务前缀和技术前缀，比如 book:stock:detail:{bookId}、order:lock:borrow:{bookId}、cell:status:{cellId}。所有key必须设置TTL，即使业务上看起来是永久数据，也需要加一个很长的过期时间作为兜底，防止Redis内存泄漏。

3. 图书共享领域的核心业务建模：书格、库存与订单状态机

3.1 书格模型：一个格子一本书的物理约束

实体书柜是共享借阅平台的物理载体，一个柜子通常有几十个格子，每个格子放一本书。格子门锁通过物联网模块控制，后端系统下发开锁指令，用户才能打开指定的柜门。

在设计数据模型时，书格表 book_cell 既要描述物理位置，也要维护实时状态。字段至少有：柜ID、格子编号、格子状态（空闲/占用/禁用/维护中）、当前存放图书ID、最后操作时间、开锁密码等。

一个关键业务规则是"一个格子同一时刻只能关联一本书"，这既是物理约束也是逻辑约束。但数据库层面这个约束只能通过逻辑代码保证，没办法建唯一索引，因为在历史记录中同一个格子确实会关联过很多不同书籍。实现时要靠两条路保证：一是在还书分配格子和借书释放格子时加分布式锁，确保格子状态的并发安全；二是引入格子操作流水表，每次格子状态变更都记录一条流水，包括动作类型、操作前状态、操作后状态、操作人ID、时间戳，用于事后追溯和数据对账。

3.2 库存扣减方案：从普通减库存到预占模式

共享图书的库存模型和电商不一样。电商商品的SKU库存通常是一个数字，而这个平台的库存不是"图书可借总数量"，而是具体的书格维度。比如一本《Java编程思想》有3本副本，分别放在柜A的1号格、柜B的5号格、柜C的9号格，用户借阅时必须确认自己愿意去哪个柜取书。

因此在提交借阅申请阶段，系统的库存扣减要做两个动作：一是对图书维度加锁，防止两人同时申请同副本；二是将某个具体书格标记为"预占"状态。预占不等同于已借出，只表示这个副本被某个订单锁定了。

预占期的设计直接关系到用户体验和资源利用率。如果用户提交申请后迟迟不来取书，格子一直预占会导致图书资源闲置。常规方案设定一个30分钟的预占有效期，超时未取则自动释放库存、取消订单，并对用户做一次违规记录。这个30分钟的超时释放由定时任务扫描实现，周期设在每分钟一次，扫描条件是订单状态为待取书且创建时间早于当前时间30分钟。

释放预占我使用的是先更新数据库订单状态，再释放Redis锁，最后更新格子状态的多段式操作，且完整执行在一个事务方法内。这样能确保不会有中间状态遗漏，即使某一步失败也能通过定时补偿任务兜底。

3.3 订单状态机的可扩展设计

订单状态机如果只用switch判断会非常难受，后续每加一种状态或一个流转条件，就要改动一堆散落的逻辑。更好的做法是引入状态机配置表 + 统一的流转入口。

这个平台的核心订单状态按方向分为两条主链路。借阅链路：WAIT_PICKUP(待取书) 到 BORROWED(已借出) 到 OVERDUE(已逾期) 到 RETURNED(已归还) 到 SETTLED(已结算)。还书异常链路需要额外记录：WAIT_RETURN、RETURN_ABNORMAL（还书异常）、DISPUTED（争议中）。我维护了一个枚举类，把"当前状态 + 触发事件 -> 下一状态 + 执行动作"集中映射，后续每次状态流转统一调用 orderStateMachine.transit(order, event)，再在方法内做合法性校验和扩展点触发。

java复制public enum OrderStateMachine {
    INSTANCE;

    private final Map<OrderState, Map<OrderEvent, OrderTransition>> transitions = new ConcurrentHashMap<>();

    OrderStateMachine() {
        // 待取书 -> 取书成功：进入已借出，记录借出时间
        register(OrderState.WAIT_PICKUP, OrderEvent.PICKUP_SUCCESS, 
                OrderState.BORROWED, ActionType.RECORD_BORROW_TIME);
        // 待取书 -> 超时未取：取消订单，释放格子
        register(OrderState.WAIT_PICKUP, OrderEvent.PICKUP_TIMEOUT,
                OrderState.CANCELLED, ActionType.RELEASE_CELL);
        // 已借出 -> 逾期未还：状态变为逾期
        register(OrderState.BORROWED, OrderEvent.OVERDUE_DEADLINE,
                OrderState.OVERDUE, ActionType.START_OVERDUE_COUNT);
        // 已借出/逾期 -> 归还成功：进入已归还
        register(OrderState.BORROWED, OrderEvent.RETURN_SUCCESS,
                OrderState.RETURNED, ActionType.RELEASE_CELL);
        register(OrderState.OVERDUE, OrderEvent.RETURN_SUCCESS,
                OrderState.RETURNED, ActionType.RELEASE_CELL);
        // 已归还 -> 结算完成：计算费用，扣减信用分
        register(OrderState.RETURNED, OrderEvent.SETTLE_SUCCESS,
                OrderState.SETTLED, ActionType.CALCULATE_FEE);
    }
}

这套状态机的价值在于所有状态流转都收敛到一个入口，可以很方便地加权限校验、幂等校验和审计日志。后面的还书异常、用户申诉、管理员介入等场景都从这套核心状态机上扩展，避免每个业务方法里悄悄改订单状态导致状态链路失控。

4. 借书主流程的Java实现：从扫码到取书码生成的全链路

4.1 借阅申请接口：锁、校验、预占三步

借阅申请是整个链路的第一步，用户在前端选定图书副本并点击借阅，后端接口需要完成四件事：校验用户资格、锁定副本、检查书格状态、创建预占订单。

接口路径类似 /api/borrow/apply，POST请求。第一步先走用户资格校验：用户状态必须正常，当前未归还图书数量不能超过上限（默认设置为3本），信用分不低于600分。这些校验必须全部通过Redis或数据库实时读取，不允许用前端缓存数据，因为用户在短时间内可能连续操作。

第二步是核心并发控制点。具体某本副本的借阅权通过Redisson的公平锁实现，锁的粒度精确到书格维度。同一个格子同时只能有一个用户申请，锁的等待时间设为3秒，超出则直接提示"手慢了，这本书刚刚被借走"。这个锁等待时间不宜过长，否则当大量用户同时抢同一副本时，接口RT会堆得很高，影响其他正常请求。

第三步加锁成功后，需要重新查询一次数据库中的格子状态，确认仍然是可用状态，然后再发起数据库更新：书格状态改为预占，用户借阅订单插入订单表，状态为待取书。这三步操作放在一个 @Transactional(rollbackFor = Exception.class) 方法中，因为格子状态和订单状态必须保证同时成功或同时失败。

java复制@Transactional(rollbackFor = Exception.class)
public BorrowApplyResult applyBorrow(BorrowApplyRequest request) {
    // 简化版核心逻辑，实际需要补充必要校验
    UserInfo user = userMapper.selectById(request.getUserId());
    validateUserCanBorrow(user);
    
    String lockKey = "borrow:cell:" + request.getCellId();
    RLock lock = redissonClient.getFairLock(lockKey);
    boolean acquired = false;
    try {
        acquired = lock.tryLock(3, 10, TimeUnit.SECONDS);
        if (!acquired) {
            throw new BizException("当前借阅人数较多，请稍后重试");
        }
        // 加锁后重新查询格子状态
        BookCell cell = cellMapper.selectById(request.getCellId());
        if (cell == null || !BookCellStatus.AVAILABLE.equals(cell.getStatusCode())) {
            throw new BizException("该书格当前不可用");
        }
        BookStock stock = stockMapper.selectById(cell.getBookId());
        // 扣减库存 / 修改格子为预占
        int rows = stockMapper.compareAndSetStatus(
            cell.getId(), BookCellStatus.AVAILABLE.getCode(),
            BookCellStatus.PRE_OCCUPIED.getCode(), cell.getVersion());
        if (rows == 0) {
            throw new BizException("图书刚被借出，换个格子试试");
        }
        String orderNo = generateOrderNo();
        borrowOrderMapper.insert(createOrder(user, stock, cell, orderNo));
        return new BorrowApplyResult(orderNo, cell.getCellCode());
    } catch (InterruptedException e) {
        Thread.currentThread().interrupt();
        throw new BizException("系统繁忙，请稍后重试");
    } finally {
        if (acquired && lock.isHeldByCurrentThread()) {
            lock.unlock();
        }
    }
}

这里有个非常容易踩的坑：MyBatis-Plus自带的 updateById 会根据实体字段全量更新，如果并发场景下先查后改，容易发生丢失更新。解决方法是使用自定义的SQL，在where条件中带上期望的旧状态和version字段，用乐观锁做条件更新。上面的 compareAndSetStatus 就是这样的自定义更新方法，返回影响行数来判断是否更新成功，这是防并发超卖最关键的一行代码。

4.2 取书码生成与下发逻辑

用户提交借阅申请后，系统并不立即开门，而是先生成一个取书码。取书码采用6位纯数字，避免和字母混淆（去掉0和O这类容易看错的字符），有效期为30分钟，过期作废。

这个取书码不能只存在数据库里，因为取书动作要高频校验。我把取书码以字符串形式存到Redis，key设计为 pickup:code:{orderNo}，过期时间30分钟，同时存储用户ID和格子ID作为附属信息。下发方式优先走微信公众号模板消息或短信接口，如果用户实时在线则通过WebSocket推送，避免用户退出页面后错过通知。

生成取书码时用到 SecureRandom 而非 Math.random()，原因在于取书码是用户取书的唯一凭证，有一定的安全要求，弱随机数可能被预测。同时要校验新生成的码与Redis中现有code不冲突，如果冲突则重新生成。

4.3 取书确认接口：幂等设计与异常兜底

用户到柜后输入取书码，智能柜下发开锁指令，用户取走图书，柜端上报取书结果事件，后端确认取书成功。此时借阅订单状态从待取书流转为已借出。

取书确认接口面临的最大问题是重复通知。网络抖动、柜端模块重试、消息队列重复推送都可能导致同一个取书成功事件被后端处理多次。因此接口必须做幂等设计，我用的方案是事件去重表。取书事件带有全局唯一的eventId，处理前先查event表是否已存在该id，存在则直接返回成功（幂等响应），不存在则插入event记录并更新订单状态，二者在同一个事务里执行。

订单状态更新本身也要做条件更新，UPDATE borrow_order SET status = 'BORROWED', real_borrow_time = NOW() WHERE order_no = #{orderNo} AND status = 'WAIT_PICKUP'，保证不会出现已经取消的订单被再次确认取书成功。

借阅计时的起算节点以这条更新语句的成功执行时间为准，数据库中存储真实的借出时间戳，业务展示层将当前时间与借出时间相减，得到借阅时长。这个设计确保定时任务也好、用户端展示也好，获取到的都是同一个时间基准。

5. 还书主流程与柜机联动：空闲格分配算法与多线程状态同步

5.1 还书空闲格分配的两级筛选策略

用户还书时打开小程序或H5页面点击"我要还书"，系统推荐一个空闲的书格。空余格推荐看起来简单，实际上要满足两个目标：用户走的距离尽量短，格子分配后系统整体碎片率尽量低。

最朴素的做法是把所有空闲格随机取一个，但这样会产生一个体验问题：用户明明站在3号柜前面，系统却分配了距离很远的8号柜的空格。所以分配算法的第一步是根据用户当前位置坐标或上一次借书柜的位置，筛选出附近的柜组，再在这些柜组中找空闲格。

第二步网格内筛选，我设计了优先级规则：优先推荐当前柜组中空闲且该格对应书籍最近被归还过的格子（减少找书难度），其次推荐柜组内编号连续的格子（便于用户查找），最后才是随机空闲格。这里的核心原则是不要让用户跨柜还书，除非当前柜完全没有空格。实际运营数据表明，同柜还书的订单满意度远高于跨柜还书，而取书和还书经常发生跨柜是平台运营需要另行优化的调度问题。

挑选好格子后，要加锁并CAS更新格子状态为空闲中。还书格的分布在柜机端还要考虑同柜多用户同时还书的场景，必须有锁保护。

java复制public CellPickResult pickReturnCell(ReturnPickRequest request) {
    // 1. 查询用户当前待还订单
    List<BorrowOrder> pendingOrders = borrowOrderMapper.selectPendingByUserId(request.getUserId());
    if (pendingOrders.isEmpty()) {
        throw new BizException("当前没有待归还的图书");
    }
    // 2. 第一级过滤：优先同柜设备
    List<BookCell> nearbyCells = cellMapper.selectAvailableCellsByCabinet(request.getCabinetId());
    if (nearbyCells.isEmpty()) {
        // 本柜没有空格，可以扩展到附近柜组
        nearbyCells = cellMapper.selectAvailableCellsNearby(
            request.getCabinetId(), request.getLatitude(), request.getLongitude());
    }
    // 3. 第二级过滤 + 随机
    BookCell targetCell = nearbyCells.stream()
        .sorted(Comparator.comparing(BookCell::getLastReturnTime).reversed())
        .findFirst()
        .orElseThrow(() -> new BizException("附近暂无空闲书格，请联系管理员"));
    // 4. 分布式锁 + CAS 状态更新
    String lockKey = "cell:return:" + targetCell.getId();
    // ... 加锁与状态更新
    return new CellPickResult(targetCell);
}

5.2 还书确认的传感器事件流与异常重试

用户把书放进格子、关闭柜门后，柜端传感器上报"柜门已关闭且感应到图书存在"事件。后端收到事件后，需要把格子状态从"空闲中"更新为"占用"，同时把借阅订单状态从已借出/逾期更新为已归还，并进行费用结算。

这里有一个关键的工程问题：柜机的网络环境往往不如机房稳定，事件上报可能延迟几秒甚至几分钟。如果后端在收到事件后立即扣减用户的借阅费用，但实际用户还书时间比事件上报时间早，就会产生计费偏差。合理做法是信任柜机事件中携带的物理关门时间戳，以后端服务和柜机服务的最大校准偏差5分钟为界：如果事件时间戳和服务器当前时间差在5分钟内，直接以服务器当前时间作为还书时间；如果超过5分钟，以事件时间戳为准并记录日志，同时通知运营人员核查柜机时间同步情况。

如果柜机没有RFID或压力传感器，只有门锁状态，系统必须增加一道人工确认兜底链路：用户还书后预约柜门关闭，上报开门事件。后端在连续N秒内没有收到关门事件，自动触发柜机状态查询接口，向柜机发起重试。超过3次仍然失败的，订单状态标记为"还书异常待人工确认"，由运营人员在管理后台手动确认。这个兜底链路必须在设计阶段就预留，因为物理设备的故障率远高于服务器软件故障率，没有兜底方案"无人"就会变成"无人管"。

6. 分布式锁的正确使用姿势：我对常见误用方式的复盘

6.1 为什么简单的synchronized不够用

开发阶段图省事，我曾经用synchronized关键字锁借书方法，本地单机测试一切正常，一部署到多实例就出问题。原因很简单：synchronized只能锁住单个JVM内部的线程，而线上服务是双节点部署，两个用户同时请求会落在不同的Tomcat实例上，各自拿到锁，同时操作同一个格子状态，导致超借。

解决跨进程互斥必须引入分布式锁。项目中使用Redisson的原因，在于它的看门狗机制能有效避免锁过期导致业务没执行完但锁已自动释放的问题。默认情况下，Redisson的锁过期时间是30秒，如果持锁线程还在执行，看门狗会每10秒自动续期一次。你不用担心锁过期把正在执行的任务打断，除非服务彻底宕机，锁最终会在看门狗停止后续期失败而释放。

6.2 用错锁粒度带来的性能与死锁问题

我第一次重构加锁时简单粗暴地把整个借书接口锁了，锁粒度是方法级别，锁key是全局固定字符串。这个设计实现起来容易，但性能极差，所有用户的借书请求全局串行化，并发测试时吞吐量只有不到20TPS，直接成为系统瓶颈。

后面把锁粒度细心化了：借书场景锁两个维度，第一把锁锁 borrow:book:{bookId}，把同一本书的多副本请求串行化，避免多个副本被同一用户同时借走或者两个用户竞争数据库中的库存记录；第二把锁锁 borrow:cell:{cellId}，确保同一个格子的状态变更互斥。锁一定要放在事务外层，避免锁还没释放事务就提交导致的幻读问题。

千万不要在持锁期间调用外部HTTP接口，比如用户借书时在锁内调用信用积分服务，一旦外部接口响应慢，锁持有时间会无限拉长，Redisson看门狗虽然会续期，但极端情况下可能拖垮整个服务。正确的做法是锁内只操作数据库和Redis，外部调用放到锁外或异步化。

6.3 锁和事务嵌套顺序问题

Spring的声明式事务默认在方法返回时提交。如果在一个 @Transactional 方法内部加了分布式锁，但方法结束后马上释放锁，这时事务其实还没有提交，另一个线程拿到锁了，查询数据库却读不到前一个事务未提交的数据，会造成逻辑判断错误。

解决方式是让锁的生命周期包含整个事务提交过程。我采用的做法是把锁逻辑放到Service层的外层调方法，事务方法作为内部方法被调用。外层方法负责加锁和释放锁，内层方法只负责事务操作。这样事务会在内层方法返回时提交，此时外层锁还没释放，其他线程要等锁释放后才能真正读到已提交的数据。

java复制public void handleBorrow(String orderNo) {
    String lockKey = "order:handle:" + orderNo;
    RLock lock = redissonClient.getLock(lockKey);
    lock.lock(10, TimeUnit.SECONDS);
    try {
        borrowService.doBorrowInTransaction(orderNo); // 方法上有 @Transactional
    } finally {
        lock.unlock();
    }
}

7. 还书超时检测与超时任务调度：定时扫描还是延迟队列

共享图书平台有两个典型的超时场景，需要系统自动判定并触发后续流程。一是用户申请借书后30分钟未取书，自动取消订单；二是借阅到期后未还书，自动把订单流转为逾期状态，开始计算逾期费用。

两个场景的及时性要求不同。超时未取虽然不紧急，但要在用户可能继续借其他书的场景下尽快释放库存，所以扫描周期设在1分钟。逾期检测的精度同样不需要到秒级，每天的零点结算或者每小时跑一轮都可以接受。基于这个特点，我选择了Spring Schedule定时任务 + 数据库扫描方案，而不是引入RabbitMQ的延迟队列或者Redisson的延迟队列。原因在于延迟队列虽然精确，但需要把每个待处理订单都压入队列，系统重启后队列数据恢复要考虑持久化，复杂度会上升不少。而扫描方案只需要几个定时任务，定时任务本身要保证幂等和失败重试。

定时任务的核心是分页扫描。比如超时未取订单的SQL条件大致是 status = 'WAIT_PICKUP' AND create_time < NOW() - INTERVAL 30 MINUTE AND cancel_flag = 0，每次取500条，处理完一批再取下一批。处理时先尝试获取订单维度的分布式锁，拿到锁后做条件更新状态，另一侧通过发送站内信和短信通知用户订单已取消。

为了防止任务执行时间过长导致数据不一致，所有定时任务都加了一个开关控制，比如 @Scheduled(cron = "${task.pickup-timeout-cron}")，通过配置中心或环境变量动态调节开关。这样线上如果出现大面积积压，可以立即停掉任务排查。

这个方案有一个不能忽视的细节：订单确认取消和格子状态释放也是先处理后记录。如果释放格子失败，比如数据库临时抖动，任务要记录失败日志并重新放回待处理队列。最简单的兜底是每隔5分钟启动一个补扫任务，专门处理那些状态还是预占但对应订单已经是取消状态的孤儿数据。这种对账任务在设计初期就要加上，因为线上真正稳定的系统靠的不是每一个任务都不出错，而是出错后能被后续任务修正。

8. 会话保持与用户状态管理：为何WebSocket连接总是断

无人共享图书平台的用户操作高度依赖移动端H5或小程序。用户到达柜前，小程序需要实时接收开锁指令、柜门状态通知，这意味着前后端要维护一个长时间存活的长连接通道。开发联调阶段一切正常，到了现场经常出现用户到达柜前时连接已断开，开锁指令无法触达的情况。

排查后发现根因主要有四个：第一，H5页面在小程序WebView中长时间置于后台，系统层会主动断开网络连接；第二，Nginx默认的proxy_read_timeout设置为60秒，超过60秒没有数据交互的WebSocket连接会被断开；第三，后端没有实现心跳机制，不知道连接对端是否还活着；第四，Redis存储用户在线状态时没有续期，用户会话信息过期后，推送模块误判用户离线。

解决方案要从前端到后端整条链路对齐。前端WebSocket库实现每30秒发送一次ping帧，后端收到ping帧需要回复pong帧。Nginx配置调整，proxy_read_timeout 300s， proxy_send_timeout 300s，同时在location块中配置 proxy_http_version 1.1 和 proxy_set_header Upgrade、Connection "upgrade" 这些WebSocket必要项。后端增加心跳管理器，每隔30秒向连接写入一个自定义心跳包，同时检测连接是否在90秒内收到过任何客户端消息，超过则主动断开并清理会话。

用户在线状态的存储使用Redis的Hash结构，key为 user:online:{userId}，field区分channel类型（微信小程序、H5、管理后台），存储连接ID和最近心跳时间。每次心跳通过Pipeline方式同时更新Hash字段和设置过期时间。这样推送模块在投递消息时先查在线状态，用户在线直接推，不在线则走消息记录表，等用户下次上线拉取。

综合这些改动后，连接稳定性显著提升，现场测试一小时内连接掉线率从约30%降到1%以下。分布式部署时要注意另一件事：用户连接的是节点A，但借阅事件可能由节点B处理，推送请求如果发到节点B就会失败。因此WebSocket连接需要注册到Redis的哈希槽位中，推送模块根据用户ID哈希到对应的节点实例再转发，或者直接用Redis Pub/Sub广播，每个节点消费消息并检查该用户是否与自己建立了连接。我这里选用订阅广播模式，原因是实现简单且节点数不多，广播带来的额外开销可以接受。

9. MySQL扣减库存死锁问题排查：一条让人头疼的慢SQL

上线后借阅高峰期突然出现大量死锁异常，报错信息是经典的 Deadlock found when trying to get lock; try restarting transaction。监控面板上可以看到数据库死锁次数每分钟几十次，需要定位哪条SQL跟哪条SQL相互等锁。

我通过 SHOW ENGINE INNODB STATUS 查看最近一次死锁的详细信息。日志显示两个事务都在执行类似这样的更新语句：

sql复制UPDATE book_cell SET status = 'PRE_OCCUPIED', version = version + 1 
WHERE id = ? AND status = 'AVAILABLE' AND version = ?

奇怪的是两条SQL的id并不相同，为什么会互相造成死锁？接着看日志中事务的锁等待部分，发现两个事务都在等待一个共同的锁：某个二级索引。进一步检查表结构，发现 book_cell 表上有一个索引 idx_book_status，建立在 (book_id, status) 上。两个事务都更新了book_a下面的不同格子记录，但更新时需要对 book_id='book_a' 这段二级索引范围加锁，两个事务都先锁了各自要更新的格子主键索引，又都想获取对方持有的二级索引范围内的锁，于是形成等待环。

根因清楚了：借阅申请操作同一个book_id的多条格子记录时，多线程并发更新同一个二级索引范围，InnoDB对二级索引范围的锁无法做到像主键那样完全可串行化，导致死锁。

解决方案有三层。第一层是从SQL层面调整更新顺序，每个事务都按固定的格子ID顺序执行更新，但这对业务上无法简单排序的场景并不总是可行。第二层优化是缩小索引范围，把二级索引改成精确匹配 (book_id, cell_code) 而不是 (book_id, status)，或者直接删掉这个二级索引，让更新走主键索引，降低锁竞争范围。第三层也是最有效的一层，是在代码层面先针对 book_id 加一把分布式锁，保证同一本书的多个副本更新操作全局串行，从源头杜绝了同book_id并发更新造成的数据库层锁冲突。

死锁的根本预防不只是靠重试机制，更重要的是分析锁的维度是否合理。如果一个事务要同时更新多行记录，一定存在一个简单的规则让不同事务的加锁顺序一致，否则死锁只是时间问题。当然代码里依然也做了死锁重试机制，捕获DeadlockLoserDataAccessException后重试三次，作为最后的防线。

10. 用户信用体系与逾期罚款计算规则在Java中的落地

共享图书平台如果没有信用体系，图书丢失率会很难控制。这个模块在业务和技术上都不复杂，但坑在于规则引擎的设计容易过于抽象。初期我想引入Drools规则引擎来做信用分扣减和罚款计算，开发了一段时间后发现，这个平台的规则量级其实很小，几个核心规则通过策略模式加配置表完全可以覆盖，Drools增加了规则文件和业务代码的维护成本，后面果断移除。

信用分初始值为100分，扣分维度包括：借书超时未取扣5分，逾期还书每天扣2分且上限10分，图书损坏或丢失扣30分并触发赔偿流程，恶意占用书格扣10分。信用分低于60分时限制借书。这个规则不需要做到千人千面，做成配置表，运营人员可以直接修改配置，核心代码只需要读取配置再执行扣分。

罚款计算上需要注意金额精度问题，项目用整型存储最小货币单位（分），而不是double或float。逾期费用按日计算，日费率0.5元，即50分/天，不足一天按一天计。归还时结算费用 = 逾期天数 x 50分。用户支付后订单状态进入已结算。例如借出时间12月1日10:00，应还时间12月8日10:00，用户实际12月9日14:00归还，逾期天数计算方式：减去1天后不足1天按1天算，所以从12月8日10:00到12月9日14:00是1天零4小时，算2天，罚款100分即1元。

这里必须提醒，配置日费用时不要用浮点运算分段计算再相加，直接用整型分做乘法累加，最后再展示成元。

用户申诉和人工审核同样依赖状态机。用户在订单详情页发起"归还争议申诉"，订单状态从逾期或已归还变更到 DISPUTED，同时触发消息通知运营管理员。管理员在后台可以查看借阅记录、操作流水、柜机上报日志，支持判定申诉通过或驳回。申诉通过后状态回到已结算或撤销逾期费用，信用分会回滚或补偿，整个过程要记录完整审计日志。

11. 项目部署与压测实战：从单机到多实例的扩容之路

11.1 Docker Compose一键启动方案

本地开发阶段用Docker Compose起了整套中间件，极大方便了环境一致性。生产部署可以把后端服务打包成镜像，配合Nginx反代和Let's Encrypt证书完成HTTPS。一套典型的docker-compose配置大概长这样：

yaml复制version: '3.8'
services:
  mysql:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: root123
      MYSQL_DATABASE: bookshare
    ports:
      - "3306:3306"
    volumes:
      - ./data/mysql:/var/lib/mysql
    command: --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci

  redis:
    image: redis:6.2
    ports:
      - "6379:6379"
    command: redis-server --appendonly yes --requirepass redis123

  app:
    build: .
    depends_on:
      - mysql
      - redis
    environment:
      SPRING_PROFILES_ACTIVE: prod
      DB_URL: jdbc:mysql://mysql:3306/bookshare
      REDIS_HOST: redis
    ports:
      - "8080:8080"

注意MySQL的字符集一定要在容器启动命令中显式设置，否则默认的latin1字符集存中文会乱码。密码和敏感配置不要直接写在compose文件里，生产上建议通过环境变量文件注入。数据库的数据目录要挂载到宿主机，防止容器重建后数据丢失。

11.2 JMeter压测中发现的性能瓶颈

压测我用的JMeter，模拟场景是50个并发用户持续借书。第一轮压测结果惨不忍睹，接口平均响应时间约1.8秒，99分位达到4.5秒。定位性能瓶颈优先看链路跟踪和慢SQL日志。MyBatis-Plus开启了慢SQL统计，日志输出显示很多借阅相关的查询超过200ms，最慢的一条SQL耗时900ms。

仔细排查发现是mapper中嵌套查询导致的N+1问题。比如查询借阅订单列表时，先查订单主表，再循环查询每本书和每个格子，每多一条订单就多几次SQL。解决方法是改写为join查询或使用MyBatis的collection嵌套结果映射，一页10条数据从30多次SQL压到3次。

另一个发现是HikariCP默认连接池大小为10，50并发时大量线程在等待获取连接。调整最大连接池为50后，数据库吞吐量明显提升。但连接数翻倍之后也要注意MySQL的max_connections够不够。我给的配置是 spring.datasource.hikari.maximum-pool-size=50, minimum-idle=10, connection-timeout=3000，其中connection-timeout设短一些，宁可快速失败也不让用户长期挂起等待。

经过代码优化、SQL优化和连接池调参后的第二轮压测，平均响应时间降到约220ms，99分位约680ms，基本满足业务要求。整个压测过程暴露出一个问题：开发阶段过度只关注功能正确，很少关注并发吞吐量，但无人共享平台恰恰是把并发问题放在第一位的系统。

11.3 多实例部署时需要同步改的配置清单

如果服务从单实例扩到双实例，不只是部署脚本要改，还有几个基础设施要同步调整：

定时任务必须加分布式锁，避免两个节点同时执行超时订单扫描，重复处理同一个订单。
文件上传和图片存储不能放在本地磁盘，需要迁移到对象存储服务，否则用户请求会路由到不同节点，之前上传的图片可能404。
本地缓存Caffeine与Redis缓存双写要设计好失效策略，服务节点缓存不一致会给用户带来困扰。
日志系统要接入统一的收集平台，比如ELK，否则排查问题时要同时翻两台机器的日志文件，效率很低。
WebSocket长连接需要按节点分片管理跨节点消息转发，否则只连接其中一台机器的用户无法收到另一台机器推送的事件。

我在双节点部署后第一次半夜出问题时深刻体会到最后一条的重要性。当时节点A发生了FullGC，导致所有连接在节点A上的用户收不到还书成功通知，而管理后台看到的却是用户在线状态正常。后来把推送模块改成Redis Pub/Sub广播成功解决。

12. 异常补偿体系的设计与关键业务日志追踪

大量踩坑之后我沉淀出一条经验：无人共享系统的核心不是把主流程写得多完美，而是异常发生之后能不能自动恢复，不能自动恢复的能不能快速定位。基于这个思路，我为每个核心业务动作增加了操作流水表，类似事件溯源的思想。每次订单状态变更、格子状态变更、信用分变更都插入一条流水记录，字段包括业务类型、业务ID、变更前值、变更后值、操作人ID、操作时间、请求追踪ID。后续排查问题时，只需要根据订单号或格子ID查流水，整个链路基本一目了然。

还书异常、支付回调失败、柜机状态上报丢失等场景，会有定时补偿任务扫描未完成的业务动作并重新触发。比如支付回调没有成功时，订单停留在待支付状态，每5分钟触发一次重查支付网关接口以确认支付结果。所有的重试都带有最大次数限制和执行间隔退避策略，避免补偿任务本身成为新的故障源。

日志这块我统一使用了@TraceLog注解切面，在关键接口上自动打印入参、出参和耗时。压测和排查问题期间，这个注解带来的收益超出预期。一次现场用户反馈"已经还书但订单仍显示借出中"，我看流水发现柜机上报关门事件的服务端时间比实际值晚了20分钟，导致超时任务误判用户未还书而触发催还通知。日志中的时间戳帮了大忙，否则这类问题要排查很久。

提示：日志只打印必要信息，绝对不要打印完整的用户手机号、身份证号等敏感数据。借阅场景会涉及用户的个人位置和行为数据，上线前最好做一次脱敏改造。

13. 写在最后的几点务实总结

这个项目从需求梳理到稳定上线前后迭代了一个多月，中间经历了死锁、掉线、超时误判、数据不一致等一串问题。说实话，每次都挺折腾的，但也正因为这些问题，我对无人值守类系统的理解比单纯看技术文档要深得多。如果你准备照着做或者正在做类似项目，有几个建议直接给到：

第一，优先把状态机、流水表、幂等机制和分布式锁先设计好再写业务代码。这四块是无人共享系统的地基，后续所有业务逻辑都会在它们之上叠加，地基不稳后面全是补洞。

第二，物理设备的不可靠性要在一开始就计入设计预期。柜机掉线、传感器误报、时间不同步都不是小概率事件，后端必须把它们当常态处理，做超时重试、异常上报和人工兜底，而不是假设设备永远在线。

第三，数据库的并发控制一定在写SQL时就考虑好。同一个资源（书格、图书副本）的并发更新，不仅要靠分布式锁，数据库的条件更新和乐观锁必须双保险。只做应用层锁一旦锁漏了，数据库层会出大乱子。

最后，把这个项目当作一次完整的工程实践，而不是单独的CRUD练习。把自己的代码当成长期要维护的产品来写，把异常场景当成正常功能来设计，锻炼出来的能力跟只做增删改查完全不在一个层级。希望这篇源码实战记录对你有点帮助，照着思路做一遍，再踩出你自己的坑，你会有比我更深刻的体会。

无人共享图书借阅平台Java实战：分布式锁与状态机踩坑全记录