【苍穹外卖 day10｜Spring Task、WebSocket 与来单提醒、催单铃声实现】

前言订单系统里有两类事情很容易被忽略一类是到了时间必须处理的超时订单另一类是商家页面需要立刻收到的来单和催单消息。前者适合交给 Spring Task后者适合通过 WebSocket 推送到管理端。这一篇结合苍穹外卖的订单代码整理 Spring Task 的定时处理、WebSocket 的连接与群发以及管理端根据消息类型播放来单/催单铃声的实现。一、Spring Task让订单状态按时间自动推进Spring Task 是 Spring 提供的任务调度能力。给方法加上 Scheduled并在应用中开启调度后Spring 会按设定的时间规则调用该方法。当前 Spring 文档中周期任务可以使用 cron、fixedRate 或 fixedDelay 三种方式之一被调度的方法不能声明参数通常返回 void。项目中处理订单超时的场景需要按日历时间触发使用 cron 更直观。1. 开启任务调度项目启动类已经开启了定时任务能力SpringBootApplicationEnableTransactionManagementEnableCachingEnableSchedulingpublicclassSkyApplication{publicstaticvoidmain(String[]args){SpringApplication.run(SkyApplication.class,args);}}EnableScheduling 会注册对 Scheduled 的处理。没有这项配置即使任务类和 cron 表达式都写好了方法也不会被调度执行。2. 看懂 cron 表达式Spring Task 常用 cron 由秒、分、时、日、月、周六个字段组成字段之间以空格分隔。项目里的两个表达式如下表达式含义使用位置0 * * * * ?每分钟的第 0 秒执行一次取消超时未支付订单0 1 * * * ?每天凌晨 1:00 执行一次处理长时间派送中的订单常见通配符可以这样记* 表示任意值? 表示该字段不指定值- 表示范围, 表示多个值/ 表示步长。例如 0/5 放在秒字段表示从第 0 秒开始每 5 秒触发一次。日和周两个字段通常不要同时写具体值。当前代码中的 ? 就是为了避免两个字段同时限定。3. 超时订单的定时处理订单任务类被 Spring 扫描为组件后定时器会调用其中的方法ComponentSlf4jpublicclassOrderTask{AutowiredprivateOrderMapperorderMapper;Scheduled(cron0 * * * * ?)publicvoidprocessOutOrder(){LocalDateTimetimeLocalDateTime.now().plusMinutes(-15);ListOrdersordersorderMapper.getBystatusAndOrderTimeLT(Orders.PENDING_PAYMENT,time);if(orders!null!orders.isEmpty()){for(Ordersorder:orders){order.setStatus(Orders.CANCELLED);order.setCancelReason(订单超时,自动取消);order.setCancelTime(LocalDateTime.now());orderMapper.update(order);}}}}这里的查询条件由两个部分组成订单状态必须是待支付订单创建时间必须早于当前时间减 15 分钟。查到后再更新状态、取消原因和取消时间。这样即使用户关闭了页面订单数据也能被后台任务兜底处理。另一段 processOutOrder3 使用每天凌晨一次的规则查询派送中且超过 60 分钟的订单并取消。具体的状态是否应取消、还是应完成需要以产品规则为准定时任务只负责在设定时间执行既定业务规则。4. 定时任务怎么验证开发阶段可以暂时把 cron 改成每 5 秒执行一次或者构造一条符合查询条件的测试订单。观察日志、订单状态和取消时间是否一同发生变化即可。验证完成后要恢复正式 cron避免高频扫描订单表。如果任务没有执行优先检查三处启动类是否存在 EnableScheduling、任务类是否被 Spring 扫描、cron 是否有 6 个字段且合法。二、WebSocket保持连接让服务端主动发消息HTTP 很适合“客户端发请求服务端返回响应”的业务例如提交订单、查询订单详情。但商家正在打开管理端页面时服务端不能等到下一次 HTTP 请求才告诉它有新订单。WebSocket 建立握手后会保留一条连接客户端和服务端都可以主动发送消息。因此它适合来单提醒、催单提醒、聊天和实时状态变化这类场景。它同样基于 TCP但需要处理断线、重连和在线连接管理不能替代普通的 HTTP 接口。1. 注册服务端端点项目已经引入 spring-boot-starter-websocket并通过配置类注册 ServerEndpointExporterConfigurationpublicclassWebSocketConfiguration{BeanpublicServerEndpointExporterserverEndpointExporter(){returnnewServerEndpointExporter();}}该 Bean 会注册使用 ServerEndpoint 标记的端点。当前项目的连接地址为 /ws/{sid}sid 用于区分浏览器会话。2. 管理在线会话并群发ComponentServerEndpoint(/ws/{sid})Slf4jpublicclassWebSocketServer{privatestaticMapString,SessionsessionMapnewConcurrentHashMap();OnOpenpublicvoidonOpen(Sessionsession,PathParam(sid)Stringsid){sessionMap.put(sid,session);}OnClosepublicvoidonClose(PathParam(sid)Stringsid){sessionMap.remove(sid);}publicvoidsendToAllClient(Stringmessage){for(Sessionsession:sessionMap.values()){try{session.getBasicRemote().sendText(message);}catch(Exceptione){log.error(WebSocket发送消息失败: {},e.getMessage());}}}}onOpen 在浏览器连接成功时保存 SessiononClose 在连接断开时删除 Session。sessionMap 使用 ConcurrentHashMap适合多个连接同时建立、关闭或推送的场景。sendToAllClient 遍历在线 Session 后调用 sendText把同一条文本消息推给当前在线的管理端。这里采用的是群发策略适合单门店、单后台账号或所有管理端都需要获知订单的练习场景。多门店或多角色系统应按门店 ID、员工 ID 等维度维护会话集合避免无关人员收到消息。三、支付成功后的来单提醒用户提交订单后真正应提醒商家的时机是支付成功、订单进入待接单状态。项目在 paySuccess 中完成状态更新后构造了一条 type1 的 WebSocket 消息publicvoidpaySuccess(StringoutTradeNo){OrdersordersDBorderMapper.getByNumber(outTradeNo);if(ordersDBnull){thrownewOrderBusinessException(MessageConstant.ORDER_NOT_FOUND);}OrdersordersOrders.builder().id(ordersDB.getId()).status(Orders.TO_BE_CONFIRMED).payStatus(Orders.PAID).checkoutTime(LocalDateTime.now()).build();orderMapper.update(orders);MapString,ObjectwebsocketMapnewHashMap();websocketMap.put(type,1);websocketMap.put(orderId,ordersDB.getId());websocketMap.put(content,订单号outTradeNo);webSocketServer.sendToAllClient(JSON.toJSONString(websocketMap));}消息字段的约定很简单type1 表示来单提醒orderId 方便管理端跳转订单详情content 用于弹窗或通知栏展示订单号。先更新订单状态再推送消息能避免管理端收到提醒后查询到旧状态。四、用户催单用 type2 区分提醒类别用户端催单接口为 GET /user/order/reminder/{id}。项目先根据订单 ID 查询订单再组装 type2 的消息并通过同一个 WebSocket 服务群发GetMapping(/reminder/{id})publicResultreminder(PathVariableLongid){OrdersorderorderMapper.getById(id);if(orderService.orderDetail(id)null){thrownewOrderBusinessException(MessageConstant.ORDER_STATUS_ERROR);}MapString,ObjectmapnewHashMap();map.put(type,2);map.put(orderId,id);map.put(content,订单号order.getNumber());webSocketServer.sendToAllClient(JSON.toJSONString(map));returnResult.success();}来单和催单复用一条长连接前端只需要根据 type 决定提示文案和铃声。这样比为每一种提醒再建一个 WebSocket 地址更容易维护。这段代码还应注意业务校验当前实现通过 orderDetail 判断订单是否存在。正式项目建议同时校验订单归属和可催单状态避免用户对不属于自己的订单或已完成订单发起提醒。五、管理端接收消息并播放不同铃声当前仓库只包含后端模块下面这段是管理端页面可以直接接入的客户端代码。将 order.mp3 和 reminder.mp3 放到管理端静态资源目录并按实际构建工具调整资源地址。constorderAudionewAudio(/audio/order.mp3);constreminderAudionewAudio(/audio/reminder.mp3);letsocket;functionconnectWebSocket(){constclientIdcrypto.randomUUID();socketnewWebSocket(ws://localhost:8080/ws/${clientId});socket.onopen(){console.log(WebSocket 已连接);};socket.onmessage(event){constmessageJSON.parse(event.data);if(message.type1){orderAudio.currentTime0;orderAudio.play().catch((){console.warn(浏览器尚未允许自动播放请先点击页面一次);});showNotice(您有新的订单${message.content});return;}if(message.type2){reminderAudio.currentTime0;reminderAudio.play().catch((){console.warn(浏览器尚未允许自动播放请先点击页面一次);});showNotice(用户正在催单${message.content});}};socket.onclose(){setTimeout(connectWebSocket,3000);};}connectWebSocket();functionshowNotice(text){// 替换为管理端实际的 Message、Notification 或弹窗组件console.log(text);}message.type 是服务端约定的消息类型type1 播放来单铃声type2 播放催单铃声。每次播放前把 currentTime 设为 0连续来单时铃声会从头开始。浏览器通常会拦截没有用户交互时的音频自动播放。因此管理端登录成功或首次进入订单页后应让用户主动点击一次“开启提醒”按钮在点击事件中调用一次 orderAudio.play() 后马上 pause() 并归零浏览器便会把后续音频播放视为已授权。生产环境还应将 ws:// 根据 HTTPS 部署切换为 wss://否则浏览器会拦截混合内容。六、从下单到铃声响起的调用链整个来单提醒链路可以按下面顺序排查用户支付成功 - OrderServiceImpl.paySuccess 更新订单为待接单、已支付 - 组装 type1 的 JSON 消息 - WebSocketServer.sendToAllClient 群发 - 管理端 socket.onmessage 接收 - 播放 order.mp3 并展示来单通知 用户点击催单 - GET /user/order/reminder/{id} - 组装 type2 的 JSON 消息 - WebSocketServer.sendToAllClient 群发 - 管理端播放 reminder.mp3 并展示催单通知排查时先打开管理端浏览器控制台确认 WebSocket 是否连接成功再确认服务端日志中的在线客户端数是否大于 0最后检查推送的 JSON 是否包含正确的 type 和 orderId。若消息已到达但没有声音优先检查音频文件地址和浏览器自动播放权限。总结这一部分把订单的两种后台能力接起来了Spring Task 负责按时间扫描并修正订单状态WebSocket 负责把支付成功和用户催单实时送到管理端。通过 type1 与 type2 区分消息类型管理端就能播放不同铃声并给出对应的订单提示。