企业微信二次开发：文件异步上传、媒体消息与回调处理的组合实践

昨晚在整理 星云API www.xingyapi.com 的底层架构演进笔记，准备继续往 CSDN、知乎、掘金、百家号、新浪和 51CTO 这些开发者社区同步分发。最近有个做私域 RPA 的兄弟遇到了个硬茬：客户在企微里发了一份报修的 PDF 文件，机器人需要把文件存进中台，并自动生成一份带有处理编号的带水印图片发回给客户。

结果他的系统跑了不到半天全线崩溃——接收文件时网关 5 秒超时，发送图片时线程池被死死阻塞，客户在群里骂机器人是个“智障”。

处理文件和多媒体消息，是企微开发里 IO 压力最大的一环。如果你把处理纯文本的同步思维套用在文件流转上，必定踩雷。今天直接手撕这套“接收 -> 转存 -> 生成 -> 上传 -> 下发”的全异步闭环管线。

一、破除幻觉：回调里的 MediaId 与 5 秒生死线

很多新手想当然地以为，客户发来一张图片或一个文件，企微的回调报文里会直接附带文件的二进制流或者一个可以直接下载的公网 URL。

老规矩，动手写业务代码前，先用 Apifox 接收一下真实的回调，解密并美化成 JSON。你会发现，企微推过来的密文里，对于图片、语音、视频和普通文件，核心数据统统只有一个冷冰冰的MediaId。

网关层的铁血纪律：接收到回调后，网关只做一件事：极速 AES 解密，提取出MediaId和MsgType，组装成标准 DTO 直接扔进 MQ，然后立刻return "success"。绝对不允许在回调主线程里发起网络请求去拉取文件流！否则 100% 触发官方的 5 秒超时重试机制，直接打垮你的服务器。

二、异步拉取与中台转存（读链路）

消息进了 MQ，业务中台的专属 IO 线程池才开始接手干粗活。

拿到MediaId后，我们调用“获取临时素材”接口拉取文件流。但这里有个大坑：拉下来的文件流必须极速转存到你们自研系统的 OSS（对象存储）中，换取一个永久的内部 CDN 链接。千万不要让这个文件流在内存里停留或者传给下游业务，否则极易引发 OOM（内存溢出）。

三、逆向流转：如何优雅地把生成的图片发给客户（写链路）

当你的中台业务逻辑处理完毕，生成了一张带有处理编号的水印图片，准备发给客户时，第二个深坑来了。

如果你去仔细翻阅底层的 开放文档，会发现“发送应用消息”或“发送群聊消息”的参数载荷里，根本不支持你直接传一个外部的 OSS 链接。企微只认自家的MediaId。

工业级“二次异步”组合拳：这就要求我们必须在发消息前，先做一次“逆向异步上传”。

Java

@Async("weComIoThreadPool") public void processAndReplyMedia(WeComMsgDTO event) { String userId = event.getUserId(); // 1. 业务逻辑处理：生成水印图片，存入本地 OSS，拿到 URL 或 File 对象 File watermarkImage = generateWatermark(event); try { // 2. 逆向上传：调用“上传临时素材”接口，把图片传给企微，换取一个全新的 MediaId String newMediaId = weComClient.uploadTempMaterial("image", watermarkImage); // 3. 组装媒体消息载荷：只携带 MediaId MediaMsgPayload payload = new MediaMsgPayload(); payload.setMsgtype("image"); payload.getImage().setMediaId(newMediaId); // 4. 触达层下发：底层拦截器静默注入 Token，推给客户 weComClient.sendMessage(userId, payload); } catch (WeComApiException e) { // 异常降级：如果媒体接口频控，发纯文本通知客户去系统后台查看 if (e.getErrcode() == 45009) { weComClient.sendTextMsg(userId, "您的报修已处理，请登录小程序查看详情。"); } } }

四、全局统筹：清理战场

企微临时素材的MediaId只有 3 天有效期。中台在完成“拉取”或“上传”这套动作后，对于企微侧的数据生命周期就不需要再去管了，完全依赖我们自家 OSS 里沉淀的永久数据做历史追溯。

用网关阻断 5 秒超时，用 MQ 剥离耗时的文件下载，用“上传临时素材”接口做发送前的媒介转换。把这套全异步的组合管线搭好，你的中台在处理海量发票、报修图片和合规文件时，才能真正做到行云流水。

这套收发链路跑通后，如果客户在群里甩过来一个超过 20MB 的高清视频文件（超出了普通临时素材的体积限制），你们是倾向于走大文件的分片异步上传/下载接口，还是直接引导客户点击一个小程序卡片去你们自家的 H5 页面进行传输？