问题的起点

一个内部系统需要把待办通知推送到企业微信。请求体里明确带了接收人字段:

{
  "system": "QMS",
  "title": "SOP检验待办",
  "content": "批次 BT20260508 需要完成首件检验",
  "assignee": "张三"
}

结果消息发出去了,但群里 50 多个人的手机同时响了同一句话,张三和其他人收到的内容一模一样。

现象很清楚:接收人参数被吞了。但问题不在"参数解析失败"这一层——顺着链路往下走,会发现问题出在渠道选型上:企业微信群机器人这个渠道,在设计上就没有"收件人"这个概念。

消息链路拆解

以 Austin(java3y 开源的消息推送平台)为例,一条外部系统推送的消息,完整流转如下:

外部系统(QMS 出站接口)
   ↓  HTTP POST /receive/todo
WebhookController          接收请求、参数校验、组装 SendRequest
   ↓
SendService.send()         落库 + 投递到 Kafka(异步,接口立即返回)
   ↓
austin-handler / Receiver  消费 Kafka 消息
   ↓
处理流水线                 去重 → 屏蔽 → 渠道路由
   ↓
对应渠道的 Handler         调用第三方 API
   ↓
企业微信 API               消息出现在群里

关键问题是:"发给谁"这个决策,发生在哪一步?

答案取决于渠道实现。Austin 的两种企业微信渠道,行为完全不同。

两种渠道的对比

群机器人(Webhook Robot)

EnterpriseWeChatRobotHandler 负责这个渠道。它的核心方法 assembleParam() 组装的请求体长这样:

{
  "msgtype": "markdown",
  "markdown": { "content": "..." }
}

只有"发什么",没有"发给谁"。这是企业微信群机器人 API 的设计:它绑定的是一个群,调用即全员可见,没有 touser 字段。

那 receiver 参数去哪了?在 handler() 里只出现了一次,用于打日志:

logUtils.print(AnchorInfo.builder()
        .ids(taskInfo.getReceiver())   // 仅记录,不参与路由
        ...

也就是说:接收人被记录下来方便排查,但从未影响消息的投递范围。参数存在不等于参数生效——这是排查此类问题时要盯住的关键点。

想做到"定向",这个渠道只有一种折中:

{
  "msgtype": "text",
  "text": {
    "content": "待办:完成批次检验\n<@zhangsan>",
    "mentioned_list": ["zhangsan"]
  }
}

mentioned_list 能在消息里 @ 某人的企业微信 ID,起到提醒作用。但注意:这只是"@提醒",不是"定向投递",消息依然全员可见。而且它只支持 text 消息类型,markdown 消息不支持 @。

应用消息(Agent Message)

EnterpriseWeChatHandler 走的是企业微信的"应用消息"接口。它的请求体里明确有收件人:

{
  "touser": "zhangsan|lisi",
  "msgtype": "markdown",
  "agentid": 1000002,
  "markdown": { "content": "..." }
}

receiver 在这里会赋值给 touser,是真正参与业务逻辑的字段。这才是"定向推送"。

方案取舍

维度群机器人应用消息
定向能力❌ 只能 @ 提醒,消息全员可见✅ 按 userid 精准推送
接入成本极低,建群拿 webhook 地址即可需在企业微信后台创建自建应用,拿 agentid + secret
依赖无需维护"人名 → userid"的映射(可通过通讯录 API 同步)
消息类型markdown / text / 图文支持更丰富(含卡片消息)
适用场景团队广播、告警公示个人待办、审批提醒、敏感信息

结论:如果业务语义是"这件事归某个人办",就必须用应用消息渠道;如果只是"通知大家一声",群机器人足够。

选择群机器人省下的是接入成本,付出的是业务语义上的不精确——对"待办"这类场景,用户会因为"反正全群都看到"而逐渐忽略通知,这本身就是种损耗。

几个排查思路沉淀

  1. 先看请求体,再看代码。渠道 API 文档里有没有收件人字段,决定了这个渠道的能力边界。看代码之前先看 API 契约,能省一半时间。
  2. 搜索参数时,区分"类型定义"和"调用现场"。在类里搜到 private String receiver; 没有意义,要看的是它在业务方法里被用成了什么。
  3. receiver 这类字段出现多次时,统计用法。应用消息 Handler 里 receiver 出现了 4 次,一次是日志、三次参与 touser 赋值——这种"用法分布"直接告诉你字段的真实作用。
  4. 异步链路要有心理预期。SendService.send() 返回成功只代表消息成功落到 MQ,不代表已经发到群里。真实投递结果要去查 Handler 的日志和第三方的返回码。

小结

"指定了接收人却发到全员群"不是 bug,而是渠道能力与业务语义不匹配。企业微信群机器人天生没有收件人概念,receiver 在它的实现里只用于日志;要真正的定向推送,得换应用消息渠道,代价是自建应用和通讯录映射的维护成本。

技术选型时问一句"这个能力的边界在哪",比事后排查三天都值。

Logo

DAMO开发者矩阵,由阿里巴巴达摩院和中国互联网协会联合发起,致力于探讨最前沿的技术趋势与应用成果,搭建高质量的交流与分享平台,推动技术创新与产业应用链接,围绕“人工智能与新型计算”构建开放共享的开发者生态。

更多推荐