如何在 Spring Boot 项目中集成钉钉机器人通知功能

在 Spring Boot 项目中集成钉钉机器人，最稳妥的方式是直接调用官方 Webhook 接口并配合签名验证。这种方式无需引入重型 SDK，适合用于系统报警、部署通知等场景。

先说结论：推荐使用原生 HTTP 请求配合 HMAC-SHA256 签名，避免引入过重依赖，适合大多数监控告警场景。

适合：内部系统告警、CI/CD 部署通知、业务关键状态推送。
先看：钉钉群机器人安全设置（签名或 IP 白名单）。
建议：发送逻辑异步化，避免阻塞主业务线程。
安全：Secret 严禁硬编码，生产环境使用环境变量或配置中心管理。

1. 前置准备

在钉钉群设置中添加机器人，选择“自定义”，勾选“加签”安全设置。记录以下两个关键信息：

Webhook 地址：包含 access_token 的完整 URL。
Secret：加签密钥，以 SEC 开头。

2. 依赖配置

确保项目包含 spring-boot-starter-web，它提供了 RestTemplate 用于发送 HTTP 请求。如需简化代码，可选引入 Lombok。

<!-- Maven 依赖 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

3. 配置文件示例

将 Webhook 和 Secret 配置在 application.yml 中。注意：生产环境建议使用环境变量占位符，避免密钥泄露。

dingtalk:
  robot:
    webhook: https://oapi.dingtalk.com/robot/send?access_token=YOUR_TOKEN
    secret: SEC_YOUR_SECRET
    # 生产环境建议：secret: ${DING_ROBOT_SECRET}

4. 核心代码实现

编写工具类实现签名计算与消息发送。签名逻辑需严格遵循：timestamp + "\n" + secret 进行 HMAC-SHA256 计算，结果再进行 URL 编码。

import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Service;
import org.springframework.web.client.RestTemplate;

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;

@Slf4j
@Service
public class DingTalkRobotService {

    @Value("${dingtalk.robot.webhook}")
    private String webhook;

    @Value("${dingtalk.robot.secret}")
    private String secret;

    private final RestTemplate restTemplate = new RestTemplate();

    public void sendTextMessage(String content) {
        try {
            long timestamp = System.currentTimeMillis();
            String sign = generateSign(timestamp, secret);
            String url = webhook + "×tamp=" + timestamp + "&sign=" + sign;

            String jsonBody = "{\"msgtype\": \"text\", \"text\": {\"content\": \"" + content + "\"}}";
            restTemplate.postForObject(url, jsonBody, String.class);
            log.info("钉钉通知发送成功");
        } catch (Exception e) {
            log.error("钉钉通知发送失败", e);
        }
    }

    private String generateSign(long timestamp, String secret) throws Exception {
        String stringToSign = timestamp + "\n" + secret;
        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
        byte[] signData = mac.doFinal(stringToSign.getBytes(StandardCharsets.UTF_8));
        return URLEncoder.encode(new String(signData, StandardCharsets.UTF_8), "UTF-8");
    }
}

5. 调用示例

在业务代码中注入服务即可调用，建议异步执行以免阻塞主线程。

@Autowired
private DingTalkRobotService dingTalkRobotService;

// 业务逻辑中调用
dingTalkRobotService.sendTextMessage("系统部署完成，版本 v1.0.2");

6. 验证方法

启动项目后触发通知逻辑，通过以下方式验证：

钉钉群消息：确认群内收到文本消息。
接口响应：检查日志中 RestTemplate 返回内容，钉钉成功返回 {"errcode":0,"errmsg":"ok"}。

curl 测试：若代码失败，先用 curl 验证网络与 Token 有效性。

curl 'https://oapi.dingtalk.com/robot/send?access_token=YOUR_TOKEN' \
   -H 'Content-Type: application/json' \
   -d '{"msgtype": "text", "text": {"content": "测试"}}'

7. 常见坑与排查

签名无效：确保 Secret 拼接 timestamp 后换行（\n）再进行 HMAC 计算，顺序不能错。
时间戳过期：timestamp 必须是当前时间毫秒值，与服务器时间偏差过大可能失败。
频率限制：钉钉机器人限流约 20 条/分钟，高频场景需做聚合或降级处理。
密钥安全：Secret 等同于密码，不要提交到 Git 仓库。生产环境建议通过配置中心（如 Nacos/Apollo）或环境变量注入。
特殊字符：消息内容包含特殊字符时，确保 JSON 格式正确，必要时进行转义。