上周三凌晨一点值班群里跳出一条消息对账任务跑挂了但没人第一时间知道。事后复盘发现日志平台里躺着二十多条异常堆栈邮箱里那封告警邮件被埋在第 47 页谁也没翻到。这件事之后我又把吃灰很久的那套Java 调用企业微信群机器人的小工具捡了起来重新梳理了一遍。这篇内容讲的就是这件事怎么用 Java 给企业微信群机器人发消息通知。它不是复述官方文档而是把我在真实项目里踩过的坑、做过的取舍、写过的封装代码摊开来讲。群机器人本质上就是一个Webhook 地址你往这个地址 POST 一段 JSON机器人就把消息发到指定的群里。不用申请应用、不用审核、不用拿 access_token 换票据五分钟能跑通第一条消息。适合谁看后端开发、运维、测试、做数据任务的同学习。你手里只要有一个能访问外网的 Java 进程就能把任务跑完/跑挂这件事告诉具体的人而不是躺在某个没人看的角落里。1. 消息通知方案的选型为什么最后选了群机器人1.1 五种常见通知通道的真实成本对比做过告警的人都知道选通道不是选技术是选人会不会真的看到。我把这几年用过的几种方式拉出来对比数据是实践中的经验值不是厂商宣传口径。通道接入成本到达速度是否需资质典型问题短信网关中要签名、模板报备秒级需要有费用模板改一次审一次邮件低SMTP 现成分钟级不需要打开率极低容易被规则归入归档群机器人 Webhook极低一个 URL秒级不需要有频率上限消息不保证必达自建推送应用高要管理员权限、IP 白名单秒级需要企业侧配合权限链路长跨团队推不动监控平台自带告警中分钟级不需要绑定平台临时脚本接不进去把这张表看完结论其实很清楚临时任务、脚本、内部工具这类的通知需求群机器人的性价比是最高的。它的上限确实不高——不支持可靠投递、有频率限制、消息存不住但对于跑完了告诉我一声这个场景够用。真正让我死心的是对比过自建应用那条路。走企业自建应用你得先拿到企业管理员权限建应用配可信 IP再写代码换 access_token、做缓存、处理过期还要关心不同成员的可见范围。链路一长一个环节卡住就是半天。而群机器人只要群主或者管理员在群里点几下给你一个带随机密钥的地址剩下全是你的代码说了算。1.2 Webhook 机器人到底是怎么工作的拆开看很简单你在群里添加机器人之后平台会分配一个 HTTPS 地址地址上挂着一串随机参数这就是你的身份凭证。你的 Java 程序向这个地址发一个 POST 请求请求体是一段 JSON里面有两个关键字段——msgtype声明消息类型其余字段按类型填内容。平台服务端收到后做校验校验通过就把消息投递到该机器人所在的群。整个过程里你的服务不用暴露任何端口不用关心内网穿透不用管对方怎么找到你因为流量是你主动往外发的。这一点对于部署在受限环境里的定时任务特别友好——很多内网机器出站是通的入站是一堵墙。还有一个常被忽略的点群机器人不需要签名。消息体里不带时间戳、不带签名串这跟很多开放平台的回调机制是反的。好处是实现极其简单坏处是密钥一旦泄露任何人拿到那个 URL 都能往你的群里发消息。所以这个地址的保管等级要按密码来算具体做法我在第 4 章展开。注意这里说的机器人是群里的自定义机器人不是对个人账号做自动化操作的那种方案。后者稳定性差、存在账号风险不适合放在生产链路上我见过有团队拿它做告警结果号被封了告警静默了两周才发现。1.3 我在选型阶段真正纠结的三个问题第一个问题是消息能不能撤回。答案是不能。发出去就发出去了所以任何自动通知在内容上都要克制别把一整段堆栈直接甩进群里——群里可能有不熟悉技术的同事一屏的异常信息只会让人选择无视。我的做法是群里只发一句人话加上一个链接细节放到日志平台的跳转地址里。第二个问题是谁该收到。群机器人只能发到群不能定向发给某个人。想定向就得用mentioned_list在文本消息里 具体的人。但这里有个坑 的标识是成员在群里的账号标识不是昵称写错了就是了个空气。我的习惯是把关键人做成配置项写在配置文件里改人不用改代码。第三个问题是消息丢了怎么办。这个必须提前想清楚。群机器人不是可靠消息队列网络抖一下、频率超一点消息就没了。所以我在关键告警上做了冗余群消息只是提醒,真正的告警状态落在自己的告警表里群消息丢失不影响故障被发现只是发现得慢一点。这个思路很重要别把唯一真相放在通知通道上。2. 动手前的准备拿到地址、定好消息格式2.1 三分钟拿到 Webhook 地址流程本身没什么技术含量但有两个细节值得说。在群聊的设置里找到机器人入口添加一个自定义机器人起个能看懂的名字我用的是任务通知-勿回这种避免有人以为是真人在说话然后复制那串地址。地址长这样前面是固定的域名路径后面跟着一个key参数https://qyapi.weixin.qq.com/cgi-bin/webhook/send?keyxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx这里有个细节很多人在测试的时候会把完整地址直接粘到代码里提交到代码仓库然后忘了。我见过不止一次密钥泄露导致的群里突然出现奇怪消息。正确做法是把它放进环境变量或者配置中心代码里只读key这一段域名部分写常量。第二个细节是机器人名字要能一眼区分环境。测试环境的机器人叫测试通知生产环境叫生产告警两者发到不同的群。我一开始图省事测试和生产共用一个群结果有一次压测把几万条消息刷进了生产群那场面相当难看。2.2 消息类型的选型text、markdown、图文卡片各管什么群机器人支持的消息类型不少常用的就四类各自的适用场景差别很大text纯文本支持换行和 成员。适合简短的告警、任务完成提示。上限是 2048 字节按 UTF-8 算一个常用汉字占 3 字节实际约 680 个汉字超了会被截断或者直接报错。markdown支持标题、加粗、行内代码、引用、链接、彩色字体。适合发版通知、日报汇总这类需要排版的场景。上限 4096 字节。news图文卡片最多 8 条每条有标题、描述、跳转链接和配图。适合把多条构建结果汇总成一张卡片。file先上传文件拿到临时标识再发消息引用。适合把构建产物、报表文件丢到群里。我个人的经验是日常告警一律用 text需要人点进去看的用 markdown需要人扫一眼多条结果的用 news。别一上来就用 markdown 画表格手机端窄屏上表格会挤成一坨我试过效果惨不忍睹。markdown 里有个隐藏能力值得记一笔支持三种语义颜色写成font colorinfo通过/font、font colorwarning警告/font、font colorcomment次要/font。用它把成功/失败标个色比写一堆感叹号有效得多。提示以上这些字节上限和条数限制官方文档会随版本调整。我建议你在项目里把这些数字抽成常量并且第一条消息就跑一次超长内容测试确认自己环境下的实际行为别全信记忆里的数字。2.3 参数与限制清单上线前必须核对的东西下面这张表是我每次接入新项目时会核对的清单直接抄就行项目实践值说明text 内容上限2048 字节按 UTF-8 计中文约 680 字markdown 上限4096 字节同样按 UTF-8 计单机器人发送频率20 条/分钟超过会返回限流错误码图片大小2MB 以内需要 base64 和 MD5 校验值文件大小20MB 以内需先调上传接口换标识请求方式POSTJSONContent-Type 必须带 charset频率限制这条是最容易翻车的。20 条/分钟听着够用但你想想一个批量任务处理 500 条数据每失败一条发一条消息瞬间就打满了。我的处理办法是在客户端做聚合——同类错误合并成一条最多列出前 5 条明细剩下的写共 N 条。这不仅规避了限流也让群里的人真的愿意看。3. Java 实现从三十行跑通到封装成工具类3.1 最简版本不用任何第三方库先跑通很多人一上来就找 SDK其实完全没必要。JDK 自带的HttpURLConnection就够了三十行能跑通第一条消息这对验证地址是否有效特别有用import java.io.*; import java.net.HttpURLConnection; import java.net.URL; import java.nio.charset.StandardCharsets; public class SimpleRobot { public static void main(String[] args) throws Exception { String webhook System.getenv(WX_ROBOT_WEBHOOK); String body {\msgtype\:\text\,\text\:{\content\:\对账任务执行完成耗时 32s\}}; HttpURLConnection conn (HttpURLConnection) new URL(webhook).openConnection(); conn.setRequestMethod(POST); conn.setDoOutput(true); conn.setConnectTimeout(3000); conn.setReadTimeout(5000); conn.setRequestProperty(Content-Type, application/json; charsetutf-8); try (OutputStream os conn.getOutputStream()) { os.write(body.getBytes(StandardCharsets.UTF_8)); } int code conn.getResponseCode(); InputStream is code 200 ? conn.getInputStream() : conn.getErrorStream(); try (InputStream in is) { System.out.println(HTTP code - new String(in.readAllBytes(), StandardCharsets.UTF_8)); } } }这段代码里有两个地方必须解释清楚否则你会踩坑。第一Content-Type必须带charsetutf-8。少了这一段服务端可能按默认编码解析你的请求体中文就变成了问号或者乱码。我在一个老项目上遇到过这个问题排查了很久最后发现就是头信息少了几个字符。第二返回码是 200 不代表发送成功。HTTP 200 只说明请求被接收了业务结果要看响应体里的errcode字段。errcode为 0 才是真的成功非 0 是业务错误具体错误码我放在第 5 章的表里。这一点非常关键我见过不少实现只判断 HTTP 状态码结果限流了还以为发成功了告警静默好几天。3.2 依赖选型OkHttp、HttpClient、RestTemplate 怎么挑跑通之后就要考虑工程化了。裸用HttpURLConnection写业务代码会很别扭连接池得自己管重试得自己写超时设置分散在各处。我在不同项目上用过三种方案说说各自的适用面。JDK 11 之后的java.net.http.HttpClient是我现在默认的选择。它内置在 JDK 里支持 HTTP/2、支持异步、线程安全、连接池管得住不需要加任何依赖。对于只有几个通知点的项目它是最轻的方案。缺点是写法略啰嗦尤其是构造 JSON 的时候。OkHttp适合项目里已经用它做别的 HTTP 调用的情况连接池复用、拦截器做日志都很顺手。如果项目已经引入没必要为了减少依赖硬切回 JDK 原生。Spring 的 RestTemplate适合本来就是 Spring 项目、且团队习惯统一走同一个客户端。但要注意较新版本里它已经被标注为维护状态新项目我更倾向用WebClient或者 JDK 原生客户端。选型上我给一个判断标准如果项目里已经有成熟的 HTTP 客户端封装就复用别为发个通知另起一套。通知代码最忌讳的就是自己造一个半成品 HTTP 工具超时没设、连接不关跑几个月把连接数吃满。3.3 封装一个可复用的发送客户端真正在项目里用的版本我会把消息体构造、分片、限流、重试、结果判断都收进一个类里。下面是我经过几轮修改后的结构去掉业务字段后大概长这样import com.fasterxml.jackson.databind.ObjectMapper; import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.nio.charset.StandardCharsets; import java.time.Duration; import java.util.*; import java.util.concurrent.*; public class GroupRobotClient { private static final String SEND_PATH /cgi-bin/webhook/send?key; private static final int TEXT_MAX_BYTES 1800; // 留出包装余量 private static final int MAX_PER_MINUTE 18; // 官方 20留 2 条余量 private final String baseUrl; private final String key; private final ObjectMapper mapper new ObjectMapper(); private final HttpClient http HttpClient.newBuilder() .connectTimeout(Duration.ofSeconds(3)) .build(); private final DequeLong window new ArrayDeque(); public GroupRobotClient(String baseUrl, String key) { this.baseUrl baseUrl; this.key key; } public boolean sendText(String content, ListString mentioned) { boolean allOk true; for (String part : splitByBytes(content, TEXT_MAX_BYTES)) { allOk doSend(buildTextBody(part, mentioned)); } return allOk; } private MapString, Object buildTextBody(String content, ListString mentioned) { MapString, Object text new LinkedHashMap(); text.put(content, content); if (mentioned ! null !mentioned.isEmpty()) { text.put(mentioned_list, mentioned); } MapString, Object body new LinkedHashMap(); body.put(msgtype, text); body.put(text, text); return body; } private boolean doSend(MapString, Object body) { String json; try { json mapper.writeValueAsString(body); } catch (Exception e) { return false; } for (int attempt 0; attempt 3; attempt) { try { acquire(); HttpRequest req HttpRequest.newBuilder() .uri(URI.create(baseUrl SEND_PATH key)) .timeout(Duration.ofSeconds(5)) .header(Content-Type, application/json; charsetutf-8) .POST(HttpRequest.BodyPublishers.ofString(json, StandardCharsets.UTF_8)) .build(); HttpResponseString resp http.send(req, HttpResponse.BodyHandlers.ofString()); Map?, ? result mapper.readValue(resp.body(), Map.class); int errcode ((Number) result.get(errcode)).intValue(); if (errcode 0) { return true; } if (errcode 45009) { // 触发频率限制 Thread.sleep(3000L * (attempt 1)); continue; } return false; // 业务错误重试无意义 } catch (InterruptedException ie) { Thread.currentThread().interrupt(); return false; } catch (Exception e) { if (attempt 2) return false; try { Thread.sleep(500L * (1L attempt)); // 指数退避 } catch (InterruptedException ie) { Thread.currentThread().interrupt(); return false; } } } return false; } private void acquire() throws InterruptedException { synchronized (window) { long now System.currentTimeMillis(); while (!window.isEmpty() now - window.peekFirst() 60_000L) { window.pollFirst(); } if (window.size() MAX_PER_MINUTE) { long wait 60_000L - (now - window.peekFirst()) 100L; if (wait 0) Thread.sleep(wait); } window.addLast(System.currentTimeMillis()); } } private ListString splitByBytes(String content, int maxBytes) { ListString parts new ArrayList(); StringBuilder sb new StringBuilder(); int bytes 0; for (int i 0; i content.length(); ) { int cp content.codePointAt(i); int len new String(Character.toChars(cp)).getBytes(StandardCharsets.UTF_8).length; if (bytes len maxBytes) { parts.add(sb.toString()); sb.setLength(0); bytes 0; } sb.appendCodePoint(cp); bytes len; i Character.charCount(cp); } if (sb.length() 0) parts.add(sb.toString()); return parts; } }这段代码里有几个设计决定值得单独说清楚。为什么留余量。官方说是 2048 字节我设 1800官方说 20 条/分钟我设 18。原因很简单你永远不知道平台侧的统计窗口是怎么切的也不知道有没有别的进程同时在用同一个机器人。留 10% 的余量换来的是不会在关键时刻被限流。为什么限流用客户端滑动窗口而不是信号量。信号量只控制并发数不控制时间维度。一个循环里顺序发 30 条并发是 1但一分钟内发了 30 条照样触发限流。所以必须是按时间窗口限。为什么只对限流错误重试其他业务错误直接返回。这是我从一次事故里学来的。当时所有错误都重试三次结果有个参数格式错的请求被重试了三遍还因为重试把限流额度全用光了导致后面真正的告警发不出去。业务错误重试是没有意义的只会放大问题。为什么按字节切分而不是按字符数切。因为限制单位是字节。用String.length()判断遇到中文就会判断失误你以为是 1500 个字符实际可能超过 4500 字节。上面这个按码点切分的方法能正确处理中文和 emoji 这类占用多字节的字符不会把字符切坏。3.4 JSON 组装与转义那些让人抓狂的细节手工拼 JSON 字符串是最容易出问题的地方。内容里只要出现引号、反斜杠、换行拼出来的 JSON 就废了。我有一次在告警内容里放了一段堆栈结果整条消息发送失败排查半天才发现是堆栈里的双引号没转义。正确做法是用序列化工具。项目里已经有 Jackson 就直接用没有的话用String.format加自己写的转义方法也能凑合但要处理全双引号、反斜杠、换行、回车、制表符、以及控制字符。另一个细节是字段顺序。用LinkedHashMap而不是HashMap能保证生成的 JSON 字段顺序稳定。这不影响功能但调试的时候日志里每次顺序都不一样会让人很烦。还有一点别在消息内容里放大段的原始异常堆栈。除了体积问题还有安全考虑——堆栈里可能带路径、连接串片段。我现在的做法是消息里只放异常类型 关键信息 日志查询链接堆栈留在日志里。4. 生产环境该考虑的限流、重试、异步与监控4.1 频率限制与告警风暴治理限流在客户端做只是第一层。真正的问题是告警风暴一个下游服务挂了你的任务批量失败几百个任务同时触发通知。这时候客户端限流只能让消息排队慢慢发群还是会被刷屏而且等你发完故障可能都恢复了。我在生产上用了三层防护。第一层是同类消息合并按异常类型和任务名做聚合键一分钟内的同类消息只发一条附带计数。第二层是静默窗口同一个聚合键在 10 分钟内只允许发一次后续的进队列但不发。第三层才是客户端限流作为最后的安全阀。注意合并逻辑里的聚合键设计要用任务名 异常类型别只用任务名。我一开始只用任务名结果一个任务同时出现两种完全不同的异常被合并成一条排查时信息不够得多翻一次日志。4.2 重试策略与重复消息的取舍重试这件事本质是在漏发和重复发之间选一个。我的取舍是网络异常和超时重试业务错误不重试重试次数控制在 3 次以内退避间隔用 500ms、1s、2s。为什么不重试更多次因为通知的时效性很短。一个告警延迟 30 秒还有意义延迟 5 分钟可能故障都恢复了这时候再发出去只会造成困扰。而且长时间占用线程重试会拖慢主业务流程。重复消息的问题也确实存在请求发出去了服务端收到了但响应在回程丢了你这边判定失败去重试群里就出现两条一样的消息。我的处理办法是在消息内容末尾加一个短序号比如[#7f3a]肉眼能看出是重复。这比做一套完整的幂等机制轻量得多日常够用。4.3 异步发送与线程池隔离通知发送绝对不能放在主业务线程里同步执行。一次 HTTP 调用少则几十毫秒多则几秒网络抖动的时候如果它挡在任务结束的关键路径上任务总耗时会被明显拉长。我在一个批量导出任务里就吃过这个亏原本 40 秒的任务加了同步通知后变成平均 43 秒因为偶尔会有一次超时。正确做法是丢到一个专用的小线程池里。这个池子要满足三个条件有界队列防止任务堆积把内存吃光专用线程跟业务线程池隔离避免互相拖累明确的拒绝策略队列满了就丢弃并计数绝不能让它阻塞或者无限排队。ThreadPoolExecutor noticePool new ThreadPoolExecutor( 2, 4, 60L, TimeUnit.SECONDS, new ArrayBlockingQueue(500), r - { Thread t new Thread(r, wx-notice); t.setDaemon(true); return t; }, new ThreadPoolExecutor.DiscardOldestPolicy() // 满了丢最老的 );用DiscardOldestPolicy的理由是通知场景下最新的信息比最全的信息有价值。队列满了说明已经出了大问题这时候保最新的一条比按顺序发完所有旧消息更合理。但要注意这个策略会静默丢弃所以一定要配一个计数器打点不然你永远不知道丢了多少。4.4 埋点监控让你的通知系统自己会报警通知通道本身也需要被监控否则它挂了你都不知道。我在发送客户端里埋了四个指标发送总数、成功数、失败数、平均耗时。另外把每次响应的errcode按值聚合出现频率异常的错误码单独统计。这些指标不用做得太复杂先打到日志里按天统计也能看出问题。关键是要有基线正常情况下一小时发多少条如果突然从 3 条变成 300 条说明上游出事了这时候通知系统本身应该触发一次通知量异常的告警——用另一条通道发别用同一条。我遇到过最尴尬的一次是机器人因为群设置变更失效了所有通知都发不出去而通知失败这件事本身也是通过这个机器人通知的形成死循环静默了整整一天。从那以后我的规则是——通知系统自身的健康检查必须走另一条独立通道。5. 常见问题与排查技巧实录5.1 错误码速查表先看这里再去翻文档下面这些是我实际遇到过的按出现频率排序。具体数值以你环境返回的为准但排查思路是通用的现象 / 错误码最可能的原因处理方式HTTP 200 但 errcode 非 0业务校验失败打印完整响应体别只看状态码45009触发频率限制客户端限流退避后重试93000地址无效或密钥被重置核对地址重新获取40008消息类型与字段不匹配检查 msgtype 和对应内容字段44004内容为空检查拼接逻辑空串也要防中文变问号或方块编码问题Content-Type 带 charset字节用 UTF-8消息被截断超出字节上限按字节分片留余量返回成功但群里没消息机器人被移出群、群解散让人确认群还在、机器人在5.2 三个让人抓狂的诡异现象现象一本地跑得好好的上了服务器就超时。这个最典型。原因是服务器所在的网络环境对出站访问有限制或者 DNS 解析不了那个域名。排查顺序是先在服务器上直接curl那个地址看能不能通通了再看 Java 里有没有设过默认的请求配置最后看超时时间设得是不是太短我见过设 500ms 的跨机房根本不够。现象二消息发出去了但 的人没收到提醒。mentioned_list里要填的是成员在群里的账号标识不是显示名也不是手机号部分场景下手机号可用但不通用。填错不会报错只是静默不生效。我的做法是在配置里维护一份账号标识 → 人名的映射写代码的时候用人名运行时转成标识出错时日志里能对得上。现象三markdown 消息里的链接点不动。markdown 类型对链接的渲染有要求有些格式它不认。最简单可靠的写法是直接用裸链接把 URL 完整写出来大多数客户端会自动识别。复杂排版就别强求了通知场景下能看清比好看重要。提示排查时先把发送内容打印出来直接粘到命令行里用curl发一次。这能立刻区分是代码问题还是内容问题。我用这一招定位过大部分问题比在代码里加断点快得多。5.3 我的避坑清单最后整理一份清单都是我实际踩过之后写进团队规范的可以直接拿去用。密钥不进代码库。走环境变量或者配置中心仓库里只留读取逻辑。一旦发现泄露立刻在群里重置机器人重新拿地址。生产环境和测试环境用不同的机器人。别图省事共用一个压测刷屏的事我经历过一次就够了。消息内容有长度上限保护。任何拼接进来的变量异常信息、文件名、用户输入都要先截断否则一个超长文件名就能让整条消息发送失败。判断成功要看 errcode不看 HTTP 状态码。这是最容易犯的错也是最贵的错。通知失败不能影响主流程。所有发送调用外面都要包一层异常兜底返回值用布尔量别往外抛。别在循环里逐条发通知。批量场景先聚合聚合之后再发既省额度又让人愿意看。给消息加上上下文标识。比如任务名、实例标识、环境名收到消息的人能立刻知道是哪个系统在说话。定期清理失效机器人。项目下线了、群解散了机器人地址还挂在配置里等哪天真的需要发消息才发现早就失效了。我在实际使用中的体会是这套东西的技术难度并不高难的是让人真的看到并且看懂。技术上跑通只是起点真正决定它有没有用的是内容设计——一条消息里该放什么、不该放什么、怎么让人在睡眼惺忪的时候一眼看出严重程度。我现在的做法是给消息做分级日常完成通知用灰色需要关注用警告色故障用最醒目的方式并 到人。分完级之后群里抱怨消息太多的声音明显少了因为大家知道什么样的消息可以忽略什么样的必须立刻看。还有一个后续可以扩展的方向把发送记录落到本地表里记录发送时间、内容摘要、返回码。这样做两个事——一是能统计哪些告警最频繁反向去优化那些总是出问题的任务二是当有人问那天到底通知了没有你有据可查不用靠记忆和聊天记录去翻。