上周有个做测试平台的朋友来问我他们流水线跑完自动化用例之后allure 报告和打包好的 jar 想自动丢到测试群里让大家第一时间看到结果问我有没有什么省事的做法。我第一反应就是企业微信的群机器人——不用申请自建应用不用配可信 IP不用管 access_token 的刷新逻辑一个 Webhook 地址就能把消息推到群里。但真动手写的时候会发现发文本一句话就完事发文件就没那么直白了中间横着一个“素材上传换 media_id”的步骤很多人卡在 media_id 过期、文件超过 20MB、multipart 边界处理这些细节上。这篇就聊聊我用 Spring Boot 做这件事的完整思路从群机器人的能力边界到上传接口的参数含义再到工程里怎么封装成一个能复用的客户端最后把我踩过的坑和排查表一并交代清楚。适合手上有 Spring Boot 项目、想给团队做构建通知或报告推送的同学也适合刚开始接触企业微信开放接口、想搞明白 media_id 这套机制的人。代码基本都是可以复制粘贴改改就能跑的我会标清楚每个参数为什么这么设。1. 需求拆解与整体方案设计1.1 先搞清楚群机器人到底能发什么动手写代码之前我建议你先花五分钟把群机器人的消息类型捋一遍这一步省不得。企业微信群机器人本质是一个 Webhook 接收端你 POST 一段 JSON 过去它负责渲染到群里支持的类型有文本 text、markdown、图片 image、图文 news、文件 file、语音 voice、模板卡片 template_card。注意这里有个非常容易误判的点image 和 file 类型要求的不是二进制内容而是 media_id也就是说你没法直接把图片字节塞进 JSON 发出去必须先调一次“上传素材”接口把文件传上去拿到一个叫 media_id 的字符串凭证再拿这个凭证去发消息。这个设计和公众号素材库的思路是一模一样的我个人的理解是它要控制消息体大小同时给文件内容做一次缓存复用。文本消息你甚至可以塞几千字进去但一个 10MB 的文件如果直接走 JSON 的 body网关那一层就扛不住了。所以群机器人把“内容传输”和“消息通知”拆成了两步理解了这个前提后面所有代码结构就顺了。顺带说一句很多同学搜到的是“企业微信发送应用消息”那套接口那是自建应用的能力需要 corpId、corpSecret、agentId 三件套还要配置可信 IP接口地址和群机器人完全不是一回事。这两套东西经常被混为一谈我在群里见过太多次有人拿着应用的 access_token 去调群机器人的接口然后报 40001。判断方法很简单URL 里带webhook/send和key的是群机器人带message/send和access_token的是应用消息。1.2 为什么我优先推荐 Webhook 而不是自建应用从工程成本看群机器人几乎是零门槛。你只需要在群聊里点右上角添加群机器人拿到一串类似xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx的 key拼到https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key后面就能用。没有 token 过期问题没有 IP 白名单问题不需要企业管理员审批一个普通的群成员就能创建。对于“构建完成通知”“日报推送”“告警上报”这类场景它完全够用。自建应用的优势在于能定向发给个人、能接收用户回复、能做更复杂的交互但代价是要走审批、要维护 token 刷新、要处理 IP 变更。我一般的判断标准是如果只是单向地把信息推到某个群里用群机器人如果需要和具体的人做双向交互才考虑自建应用。这个项目标题里明确说了“群机器人”所以我们整条链路都围绕 Webhook 来走不引入 access_token 那一套。不过这里要提醒一句群机器人的 key 等同于密码谁拿到都能往群里发消息。所以我在项目里从来不把 key 硬编码进代码一律走配置中心或者环境变量本地开发用一个单独的测试群 key别拿生产群的 key 在本地乱试我之前就因为调试频率太高触发过限流消息延迟了几分钟才到排查了半天。1.3 整条链路怎么设计才不至于写成一坨把链路拆开看其实就四步读取本地文件、调用上传素材接口拿到 media_id、拿 media_id 组装 file 消息体、调 send 接口发出去。前两步是“传”后两步是“发”。我的做法是把上传和发送封装到同一个客户端类里对外只暴露一个sendFile(File file)方法调用方不需要知道 media_id 这回事这样以后要加图片、加 markdown 通知扩展起来也清爽。再往上一层我会把它挂到一个异步线程池里执行因为上传一个大文件加发消息加起来可能要一两秒如果放在主业务线程或者定时任务线程里同步执行会把整个流程拖慢。构建通知这种场景晚半秒没人介意但卡住主流程就是事故。所以整个设计的核心关键词是单一职责、异步解耦、配置外置、失败可重试。工程结构上我一般这么分一个WeComRobotProperties承载配置一个WeComRobotClient负责实际请求一个FileUploadResult之类的 DTO 接返回再加上一个AsyncConfig定义线程池。文件不大的话甚至不需要引入任何额外的 HTTP 客户端Spring 自带的 RestTemplate 就够用了这也是我下面演示方案的基础。2. 核心原理与关键参数拆解2.1 上传素材接口的机制与 media_id 的生命周期上传素材的接口是POST https://qyapi.weixin.qq.com/cgi-bin/webhook/upload_media?keyKEYtypefile请求体是multipart/form-data表单字段名固定叫media值是文件本身。type参数目前群机器人支持file和image两种发文件就用 file。返回体是 JSON结构大致是{errcode:0,errmsg:ok,type:file,media_id:...,created_at:1690000000}你只需要取 media_id 字段。这里最关键的参数是 media_id 的有效期官方说明是 3 天。这个数字经常被误解成“消息发出去 3 天内有效”其实不是它指的是这个 media_id 本身 3 天后就作废了你用同一个 media_id 去 send 接口发消息如果在有效期内可以重复发多次超过 3 天再发就报 media_id 无效。我做过一个不太严谨的小测试第一天上传的 media_id当天重复发送没问题到第四天再去发直接返回 errcode 40007 之类的错误。所以我的实践建议是上传和发送尽量在同一个方法里紧挨着完成不要想着提前上传一堆素材存到数据库里慢慢用除非你确实验证过时间窗口。还有一个隐藏知识点同一个文件内容重复上传企业微信似乎会做去重返回的可能是同一个 media_id。这个我没有做严格的对照实验但从日志观察来看相同文件的 media_id 确实有重复出现的情况。不过我从来不依赖这个行为来做业务逻辑只把它当作一个可能的优化代码里该上传还是老实上传。2.2 文件消息体的字段构成与常见写错的地方拿到 media_id 之后发消息的接口是POST https://qyapi.weixin.qq.com/cgi-bin/webhook/send?keyKEYbody 是 JSON{ msgtype: file, file: { media_id: MEDIA_ID } }就这么简单但恰恰是这几行最容易写错。第一个坑是 msgtype 的值和字段名必须一致msgtype是file那么下面的 key 也必须是file写成fileMsg或者file_info都会报参数错误。第二个坑是 media_id 的类型必须是字符串有的人从 JSON 里取出来用了数字类型的解析器把一长串数字当 int/long 处理精度丢失之后就废了所以 DTO 里一定用 String 接。第三个坑是上传时 type 填了 image发送时却用了 file 消息体这种跨类型的错配也会报错两个地方的 type 要对上。另外提一句群机器人的 send 接口返回体里只有 errcode 和 errmsg没有消息 ID 之类的东西所以你判断成功与否就看 errcode 是不是 0。有些同学问“企业微信发送文件怎么确认发送是否成功”答案就在这个返回码上0 表示服务端已接收并投递非 0 就按错误码查表。注意它不代表对方已经“看到”只代表投递成功这个心理预期要摆正。2.3 文件大小、类型与频率限制的实测数据这部分是我踩坑最多的地方直接上表格比讲一堆话管用限制项官方/实测值说明与应对单文件大小5B ~ 20MB下限其实可忽略上限 20MB 是硬杠超了直接报错上传素材 typefile / image群机器人不支持 voice、video别拿应用那套文档套media_id 有效期3 天上传后尽快发送别囤发消息频率每分钟 20 条超过会限流批量推送要加节流请求方式必须 POSTGET 会返回 404 或不支持的提示字符编码UTF-8中文文件名要处理编码否则可能乱码20MB 这个上限我个人觉得对构建通知场景是完全够用的jar 包一般也就几十兆如果真超了要么用分片思路下面第 5 章会讲要么干脆只发个下载链接把文件放对象存储里。频率限制那个每分钟 20 条是容易被忽略的我做告警聚合的时候有一次因为一个循环里连着发了三十多条后面几条直接被限流丢了后来老老实实加了一个令牌桶限流才稳定下来。文件类型方面群机器人上传素材对扩展名没有特别严格的强制校验但微信客户端能不能正常预览预览是另一回事。我发过.jar、.zip、.xlsx、.pdf都没问题都以下载附件的形式呈现。这里有个小细节文件名是你在 multipart 里带的那个 filename客户端展示的就是它所以上传时要保证文件名是完整带扩展名的别只传个纯数字名字不然群里下载下来都不知道是什么。3. 从零落地Spring Boot 工程实操3.1 依赖与配置该怎么放先说依赖最小集合只需要spring-boot-starter-web因为 RestTemplate 和 multipart 转换器都在里面。如果你团队习惯用 OkHttp 或者 WebClient 也可以我下面用 RestTemplate 演示因为它的 multipart 支持开箱即用改动最少。如果想省事还可以引spring-boot-configuration-processor让 IDE 有配置提示这个属于锦上添花。配置我全部放到application.yml里并且做了配置类绑定这样切换测试群和生产群只改配置不改代码wecom: robot: webhook-key: your-webhook-key-here upload-url: https://qyapi.weixin.qq.com/cgi-bin/webhook/upload_media send-url: https://qyapi.weixin.qq.com/cgi-bin/webhook/send connect-timeout: 5000 read-timeout: 30000 max-file-size: 20971520这里我把 max-file-size 显式写成 20971520也就是 20MB 的字节数不是用来做校验上限的而是在上传前自己先拦一道避免把 30MB 的文件白白传上去再被服务端拒绝浪费带宽和时间。超时时间我给的是连接 5 秒、读取 30 秒因为上传大文件读响应会比较慢读取超时设太短容易在网络抖动时误判失败。配置类长这样Data Component ConfigurationProperties(prefix wecom.robot) public class WeComRobotProperties { private String webhookKey; private String uploadUrl; private String sendUrl; private int connectTimeout 5000; private int readTimeout 30000; private long maxFileSize 20971520L; }用ConfigurationProperties而不是到处Value是因为后面要加字段的时候只改一个地方工程里也不会散落一堆魔法字符串。这是我在好几个项目里养成的习惯配置集中管理出问题的时候定位快。3.2 用 RestTemplate 处理 multipart 上传上传这一步是整个流程里最容易出错的地方。我的做法是构造一个LinkedMultiValueMap把文件包装成FileSystemResource放进去字段名严格用mediapublic String uploadFile(File file) { if (file.length() properties.getMaxFileSize()) { throw new IllegalArgumentException(文件超过 20MB 上限); } MultiValueMapString, Object body new LinkedMultiValueMap(); body.add(media, new FileSystemResource(file)); HttpHeaders headers new HttpHeaders(); headers.setContentType(MediaType.MULTIPART_FORM_DATA); HttpEntityMultiValueMapString, Object request new HttpEntity(body, headers); String url UriComponentsBuilder.fromHttpUrl(properties.getUploadUrl()) .queryParam(key, properties.getWebhookKey()) .queryParam(type, file) .build().toUriString(); ResponseEntityUploadResult resp restTemplate.postForEntity(url, request, UploadResult.class); UploadResult result resp.getBody(); if (result null || result.getErrcode() null || result.getErrcode() ! 0) { throw new RuntimeException(素材上传失败: result); } return result.getMediaId(); }几个关键点解释一下。第一FileSystemResource会自动从文件路径推断出 filename 和 content-type一般够用但如果你要发一个.jar文件而 Spring 的 media type 推断器不认这个扩展名它可能会退化成application/octet-stream这通常不影响上传因为服务端要的是字节而不是 content-type。第二URL 上的 key 和 type 参数我用了UriComponentsBuilder好处是它会帮你做 URL 编码避免 key 里出现特殊字符时拼错。第三这一层我把返回结果做了解包并抛异常调用方不用关心 errcode。这里要特别说一个我踩过的坑中文文件名。如果文件名里有中文某些环境下 multipart 编码会产生乱码群里显示成问号。解决办法是给FormHttpMessageConverter显式设置 UTF-8或者干脆把上传时的文件名改成拼音/英文展示层再去补充说明。我个人倾向于第二种简单直接省得和编码较劲。3.3 发送文件消息与客户端统一封装发送这一步就简单多了构造一个 Map 转 JSON 即可但要注意msgtype、file、media_id三者对齐public void sendFileByMediaId(String mediaId) { MapString, Object fileNode new HashMap(); fileNode.put(media_id, mediaId); MapString, Object payload new HashMap(); payload.put(msgtype, file); payload.put(file, fileNode); String url UriComponentsBuilder.fromHttpUrl(properties.getSendUrl()) .queryParam(key, properties.getWebhookKey()) .build().toUriString(); HttpHeaders headers new HttpHeaders(); headers.setContentType(MediaType.APPLICATION_JSON); HttpEntityMapString, Object request new HttpEntity(payload, headers); ResponseEntitySendResult resp restTemplate.postForEntity(url, request, SendResult.class); SendResult result resp.getBody(); if (result null || result.getErrcode() null || result.getErrcode() ! 0) { throw new RuntimeException(文件消息发送失败: result); } }然后把它俩串起来对外只给一个方法public void sendFile(File file) { String mediaId uploadFile(file); sendFileByMediaId(mediaId); } public void sendFile(byte[] bytes, String fileName) { // 用 ByteArrayResource 重写 getFilename避免临时文件 ByteArrayResource resource new ByteArrayResource(bytes) { Override public String getFilename() { return fileName; } }; // 后续同 uploadFile只是把 FileSystemResource 换成 resource }为什么要提供byte[]版本因为很多场景下文件并不在本地磁盘上而是从数据库或者上游接口拿到的字节流。用ByteArrayResource匿名类重写getFilename是一个经典技巧因为ByteArrayResource默认返回 null而 multipart 需要文件名。这个小细节我卡过半小时报错信息还特别模糊后来翻源码才发现的。还有一点RestTemplate 默认用的是 JDK 自带的SimpleClientHttpRequestFactory它处理 multipart 时偶尔会有边界问题我的经验是如果需要发稍大的文件换成HttpComponentsClientHttpRequestFactory基于 Apache HttpClient更稳连接复用也更好。这属于稳定性上的取舍小文件用默认的没毛病。3.4 异步执行与失败重试的安排前面提过上传加发送整体是耗时操作我会把它放到自定义线程池里异步跑。线程池参数别用默认的Executors.newFixedThreadPool这种隐式无界队列的写法在生产环境是有风险的我一般显式声明Configuration EnableAsync public class AsyncConfig { Bean(wecomExecutor) public ThreadPoolTaskExecutor wecomExecutor() { ThreadPoolTaskExecutor executor new ThreadPoolTaskExecutor(); executor.setCorePoolSize(2); executor.setMaxPoolSize(4); executor.setQueueCapacity(200); executor.setThreadNamePrefix(wecom-); executor.setRejectedExecutionHandler(new ThreadPoolExecutor.CallerRunsPolicy()); executor.initialize(); return executor; } }这里我用CallerRunsPolicy而不是丢弃策略因为在构建通知这种场景下宁可稍微拖慢调用方也不要把通知悄悄丢了。核心线程数设小是因为这个任务本身不是高并发场景两个线程足够队列容量给大一点缓冲突发。重试方面我倾向于只对“超时”和“5xx”这类瞬时失败做重试重试次数 2 到 3 次退避间隔用 1 秒、2 秒、4 秒这种指数形式。注意千万别对“文件超过 20MB”“errcode 40007 media_id 无效”这类确定性错误重试重试一百次也没用只会刷日志。我见过有同学写了个无脑重试结果限流限得更狠得不偿失。3.5 完整调用示例与本地验证把上面拼起来在业务里调用就一行Resource private WeComRobotClient robotClient; Async(wecomExecutor) public void notifyBuildDone(Path jarPath) { try { robotClient.sendFile(jarPath.toFile()); } catch (Exception e) { log.error(构建产物推送失败, e); } }本地怎么验证我的建议是先在测试群里发一个几 KB 的小文本文件确认能收到再逐步换成真实大小的文件。不要一上来就拿 18MB 的包试因为一旦失败你分不清是代码问题还是网络问题。验证顺序我的习惯是文本消息 → 小文件 → 真实文件 → 异步环境。每步都看日志里的 errcode心里才有底。另外有个小技巧本地调试时可以在上传完拿到 mediaId 之后先把它打日志出来然后用 curl 手动调一次 send 接口确认这个 mediaId 是有效的。这样能把“上传问题”和“发送问题”彻底隔离排查效率至少翻倍。4. 踩坑实录与问题排查速查4.1 几个典型的报错和我的处理方式说到 errcode 93000 附近的错误最常见的几个我列一下。errcode 40001通常是 key 有问题或者拼错了检查 URL 里的 key 参数有没有多余空格errcode 40058一般是 msgtype 和字段名对不上回去看是不是 file 写成了别的errcode 40007我遇到两种触发场景一种是 media_id 真的过期了另一种是上传时 type 和发送时对不上比如上传类型是 image 却当成 file 发。区分方法是看日志里两次请求的 type 参数。还有一次印象比较深的是某次升级 Spring Boot 版本之后multipart 上传开始间歇性失败报的是 400 之类的错误。排查下来是新版对 multipart 的 boundary 处理更严格加上我用的是默认的SimpleClientHttpRequestFactory在某些文件名编码场景下边界字符串被污染了。换成 Apache HttpClient 的实现之后问题消失。所以我一直提醒身边人升级 Spring Boot 大版本之后一定要把这类 HTTP 相关的功能回归一遍别只看编译过没过。限流是另一个大坑。前面提过每分钟 20 条的上限我当时的场景是一个聚合告警一个批次里可能有几十条要发。最初的写法是 for 循环里直接发结果前 20 条成功后面的全被限流。后来我加了一个基于 Guava RateLimiter 的限流把速率控制在每秒 0.3 次左右稳定运行到现在。或者更简单的办法是把多条告警合并成一条 markdown 消息发一次既省额度又清爽这个思路我强烈推荐。4.2 常见问题速查表现象可能原因排查方向返回 40001key 错误或空格打印完整 URL 检查 key 参数返回 40058msgtype 与字段名不匹配确认 file 字段名是否为 file返回 40007media_id 过期或类型不符检查上传时间与 type 一致性文件收到但打不开上传时文件名缺扩展名用 FileSystemResource 或重写 getFilename中文文件名乱码multipart 编码非 UTF-8设置 converter 编码或改用英文名超过 20MB 报错服务端硬限制上传前本地校验并给出提示消息时有时无触发频率限制加限流或合并消息上传超时读取超时太短调大 readTimeout 到 30s本地能跑线上不行网络策略限制确认出网策略允许访问对应域名偶发边界错误默认请求工厂问题换 HttpComponents 实现这张表我建议打印出来贴在工位上遇到问题先扫一眼能省下大量搜索时间。很多问题本质上是同一类只是表现不同。5. 生产环境加固与后续可扩展方向5.1 文件超过 20MB 时的几种解法硬碰硬是不行的服务端限制摆在那。我的思路有三条。第一条是压缩构建产物里很多是可以压缩的比如图片、日志、报告压一压经常能掉到 20MB 以内。第二条是上传到对象存储拿一个预签名链接然后发一条 markdown 消息把链接贴出去用户点一下就下载这条路最通用也最适合大文件。第三条是分片如果确实需要推大文件只能切分成多个小文件分别上传发送接收方再合并但体验一般我很少用。我一般默认选第二条原因很简单对象存储的成本低、稳定、还能做权限和过期控制。群里收到的不再是一个死沉沉的附件而是一个干净的可点击链接从产品体验来说也更舒服。当然如果你所在的环境里没有对象存储那压缩加限制文件类型是更现实的选择。5.2 和构建流程结合起来才真正有价值单独发一个文件没什么意思真正有价值的是把它挂进 CI/CD 流程里。比如流水线跑完自动化测试之后把 allure 的 HTML 报告打成 zip推到群里或者打包完成后把 jar 推给测试同学。触发点可以是 Jenkins 的 post 步骤也可以是 GitLab CI 的 after_script甚至是本地写个脚本手动调用。核心逻辑都一样就是把生成的产物路径传给你的 Spring Boot 服务。这里有个实用的设计把发送能力包装成一个小小的 HTTP 接口比如POST /notify/file参数是文件路径和一个群标识构建脚本直接 curl 调用就行。这样构建侧完全不需要懂企业微信的接口细节解耦得很干净。我在好几个项目里都是这么搭的运维改脚本不用碰 Java 代码Java 侧改逻辑也不影响脚本。5.3 日志、监控和失败告知生产环境最怕的就是通知静默失败你以为发了其实没发出去等大家发现的时候已经误事了。所以我的做法是每次发送都打一条结构化日志包含文件名、大小、media_id 的前几位、errcode、耗时失败时除了重试还会往另一个“告警群”推一条文本消息说明哪个文件发送失败了。这就避免了“监控本身挂了没人知道”的经典问题。监控指标上我会记录发送成功率和平均耗时如果成功率掉下来或者某个时间段的失败集中出现通常意味着网络策略或者 key 出问题了。这些指标接入现有的监控系统就行不需要额外搭一套。说句实在话通知类功能一旦上线它的可用性就直接影响团队的信息流转值得花点心思做可观测性。我在实际使用中的体会是企业微信这套群机器人接口的稳定性和易用性都相当靠谱坑基本集中在 media_id 和文件大小这两个点上把这两块吃透剩下的就是工程封装的事。如果让我给新手一个建议那就是先用 curl 把上传和发送两个请求跑通确认链路没问题再动 Spring Boot 代码顺序反了容易在代码里绕圈。我踩过几次坑之后总结出来的经验就是接口先手工验证代码后批量封装日志从头到尾都别省限流从一开始就加上这四句话能帮你省下大半的调试时间。
企业微信群机器人文件推送：Spring Boot 与 media_id 实践
上周有个做测试平台的朋友来问我他们流水线跑完自动化用例之后allure 报告和打包好的 jar 想自动丢到测试群里让大家第一时间看到结果问我有没有什么省事的做法。我第一反应就是企业微信的群机器人——不用申请自建应用不用配可信 IP不用管 access_token 的刷新逻辑一个 Webhook 地址就能把消息推到群里。但真动手写的时候会发现发文本一句话就完事发文件就没那么直白了中间横着一个“素材上传换 media_id”的步骤很多人卡在 media_id 过期、文件超过 20MB、multipart 边界处理这些细节上。这篇就聊聊我用 Spring Boot 做这件事的完整思路从群机器人的能力边界到上传接口的参数含义再到工程里怎么封装成一个能复用的客户端最后把我踩过的坑和排查表一并交代清楚。适合手上有 Spring Boot 项目、想给团队做构建通知或报告推送的同学也适合刚开始接触企业微信开放接口、想搞明白 media_id 这套机制的人。代码基本都是可以复制粘贴改改就能跑的我会标清楚每个参数为什么这么设。1. 需求拆解与整体方案设计1.1 先搞清楚群机器人到底能发什么动手写代码之前我建议你先花五分钟把群机器人的消息类型捋一遍这一步省不得。企业微信群机器人本质是一个 Webhook 接收端你 POST 一段 JSON 过去它负责渲染到群里支持的类型有文本 text、markdown、图片 image、图文 news、文件 file、语音 voice、模板卡片 template_card。注意这里有个非常容易误判的点image 和 file 类型要求的不是二进制内容而是 media_id也就是说你没法直接把图片字节塞进 JSON 发出去必须先调一次“上传素材”接口把文件传上去拿到一个叫 media_id 的字符串凭证再拿这个凭证去发消息。这个设计和公众号素材库的思路是一模一样的我个人的理解是它要控制消息体大小同时给文件内容做一次缓存复用。文本消息你甚至可以塞几千字进去但一个 10MB 的文件如果直接走 JSON 的 body网关那一层就扛不住了。所以群机器人把“内容传输”和“消息通知”拆成了两步理解了这个前提后面所有代码结构就顺了。顺带说一句很多同学搜到的是“企业微信发送应用消息”那套接口那是自建应用的能力需要 corpId、corpSecret、agentId 三件套还要配置可信 IP接口地址和群机器人完全不是一回事。这两套东西经常被混为一谈我在群里见过太多次有人拿着应用的 access_token 去调群机器人的接口然后报 40001。判断方法很简单URL 里带webhook/send和key的是群机器人带message/send和access_token的是应用消息。1.2 为什么我优先推荐 Webhook 而不是自建应用从工程成本看群机器人几乎是零门槛。你只需要在群聊里点右上角添加群机器人拿到一串类似xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx的 key拼到https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key后面就能用。没有 token 过期问题没有 IP 白名单问题不需要企业管理员审批一个普通的群成员就能创建。对于“构建完成通知”“日报推送”“告警上报”这类场景它完全够用。自建应用的优势在于能定向发给个人、能接收用户回复、能做更复杂的交互但代价是要走审批、要维护 token 刷新、要处理 IP 变更。我一般的判断标准是如果只是单向地把信息推到某个群里用群机器人如果需要和具体的人做双向交互才考虑自建应用。这个项目标题里明确说了“群机器人”所以我们整条链路都围绕 Webhook 来走不引入 access_token 那一套。不过这里要提醒一句群机器人的 key 等同于密码谁拿到都能往群里发消息。所以我在项目里从来不把 key 硬编码进代码一律走配置中心或者环境变量本地开发用一个单独的测试群 key别拿生产群的 key 在本地乱试我之前就因为调试频率太高触发过限流消息延迟了几分钟才到排查了半天。1.3 整条链路怎么设计才不至于写成一坨把链路拆开看其实就四步读取本地文件、调用上传素材接口拿到 media_id、拿 media_id 组装 file 消息体、调 send 接口发出去。前两步是“传”后两步是“发”。我的做法是把上传和发送封装到同一个客户端类里对外只暴露一个sendFile(File file)方法调用方不需要知道 media_id 这回事这样以后要加图片、加 markdown 通知扩展起来也清爽。再往上一层我会把它挂到一个异步线程池里执行因为上传一个大文件加发消息加起来可能要一两秒如果放在主业务线程或者定时任务线程里同步执行会把整个流程拖慢。构建通知这种场景晚半秒没人介意但卡住主流程就是事故。所以整个设计的核心关键词是单一职责、异步解耦、配置外置、失败可重试。工程结构上我一般这么分一个WeComRobotProperties承载配置一个WeComRobotClient负责实际请求一个FileUploadResult之类的 DTO 接返回再加上一个AsyncConfig定义线程池。文件不大的话甚至不需要引入任何额外的 HTTP 客户端Spring 自带的 RestTemplate 就够用了这也是我下面演示方案的基础。2. 核心原理与关键参数拆解2.1 上传素材接口的机制与 media_id 的生命周期上传素材的接口是POST https://qyapi.weixin.qq.com/cgi-bin/webhook/upload_media?keyKEYtypefile请求体是multipart/form-data表单字段名固定叫media值是文件本身。type参数目前群机器人支持file和image两种发文件就用 file。返回体是 JSON结构大致是{errcode:0,errmsg:ok,type:file,media_id:...,created_at:1690000000}你只需要取 media_id 字段。这里最关键的参数是 media_id 的有效期官方说明是 3 天。这个数字经常被误解成“消息发出去 3 天内有效”其实不是它指的是这个 media_id 本身 3 天后就作废了你用同一个 media_id 去 send 接口发消息如果在有效期内可以重复发多次超过 3 天再发就报 media_id 无效。我做过一个不太严谨的小测试第一天上传的 media_id当天重复发送没问题到第四天再去发直接返回 errcode 40007 之类的错误。所以我的实践建议是上传和发送尽量在同一个方法里紧挨着完成不要想着提前上传一堆素材存到数据库里慢慢用除非你确实验证过时间窗口。还有一个隐藏知识点同一个文件内容重复上传企业微信似乎会做去重返回的可能是同一个 media_id。这个我没有做严格的对照实验但从日志观察来看相同文件的 media_id 确实有重复出现的情况。不过我从来不依赖这个行为来做业务逻辑只把它当作一个可能的优化代码里该上传还是老实上传。2.2 文件消息体的字段构成与常见写错的地方拿到 media_id 之后发消息的接口是POST https://qyapi.weixin.qq.com/cgi-bin/webhook/send?keyKEYbody 是 JSON{ msgtype: file, file: { media_id: MEDIA_ID } }就这么简单但恰恰是这几行最容易写错。第一个坑是 msgtype 的值和字段名必须一致msgtype是file那么下面的 key 也必须是file写成fileMsg或者file_info都会报参数错误。第二个坑是 media_id 的类型必须是字符串有的人从 JSON 里取出来用了数字类型的解析器把一长串数字当 int/long 处理精度丢失之后就废了所以 DTO 里一定用 String 接。第三个坑是上传时 type 填了 image发送时却用了 file 消息体这种跨类型的错配也会报错两个地方的 type 要对上。另外提一句群机器人的 send 接口返回体里只有 errcode 和 errmsg没有消息 ID 之类的东西所以你判断成功与否就看 errcode 是不是 0。有些同学问“企业微信发送文件怎么确认发送是否成功”答案就在这个返回码上0 表示服务端已接收并投递非 0 就按错误码查表。注意它不代表对方已经“看到”只代表投递成功这个心理预期要摆正。2.3 文件大小、类型与频率限制的实测数据这部分是我踩坑最多的地方直接上表格比讲一堆话管用限制项官方/实测值说明与应对单文件大小5B ~ 20MB下限其实可忽略上限 20MB 是硬杠超了直接报错上传素材 typefile / image群机器人不支持 voice、video别拿应用那套文档套media_id 有效期3 天上传后尽快发送别囤发消息频率每分钟 20 条超过会限流批量推送要加节流请求方式必须 POSTGET 会返回 404 或不支持的提示字符编码UTF-8中文文件名要处理编码否则可能乱码20MB 这个上限我个人觉得对构建通知场景是完全够用的jar 包一般也就几十兆如果真超了要么用分片思路下面第 5 章会讲要么干脆只发个下载链接把文件放对象存储里。频率限制那个每分钟 20 条是容易被忽略的我做告警聚合的时候有一次因为一个循环里连着发了三十多条后面几条直接被限流丢了后来老老实实加了一个令牌桶限流才稳定下来。文件类型方面群机器人上传素材对扩展名没有特别严格的强制校验但微信客户端能不能正常预览预览是另一回事。我发过.jar、.zip、.xlsx、.pdf都没问题都以下载附件的形式呈现。这里有个小细节文件名是你在 multipart 里带的那个 filename客户端展示的就是它所以上传时要保证文件名是完整带扩展名的别只传个纯数字名字不然群里下载下来都不知道是什么。3. 从零落地Spring Boot 工程实操3.1 依赖与配置该怎么放先说依赖最小集合只需要spring-boot-starter-web因为 RestTemplate 和 multipart 转换器都在里面。如果你团队习惯用 OkHttp 或者 WebClient 也可以我下面用 RestTemplate 演示因为它的 multipart 支持开箱即用改动最少。如果想省事还可以引spring-boot-configuration-processor让 IDE 有配置提示这个属于锦上添花。配置我全部放到application.yml里并且做了配置类绑定这样切换测试群和生产群只改配置不改代码wecom: robot: webhook-key: your-webhook-key-here upload-url: https://qyapi.weixin.qq.com/cgi-bin/webhook/upload_media send-url: https://qyapi.weixin.qq.com/cgi-bin/webhook/send connect-timeout: 5000 read-timeout: 30000 max-file-size: 20971520这里我把 max-file-size 显式写成 20971520也就是 20MB 的字节数不是用来做校验上限的而是在上传前自己先拦一道避免把 30MB 的文件白白传上去再被服务端拒绝浪费带宽和时间。超时时间我给的是连接 5 秒、读取 30 秒因为上传大文件读响应会比较慢读取超时设太短容易在网络抖动时误判失败。配置类长这样Data Component ConfigurationProperties(prefix wecom.robot) public class WeComRobotProperties { private String webhookKey; private String uploadUrl; private String sendUrl; private int connectTimeout 5000; private int readTimeout 30000; private long maxFileSize 20971520L; }用ConfigurationProperties而不是到处Value是因为后面要加字段的时候只改一个地方工程里也不会散落一堆魔法字符串。这是我在好几个项目里养成的习惯配置集中管理出问题的时候定位快。3.2 用 RestTemplate 处理 multipart 上传上传这一步是整个流程里最容易出错的地方。我的做法是构造一个LinkedMultiValueMap把文件包装成FileSystemResource放进去字段名严格用mediapublic String uploadFile(File file) { if (file.length() properties.getMaxFileSize()) { throw new IllegalArgumentException(文件超过 20MB 上限); } MultiValueMapString, Object body new LinkedMultiValueMap(); body.add(media, new FileSystemResource(file)); HttpHeaders headers new HttpHeaders(); headers.setContentType(MediaType.MULTIPART_FORM_DATA); HttpEntityMultiValueMapString, Object request new HttpEntity(body, headers); String url UriComponentsBuilder.fromHttpUrl(properties.getUploadUrl()) .queryParam(key, properties.getWebhookKey()) .queryParam(type, file) .build().toUriString(); ResponseEntityUploadResult resp restTemplate.postForEntity(url, request, UploadResult.class); UploadResult result resp.getBody(); if (result null || result.getErrcode() null || result.getErrcode() ! 0) { throw new RuntimeException(素材上传失败: result); } return result.getMediaId(); }几个关键点解释一下。第一FileSystemResource会自动从文件路径推断出 filename 和 content-type一般够用但如果你要发一个.jar文件而 Spring 的 media type 推断器不认这个扩展名它可能会退化成application/octet-stream这通常不影响上传因为服务端要的是字节而不是 content-type。第二URL 上的 key 和 type 参数我用了UriComponentsBuilder好处是它会帮你做 URL 编码避免 key 里出现特殊字符时拼错。第三这一层我把返回结果做了解包并抛异常调用方不用关心 errcode。这里要特别说一个我踩过的坑中文文件名。如果文件名里有中文某些环境下 multipart 编码会产生乱码群里显示成问号。解决办法是给FormHttpMessageConverter显式设置 UTF-8或者干脆把上传时的文件名改成拼音/英文展示层再去补充说明。我个人倾向于第二种简单直接省得和编码较劲。3.3 发送文件消息与客户端统一封装发送这一步就简单多了构造一个 Map 转 JSON 即可但要注意msgtype、file、media_id三者对齐public void sendFileByMediaId(String mediaId) { MapString, Object fileNode new HashMap(); fileNode.put(media_id, mediaId); MapString, Object payload new HashMap(); payload.put(msgtype, file); payload.put(file, fileNode); String url UriComponentsBuilder.fromHttpUrl(properties.getSendUrl()) .queryParam(key, properties.getWebhookKey()) .build().toUriString(); HttpHeaders headers new HttpHeaders(); headers.setContentType(MediaType.APPLICATION_JSON); HttpEntityMapString, Object request new HttpEntity(payload, headers); ResponseEntitySendResult resp restTemplate.postForEntity(url, request, SendResult.class); SendResult result resp.getBody(); if (result null || result.getErrcode() null || result.getErrcode() ! 0) { throw new RuntimeException(文件消息发送失败: result); } }然后把它俩串起来对外只给一个方法public void sendFile(File file) { String mediaId uploadFile(file); sendFileByMediaId(mediaId); } public void sendFile(byte[] bytes, String fileName) { // 用 ByteArrayResource 重写 getFilename避免临时文件 ByteArrayResource resource new ByteArrayResource(bytes) { Override public String getFilename() { return fileName; } }; // 后续同 uploadFile只是把 FileSystemResource 换成 resource }为什么要提供byte[]版本因为很多场景下文件并不在本地磁盘上而是从数据库或者上游接口拿到的字节流。用ByteArrayResource匿名类重写getFilename是一个经典技巧因为ByteArrayResource默认返回 null而 multipart 需要文件名。这个小细节我卡过半小时报错信息还特别模糊后来翻源码才发现的。还有一点RestTemplate 默认用的是 JDK 自带的SimpleClientHttpRequestFactory它处理 multipart 时偶尔会有边界问题我的经验是如果需要发稍大的文件换成HttpComponentsClientHttpRequestFactory基于 Apache HttpClient更稳连接复用也更好。这属于稳定性上的取舍小文件用默认的没毛病。3.4 异步执行与失败重试的安排前面提过上传加发送整体是耗时操作我会把它放到自定义线程池里异步跑。线程池参数别用默认的Executors.newFixedThreadPool这种隐式无界队列的写法在生产环境是有风险的我一般显式声明Configuration EnableAsync public class AsyncConfig { Bean(wecomExecutor) public ThreadPoolTaskExecutor wecomExecutor() { ThreadPoolTaskExecutor executor new ThreadPoolTaskExecutor(); executor.setCorePoolSize(2); executor.setMaxPoolSize(4); executor.setQueueCapacity(200); executor.setThreadNamePrefix(wecom-); executor.setRejectedExecutionHandler(new ThreadPoolExecutor.CallerRunsPolicy()); executor.initialize(); return executor; } }这里我用CallerRunsPolicy而不是丢弃策略因为在构建通知这种场景下宁可稍微拖慢调用方也不要把通知悄悄丢了。核心线程数设小是因为这个任务本身不是高并发场景两个线程足够队列容量给大一点缓冲突发。重试方面我倾向于只对“超时”和“5xx”这类瞬时失败做重试重试次数 2 到 3 次退避间隔用 1 秒、2 秒、4 秒这种指数形式。注意千万别对“文件超过 20MB”“errcode 40007 media_id 无效”这类确定性错误重试重试一百次也没用只会刷日志。我见过有同学写了个无脑重试结果限流限得更狠得不偿失。3.5 完整调用示例与本地验证把上面拼起来在业务里调用就一行Resource private WeComRobotClient robotClient; Async(wecomExecutor) public void notifyBuildDone(Path jarPath) { try { robotClient.sendFile(jarPath.toFile()); } catch (Exception e) { log.error(构建产物推送失败, e); } }本地怎么验证我的建议是先在测试群里发一个几 KB 的小文本文件确认能收到再逐步换成真实大小的文件。不要一上来就拿 18MB 的包试因为一旦失败你分不清是代码问题还是网络问题。验证顺序我的习惯是文本消息 → 小文件 → 真实文件 → 异步环境。每步都看日志里的 errcode心里才有底。另外有个小技巧本地调试时可以在上传完拿到 mediaId 之后先把它打日志出来然后用 curl 手动调一次 send 接口确认这个 mediaId 是有效的。这样能把“上传问题”和“发送问题”彻底隔离排查效率至少翻倍。4. 踩坑实录与问题排查速查4.1 几个典型的报错和我的处理方式说到 errcode 93000 附近的错误最常见的几个我列一下。errcode 40001通常是 key 有问题或者拼错了检查 URL 里的 key 参数有没有多余空格errcode 40058一般是 msgtype 和字段名对不上回去看是不是 file 写成了别的errcode 40007我遇到两种触发场景一种是 media_id 真的过期了另一种是上传时 type 和发送时对不上比如上传类型是 image 却当成 file 发。区分方法是看日志里两次请求的 type 参数。还有一次印象比较深的是某次升级 Spring Boot 版本之后multipart 上传开始间歇性失败报的是 400 之类的错误。排查下来是新版对 multipart 的 boundary 处理更严格加上我用的是默认的SimpleClientHttpRequestFactory在某些文件名编码场景下边界字符串被污染了。换成 Apache HttpClient 的实现之后问题消失。所以我一直提醒身边人升级 Spring Boot 大版本之后一定要把这类 HTTP 相关的功能回归一遍别只看编译过没过。限流是另一个大坑。前面提过每分钟 20 条的上限我当时的场景是一个聚合告警一个批次里可能有几十条要发。最初的写法是 for 循环里直接发结果前 20 条成功后面的全被限流。后来我加了一个基于 Guava RateLimiter 的限流把速率控制在每秒 0.3 次左右稳定运行到现在。或者更简单的办法是把多条告警合并成一条 markdown 消息发一次既省额度又清爽这个思路我强烈推荐。4.2 常见问题速查表现象可能原因排查方向返回 40001key 错误或空格打印完整 URL 检查 key 参数返回 40058msgtype 与字段名不匹配确认 file 字段名是否为 file返回 40007media_id 过期或类型不符检查上传时间与 type 一致性文件收到但打不开上传时文件名缺扩展名用 FileSystemResource 或重写 getFilename中文文件名乱码multipart 编码非 UTF-8设置 converter 编码或改用英文名超过 20MB 报错服务端硬限制上传前本地校验并给出提示消息时有时无触发频率限制加限流或合并消息上传超时读取超时太短调大 readTimeout 到 30s本地能跑线上不行网络策略限制确认出网策略允许访问对应域名偶发边界错误默认请求工厂问题换 HttpComponents 实现这张表我建议打印出来贴在工位上遇到问题先扫一眼能省下大量搜索时间。很多问题本质上是同一类只是表现不同。5. 生产环境加固与后续可扩展方向5.1 文件超过 20MB 时的几种解法硬碰硬是不行的服务端限制摆在那。我的思路有三条。第一条是压缩构建产物里很多是可以压缩的比如图片、日志、报告压一压经常能掉到 20MB 以内。第二条是上传到对象存储拿一个预签名链接然后发一条 markdown 消息把链接贴出去用户点一下就下载这条路最通用也最适合大文件。第三条是分片如果确实需要推大文件只能切分成多个小文件分别上传发送接收方再合并但体验一般我很少用。我一般默认选第二条原因很简单对象存储的成本低、稳定、还能做权限和过期控制。群里收到的不再是一个死沉沉的附件而是一个干净的可点击链接从产品体验来说也更舒服。当然如果你所在的环境里没有对象存储那压缩加限制文件类型是更现实的选择。5.2 和构建流程结合起来才真正有价值单独发一个文件没什么意思真正有价值的是把它挂进 CI/CD 流程里。比如流水线跑完自动化测试之后把 allure 的 HTML 报告打成 zip推到群里或者打包完成后把 jar 推给测试同学。触发点可以是 Jenkins 的 post 步骤也可以是 GitLab CI 的 after_script甚至是本地写个脚本手动调用。核心逻辑都一样就是把生成的产物路径传给你的 Spring Boot 服务。这里有个实用的设计把发送能力包装成一个小小的 HTTP 接口比如POST /notify/file参数是文件路径和一个群标识构建脚本直接 curl 调用就行。这样构建侧完全不需要懂企业微信的接口细节解耦得很干净。我在好几个项目里都是这么搭的运维改脚本不用碰 Java 代码Java 侧改逻辑也不影响脚本。5.3 日志、监控和失败告知生产环境最怕的就是通知静默失败你以为发了其实没发出去等大家发现的时候已经误事了。所以我的做法是每次发送都打一条结构化日志包含文件名、大小、media_id 的前几位、errcode、耗时失败时除了重试还会往另一个“告警群”推一条文本消息说明哪个文件发送失败了。这就避免了“监控本身挂了没人知道”的经典问题。监控指标上我会记录发送成功率和平均耗时如果成功率掉下来或者某个时间段的失败集中出现通常意味着网络策略或者 key 出问题了。这些指标接入现有的监控系统就行不需要额外搭一套。说句实在话通知类功能一旦上线它的可用性就直接影响团队的信息流转值得花点心思做可观测性。我在实际使用中的体会是企业微信这套群机器人接口的稳定性和易用性都相当靠谱坑基本集中在 media_id 和文件大小这两个点上把这两块吃透剩下的就是工程封装的事。如果让我给新手一个建议那就是先用 curl 把上传和发送两个请求跑通确认链路没问题再动 Spring Boot 代码顺序反了容易在代码里绕圈。我踩过几次坑之后总结出来的经验就是接口先手工验证代码后批量封装日志从头到尾都别省限流从一开始就加上这四句话能帮你省下大半的调试时间。
