Spring Boot + NATS 实战：如何让 IM 系统处理图片/视频像处理文本一样快？

摘要：在对接第三方 IM（如企业微信、WhatsApp）时，文本消息通常能毫秒级响应，但一旦涉及图片、语音或视频等多媒体文件，系统吞吐量往往会急剧下降，甚至引发消息积压和应用崩溃。本文介绍一种基于 "信令与媒体分离" 的架构优化方案，通过 预计算路径 、乐观 UI 策略 和 NATS 异步搬运，将重 I/O 操作从主链路中剥离，实现 IM 消息的"秒发秒收"体验。

1. 引言：被"多媒体"拖累的即时通讯

在即时通讯（IM）系统的开发中，对接第三方渠道（例如本案例中的"3-chat"）是常见需求。对于普通的文本消息，处理流程相对简单：接收、存储、推送，整个过程通常在几十毫秒内完成。

然而，当消息类型转变为图片、语音或视频时，情况会发生显著变化。第三方平台通常仅提供一个临时的下载 URL。传统的同步处理模式如下：

收到消息 URL。
下载文件（可能耗时几百毫秒甚至几秒）。
上传到私有 OSS（再次耗时几百毫秒）。
将最终的 OSS URL 存入数据库。
推送给客户端。

这种模式的主要弊端在于，耗时的网络 I/O（下载+上传）直接阻塞了业务主线程。若处理一个视频文件耗时 5 秒，该线程即被挂起 5 秒。在高并发场景下，线程池会迅速耗尽，导致后续所有消息（包括轻量级的文本消息）出现严重延迟。

为了突破这一瓶颈，引入 "信令与媒体分离" (Signaling & Media Separation) 的设计思想至关重要。其核心在于将"消息通知"（快链路）和"文件搬运"（慢链路）拆分为两条独立的路径。

2. 核心方案：预计算与乐观 UI (Optimistic Strategy)

优化目标是使 API 接口在接收到多媒体消息后，能像处理文本消息一样立即返回。这依赖于两个关键策略：

2.1 预计算确定性路径

在传统模式中，必须等待文件上传至 OSS 后才能获取最终 URL。但实际上，根据消息的元数据（如 SessionID、MessageID、文件类型），可以提前按规则生成一个确定性的、唯一的 OSS 路径。

传统模式：上传 -> 等待 OSS 返回 URL -> 存库。
优化模式 ：本地预生成 URL -> 存库 -> 异步上传到该位置。

2.2 乐观 UI 与状态流转

基于预先生成的 URL，系统可以在文件上传完成前，先将消息推送至前端。为防止前端加载出现 404 错误，需引入状态机机制。

消息体中增加 mediaStatus 字段：

**pending**：初始状态。表示地址已生成，但文件正在搬运中。
**ready**：终态。表示文件已成功上传到 OSS，可正常访问。
**failed**：终态。表示搬运失败（如原链接失效）。

架构图解

**Fast Path (主链路)**：计算路径 -> 落库(Pending) -> 发送 MQ -> 立即结束。
**Slow Path (异步链路)**：监听 MQ -> 流式搬运文件 -> 更新数据库状态(Ready)。

3. 代码实战：三步走实现"秒发"体验

以下结合 Spring Boot 和 NATS 环境，展示该架构的具体实现。

3.1 第一步：生产者 ------ 确定性路径与任务分发

在消息接收入口，不再执行耗时的下载操作，而是快速生成"预案"并分发任务。

复制代码

// 代码位置：消息接收服务中处理多媒体消息的方法
private void transferMediaFiles(ChatMessage msg, Long sessionId) {
  // ... 省略部分判断逻辑 ...
  case PICTURE -> {
    WxPicturePayload picturePayload = (WxPicturePayload) payload;
    String originalUrl = picturePayload.getImageUrl();
    // 1. 确定性路径生成：提前"预知"文件最终地址，无需等待 OSS
    String fileName = "wx/image/" + messageId + getFileExtension(originalUrl, ".jpg");
    String expectedUrl = rustFSService.generateExpectedUrl(fileName);

    // 2. 状态标记与乐观UI：设置预期URL并将状态标记为 pending
    picturePayload.setImageUrl(expectedUrl);
    picturePayload.setMediaStatus("pending");

    // 3. 非阻塞投递：构建轻量级任务，推送到 NATS 后即刻返回
    MediaTransferTask task = MediaTransferTask.builder()
      .sessionId(sessionId) // 重要：传递 sessionId 用于后续精确查询
      .messageId(messageId)
      .originalUrl(originalUrl)
      // ... 其他参数
      .build();
    mediaTransferPublisher.publishMediaTransfer(task);
    
    log.debug("Picture transfer task published: {} -> {}", originalUrl, expectedUrl);
  }
  // ... 其他类型处理类似 ...
}

