在 Node.js 里封装钉钉机器人，最稳妥的方式是基于官方 Webhook 协议写一个轻量类，重点处理好签名计算、异常重试和错误捕获，适合内部系统监控告警场景。

命令速用版

如果是新项目，先安装一个常用的 HTTP 请求库，然后用下面这个思路快速跑通：

npm install axios

快速处理思路：创建一个工具类，传入文本内容，内部自动计算时间戳和签名，发起 POST 请求，并包含重试机制。

为什么会这样

钉钉自定义机器人本质是一个 HTTP Webhook 接口。每次发送消息都需要向这个地址发起 POST 请求。官方为了安全，要求请求必须携带签名（signature），这个签名是用时间戳和密钥通过 HMAC-SHA256 算法算出来的。如果在业务代码里每次发送都写一遍签名逻辑，代码会很乱，而且密钥容易泄露。封装成 SDK 或工具类，就是为了统一处理这些安全细节和错误重试。

分步处理

第一步：获取 Webhook 和 Secret
在钉钉群里添加自定义机器人，拿到 Webhook 地址。勾选“加签”选项，复制 Secret。注意 Secret 只显示一次，丢失需要重置。

第二步：编写签名函数
使用 Node.js 内置的 crypto 模块。时间戳必须是当前时间毫秒数，签名结果需要 URL Encode。

const crypto = require('crypto');

function getSign(secret, timestamp) {
  const stringToSign = timestamp + '\n' + secret;
  const sign = crypto
    .createHmac('sha256', secret)
    .update(stringToSign)
    .digest('base64');
  return encodeURIComponent(sign);
}

第三步：完整 Class 封装
将签名、发送、重试逻辑封装到一个类中。这里使用 axios 发起请求，并在构造函数中传入配置。

const axios = require('axios');

class DingTalkRobot {
  constructor(webhook, secret) {
    this.webhook = webhook;
    this.secret = secret;
  }

  getSign(timestamp) {
    const stringToSign = timestamp + '\n' + this.secret;
    const sign = crypto
      .createHmac('sha256', this.secret)
      .update(stringToSign)
      .digest('base64');
    return encodeURIComponent(sign);
  }

  async send(content, maxRetries = 3) {
    const timestamp = Date.now().toString();
    const sign = this.getSign(timestamp);
    const url = `${this.webhook}×tamp=${timestamp}&sign=${sign}`;
    const payload = { msgtype: 'text', text: { content } };

    for (let i = 0; i < maxRetries; i++) {
      try {
        const res = await axios.post(url, payload);
        if (res.data.errcode === 0) {
          return { success: true };
        } else {
          throw new Error(`DingTalk API Error: ${res.data.errmsg}`);
        }
      } catch (error) {
        console.error(`Send failed (attempt ${i + 1}/${maxRetries}):`, error.message);
        if (i === maxRetries - 1) throw error;
        // 失败后间隔 1 秒重试
        await new Promise(resolve => setTimeout(resolve, 1000));
      }
    }
  }
}

第四步：调用与异常处理
在业务代码中实例化类并调用，外层包裹 try-catch 确保最终失败能被捕获记录，避免生产环境静默失败。

const robot = new DingTalkRobot(
  process.env.DING_WEBHOOK,
  process.env.DING_SECRET
);

async function notify() {
  try {
    await robot.send('系统部署完成');
    console.log('通知发送成功');
  } catch (error) {
    // 重试耗尽后的最终处理
    console.error('通知发送彻底失败，请检查网络或配置', error);
    // 可在此处触发二级告警
  }
}

怎么验证是否生效

1. 运行发送脚本，观察控制台是否有报错。
2. 检查钉钉群聊窗口，看是否收到消息。
3. 如果收到“签名无效”或“参数错误”，检查时间戳是否用了字符串，签名是否做了 URL 编码。
4. 测试重试机制：暂时断开网络或填入错误 Webhook，观察控制台是否打印了多次重试日志。

常见坑

1. 签名编码问题
算出来的签名必须用 encodeURIComponent 处理，否则特殊字符会导致请求被拒绝。

2. 密钥泄露
不要把 Secret 提交到 Git 仓库。建议使用环境变量或配置中心管理。

3. 频率限制
钉钉机器人有发送频率限制，公开资料中没有看到可靠的量化数据，建议参考钉钉开放平台文档。如果发送太频，机器人会被暂时禁言，业务代码里最好做个队列或限流。

参考来源

1. 钉钉开放平台 - 自定义机器人接入
2. Node.js 官方文档 - crypto 模块