SpringBoot对接钉钉发送消息

用户070003105832
5 阅读5分钟

01

在 Spring Boot 项目中接入钉钉消息推送能力，能够让应用快速向钉钉群/指定用户推送业务通知、系统告警等信息。
本文将以极简、易懂的方式，拆解从机器人创建到消息发送的全流程，帮你快速落地该功能。

02

核心前置步骤：创建钉钉群自定义机器人

想要实现钉钉消息推送，第一步必须先在目标钉钉群配置自定义机器人，这是整个流程的基础。

操作步骤

  1. 进入钉钉群聊界面，点击「群设置」→「智能群助手」→「添加机器人」→「自定义（通过Webhook接入自定义服务）」；
  2. 按提示填写机器人名称，完成创建后，务必保存系统生成的 Webhook URL 和加签密钥（Secret） ；

image.png image.png

image.png

image.png

image.png

03

项目集成：引入钉钉机器人 Starter 依赖

为了简化开发流程，我们直接使用封装好的 Spring Boot Starter 依赖，无需从零封装 HTTP 调用、签名逻辑。

依赖配置（pom.xml）

在项目的 pom.xml 文件中添加以下依赖：

<!-- 钉钉机器人Spring Boot Starter，简化消息推送开发 -->  
<dependency>  
    <groupId>cn.snowheart</groupId>  
    <artifactId>spring-boot-dingtalk-robot-starter</artifactId>  
    <version>1.0.3.RELEASE</version>  
</dependency>

04

核心配置：填写机器人关键信息（application.yml）

依赖引入后，需要在配置文件中配置机器人的 Webhook 前缀、access_token、加签密钥等核心信息，确保程序能正确连接钉钉机器人。

image.png

05

功能实现：编写消息发送接口（Controller）

配置完成后，我们可以编写 Controller 层代码，实现不同类型消息的发送逻辑。
下面以文本消息和Markdown消息为例，展示核心代码实现（已添加详细注解）。

完整代码示例

package com.example.controller;

import cn.snowheart.dingtalk.robot.starter.client.DingTalkRobotClient;
import cn.snowheart.dingtalk.robot.starter.entity.MarkdownMessage;
import cn.snowheart.dingtalk.robot.starter.entity.TextMessage;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.Date;

@RestController
public class DingTalkController {

    // 注入钉钉机器人客户端（由Starter自动装配）
    @Autowired
    private DingTalkRobotClient dingTalkRobotClient;

    /**
     * 发送纯文本消息接口
     * 访问路径：/sendText
     *
     * @return发送结果提示
     */
    @GetMapping("/sendText")
    public String sendTextMessage() {
        // 构造文本消息内容，建议添加业务标识（如【系统通知】），便于群内识别
        String messageContent = "【系统通知】这是一条来自Spring Boot应用的测试消息。";
        // 创建文本消息对象
        TextMessage textMessage = new TextMessage(messageContent);
        // 调用客户端发送消息
        dingTalkRobotClient.sendTextMessage(textMessage);
        // 返回友好提示（实际生产中可返回更详细的响应结果）
        return "文本消息发送请求已提交";
    }

    /**
     * 发送Markdown格式消息接口
     * 访问路径：/sendMarkdown
     *
     * @return发送结果提示
     */
    @GetMapping("/sendMarkdown")
    public String sendMarkdownMessage() {
        // Markdown消息标题（钉钉群内会显示该标题）
        String title = "业务监控警报";
        Date now = new Date();
        // Markdown消息内容，支持三级标题、加粗、换行等语法
        String content = "### 服务异常告警 \n\n **服务名称**: 用户中心 \n\n **异常时间**: " + now + "\n\n **状态**: 需要立即处理";
        // 创建Markdown消息对象
        MarkdownMessage markdownMessage = new MarkdownMessage(title, content);
        // 调用客户端发送Markdown消息
        dingTalkRobotClient.sendMarkdownMessage(markdownMessage);
        // 返回友好提示
        return "Markdown消息发送请求已提交";
    }

}

image.png

代码关键说明

  1. DingTalkRobotClient：由 Starter 自动装配的客户端对象，封装了消息发送、签名等核心逻辑；
  2. TextMessage/MarkdownMessage：Starter 提供的消息模型，对应钉钉的文本/Markdown消息类型；
  3. 接口采用 @GetMapping 注解，方便测试阶段直接通过浏览器/Postman调用，生产环境可根据业务调整为 @PostMapping。

06

安全保障：签名验证机制

钉钉机器人默认开启签名验证（配置 secret-token 后），目的是防止恶意调用机器人接口。

签名处理逻辑

  • • 如果使用本文推荐的 Starter，且在 application.yml 中配置了 secret-token，则无需手动处理签名，Starter 会自动根据 Secret + 时间戳生成签名，并拼接到请求URL中；
  • • 若未使用 Starter，需手动计算签名：基于 Secret 和当前时间戳（timestamp），通过HmacSHA256算法生成签名，再URL编码后附加到 Webhook URL 上。

07

进阶优化：提升消息推送的实用性与稳定性

丰富消息类型

除了文本、Markdown，钉钉机器人还支持 LinkMessage（链接卡片） 、ActionCard（行动卡片）  等类型：

• LinkMessage：适合推送带跳转链接的通知（如“查看详情”）； • ActionCard：适合推送带交互按钮的消息（如“确认处理”“忽略告警”）。

异步发送

对于非核心通知（如普通业务提醒），建议给消息发送方法添加 @Async 注解实现异步发送，避免阻塞主业务线程：

// 异步发送文本消息示例
@Async
public void asyncSendTextMessage(String content) {
    TextMessage message = new TextMessage(content);
    dingTalkRobotClient.sendTextMessage(message);
}

频率限制

钉钉对机器人消息有发送频率限制（单机器人每分钟最多20条），超出限制会触发限流，建议：

  1. 合并同类告警（如批量推送1分钟内的所有异常）；
  2. 对非紧急通知做延迟/排队处理。

总结

通过引入 Spring Boot 钉钉机器人 Starter，能快速完成消息推送集成，核心流程可总结为：

  1. 创建自定义机器人，获取 Webhook URL 和 Secret；
  2. 配置依赖和核心参数；
  3. 调用客户端API发送不同类型消息；
  4. 结合异步、频率控制等优化手段，提升稳定性。

本文覆盖了基础集成流程和核心优化点，若需实现更复杂的交互（如带按钮的ActionCard）或异常处理（如消息发送失败重试），可根据业务场景进一步扩展。

avatar
文章
阅读
粉丝