该处理方式将主线程的耗时压缩至仅包含几次内存操作和一次 NATS 发布操作，通常在毫秒级别。

3.2 第二步：中间件 ------ NATS JetStream 的可靠保障

媒体文件属于重要数据，必须防止丢失。使用 NATS JetStream 可确保任务的可靠投递。

复制代码

@Slf4j
@Component
@RequiredArgsConstructor
public class MediaTransferListener implements NatsConsumer {
  
  // 开启 JetStream 支持，确保 At-Least-Once 语义
  @Override
  public boolean isJetStreamConsumer() {
    return true;
  }

  @Override
  public void onMessage(Message message) {
    MediaTransferTask task = ConvertUtils.convertObject(new String(message.getData()), MediaTransferTask.class);
    // ... 解析校验 ...

    // 执行搬运
    boolean success = mediaTransferService.transferMedia(task);

    if (success) {
      // 搬运成功，确认消费
      message.ack();
    } else {
      // 搬运失败（如网络抖动），拒绝消息，触发 NATS 的自动重试机制
      log.error("Media transfer failed, NAKing message for retry");
      message.nak();
    }
  }
}

3.3 第三步：消费者 ------ 高效搬运与状态翻转

消费者负责执行繁重的 I/O 工作，并在完成后更新数据库状态。

复制代码

@Slf4j
@Service
@RequiredArgsConstructor
public class MediaTransferService {

  // ... 注入 Repository 和 Storage Service ...

  public boolean transferMedia(MediaTransferTask task) {
    // 1. 流式传输 (Streaming Transfer)
    // 采用流对接方式（InputPipe -> OutputPipe），避免将大文件加载到内存中导致 OOM
    String newUrl = rustFSService.transferFromUrl(
      task.getOriginalUrl(), task.getFileName(), task.getContentType());

    String status = newUrl != null ? "ready" : "failed";
    
    // 2. 状态翻转
    updateMediaStatus(task.getSessionId(), task.getMessageId(), task.getMessageType(), status);
    return newUrl != null;
  }

  private void updateMediaStatus(Long sessionId, String messageId, WxMessageType messageType, String status) {
    try {
      // 精准定位：利用 sessionId 和 messageId 联合索引进行 O(1) 查询
      Optional<WxMessage> messageOpt = messageRepository.findBySessionIdAndWxid(sessionId, messageId);
      
      if (messageOpt.isPresent()) {
          WxMessage message = messageOpt.get();
          // ... 反序列化 Payload，更新状态为 ready/failed，再序列化 ...
          messageRepository.save(message);
          log.info("Media status updated to: {}", status);
      }
    } catch (Exception e) {
      log.error("Failed to update media status", e);
    }
  }
}

4. 用户体验闭环：前端交互与乐观 UI 适配

为了将后端的"异步架构"转化为用户感知的"极致快"，前端的配合至关重要。需要在前端实现一套完整的状态流转机制，以保证最佳的用户体验：

本地占位（零延迟反馈） 当客户端点击发送后，立刻在聊天窗口插入一条消息气泡。此时不要等待服务器返回 URL，而是直接显示本地选中的图片（Local Blob/File），或者显示一个模糊的缩略图配上 Loading 转圈动画。此时消息状态对应后端的 pending。
状态静默同步 后端 Worker 完成文件搬运并将数据库状态更新为 ready 后，通过 WebSocket（或长轮询）向前端发送一条轻量级的 MessageStatusChanged 事件。
无感平滑切换 前端收到通知后，通过 img 标签的 src 替换，将本地占位图悄无声息地替换为云端的真实 imageUrl。由于图片内容一致，用户几乎感知不到闪烁，只看到 Loading 动画结束，整个过程流畅自然。

5. 总结

通过实施"信令与媒体分离"架构，重 I/O 操作成功从主业务链路中剥离。

系统层面：API 接口响应时间从秒级降至毫秒级，系统抗压能力显著提升，NATS 发挥了关键的削峰填谷作用。
用户体验层面：图片发送不再卡顿，交互更加流畅。尽管图片完全显示仍需时间，但"即时响应"的反馈为用户提供了极大的确定性。

这种异步化、最终一致性的设计思路，不仅适用于 IM 系统，对于任何涉及第三方资源转存或重型计算的场景均具有重要的参考价值。