企业微信机器人适合用来做业务通知、异常提醒、任务状态同步等场景。本文从已经拿到群机器人 Webhook 地址之后开始，介绍后端如何保存配置、发送消息、设置静默时间，以及配置 @ 群成员。

配置企微通知并获取webhook:

一、配置项设计

后端通常需要保存以下字段：

CREATE TABLE switch_bill_notify_config (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    enterprise_id BIGINT NOT NULL,
    wechat_webhook_url VARCHAR(1024),
    wechat_mentioned_mobile_list VARCHAR(512) NOT NULL DEFAULT '@all',
    wechat_webhook_enabled TINYINT NOT NULL DEFAULT 1,
    silent_interval_minutes INT NOT NULL DEFAULT 10,
    notify_timings VARCHAR(255),
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    deleted TINYINT DEFAULT 0
);

字段说明：

字段	说明
wechat_webhook_url	企业微信群机器人 Webhook
wechat_mentioned_mobile_list	@ 成员手机号，逗号分隔
wechat_webhook_enabled	是否启用通知
silent_interval_minutes	同类通知静默时间，单位分钟
notify_timings	启用的通知时机，逗号分隔
deleted	逻辑删除标记

二、保存 Webhook 配置

Webhook 地址由前端传给后端，后端需要做基础校验：

private String normalizeWebhookUrl(String value) {
    return value == null || value.isBlank() ? null : value.trim();
}

private void validateWebhookUrl(String webhookUrl) {
    if (webhookUrl == null || webhookUrl.isBlank()) {
        return;
    }
    if (!webhookUrl.startsWith("http://") && !webhookUrl.startsWith("https://")) {
        throw new IllegalArgumentException("企微机器人地址必须以 http:// 或 https:// 开头");
    }
}

保存时建议逻辑：

config.setWechatWebhookUrl(normalizeWebhookUrl(request.getWechatWebhookUrl()));
config.setWechatWebhookEnabled(Boolean.FALSE.equals(request.getWechatWebhookEnabled()) ? 0 : 1);

如果 Webhook 为空，可以保存配置但不发送通知。

三、发送企业微信消息

企业微信机器人支持 text、markdown 等消息类型。若需要 @ 成员，推荐使用 text 类型，因为它支持 mentioned_mobile_list。

示例请求：

Map<String, Object> body = new HashMap<>();
body.put("msgtype", "text");

Map<String, Object> text = new HashMap<>();
text.put("content", content);
text.put("mentioned_mobile_list", mentionedMobileList);

body.put("text", text);

发送请求：

restTemplate.postForObject(webhookUrl, body, String.class);

四、@ 群成员设置

企业微信机器人 @ 成员通常有三种配置方式：

配置值	效果
@all	@ 所有人
手机号列表	@ 指定成员
空字符串	不 @ 任何人

后端可以用逗号分隔保存：

@all

或：

13800138000,13900139000

解析逻辑示例：

private List<String> resolveMentionedMobileList(String value) {
    if (value == null) {
        return List.of("@all");
    }
    if (value.isBlank()) {
        return List.of();
    }
    return Arrays.stream(value.split(","))
            .map(String::trim)
            .filter(item -> !item.isEmpty())
            .distinct()
            .toList();
}

手机号建议做格式校验：

if (!mobile.matches("\\d{5,20}") && !"@all".equals(mobile)) {
    throw new IllegalArgumentException("企微 @ 手机号格式不正确");
}

五、静默时间设置

静默时间用于避免同类通知频繁发送。

例如：某条任务已经发送过一次失败提醒，如果静默时间是 10 分钟，那么 10 分钟内不再重复发送同类通知。

字段：

silent_interval_minutes INT NOT NULL DEFAULT 10

后端建议限制范围：

private int normalizeSilentIntervalMinutes(Integer value) {
    int minutes = value == null ? 10 : value;
    if (minutes < 1) {
        return 1;
    }
    return Math.min(minutes, 1440);
}

查询通知候选时，可以通过通知记录表判断是否超过静默时间：

AND nr.updated_at < DATE_SUB(
    NOW(),
    INTERVAL COALESCE(cfg.silent_interval_minutes, 10) MINUTE
)

这样可以做到：

• 未发送过：允许发送
• 发送失败：超过静默时间后允许重试
• 已发送过：按业务需要决定是否允许静默后再次提醒

六、通知时机配置

可以把通知时机保存成逗号分隔字符串：

received,submitted,send

判断是否启用：

private boolean isNotifyEnabled(String notifyTimings, String timing) {
    if (notifyTimings == null || notifyTimings.isBlank()) {
        return true;
    }
    return Arrays.asList(notifyTimings.split(",")).contains(timing);
}

七、测试 Webhook

保存配置前后都可以提供一个测试接口：

public void testWebhook(String webhookUrl) {
    validateWebhookUrl(webhookUrl);

    String content = "企微机器人通知测试";
    boolean sent = wechatBotClient.sendText(webhookUrl, content, List.of());

    if (!sent) {
        throw new IllegalStateException("企微机器人发送失败，请检查 webhook 地址");
    }
}

测试成功后，再正式启用通知。

八、推荐实践

1. Webhook 地址只做必要校验，不在日志中完整打印。
2. 通知发送结果要落库，方便排查问题。
3. 同类通知要加静默时间，避免刷屏。
4. @ 成员建议支持 @all、手机号列表、空列表三种模式。
5. 发送失败不要无限重试，应结合静默时间和重试次数控制。
6. 通知时机做成可配置，方便不同企业按需启用。

总结

企业微信机器人通知的核心不只是“拿到 Webhook 后发消息”，还要处理好配置持久化、启停开关、静默时间、@ 成员、通知时机和发送记录。

一个可维护的后端通知模块，至少应包含：

• Webhook 配置
• 启用开关
• @ 成员配置
• 静默时间控制
• 通知时机配置
• 测试发送接口
• 通知记录表

这样既能满足业务提醒，也能避免重复通知和排查困难。