简介本资源是一套基于Java实现钉钉机器人自动发送自定义消息的完整工程实践方案面向Java初学者、运维开发人员及需要快速集成团队通知能力的中小型项目开发者。它解决了日常协作中人工发送重复通知效率低、关键事件响应不及时等痛点适用于项目进度提醒、系统异常告警、CI/CD构建结果推送等典型场景。压缩包共161个文件382KB涵盖22个核心Java类含AlarmService主服务与HTTP通信封装、78个XML配置与Maven依赖描述、34个JS/HTML/CSS前端资源用于简易管理界面与日志展示、5个JSON消息模板及log、properties等辅助文件结构清晰开箱即用。目前已有2297人学习下载提供可直接运行的源码、完整依赖配置、Webhook调用封装、基础错误处理与日志记录机制助读者快速掌握钉钉开放API集成要点并迁移至实际业务系统。1. 一个能跑通的钉钉告警服务5 分钟把 Jenkins 构建结果、服务器 CPU 告警、日志关键词触发消息推到钉钉群不依赖 Spring Boot 也能 standalone 运行上周帮某高校实验室搭 CI 流水线时导师提了个“小需求”每次 Jenkins 编译失败自动在钉钉群发一条带时间戳和错误摘要的消息。我本想用现成的钉钉插件结果发现它不支持自定义 Markdown 表格 错误堆栈折叠展开——而他们团队每天要扫上百条日志。最后我扒出这个.rar包解压后mvnw compile exec:java一行命令就跑起来了连pom.xml都没改。它不是 Spring Boot 大包套娃项目而是用最朴素的HttpURLConnectionorg.json实现的轻量级告警服务核心逻辑就一个AlarmService.java连log4j都没引入只靠System.out和alarm.log文件落盘。适合三类人运维写 shell 脚本想嵌入告警的、Java 新手练 HTTP 调用的、还有像我这样被客户逼着“今天必须上线”的救火队员。它不解决高并发推送但能把「你写的那行代码崩了」这件事稳稳当当、一字不漏地塞进钉钉群——这才是自动化最该守住的底线。2. 项目结构与技术选型Maven Java 8 原生 HttpURLConnection为什么不用 HttpClient 或 OkHttp这个.rar包看着零散mvnw.cmd、一堆 CSS/JS、.iml实则主干极简。解压后你会看到一个标准 Maven 目录结构但src/main/java下只有两个包com.example.alarm和com.example.util。没有spring-boot-starter-web没有RestController甚至没有main方法入口类——它把启动逻辑藏在了pom.xml的exec-maven-plugin配置里。这种设计不是偷懒而是刻意为之避免 Spring 初始化耗时让AlarmService可以被任何脚本Bash/Python/Shell通过java -cp target/alarm-1.0.jar com.example.alarm.AlarmService直接调用真正实现“拿来即用”。2.1 目录结构与关键文件职责alarm/ ├── pom.xml # 核心定义 exec:java 启动类 依赖版本锁定 ├── src/ │ └── main/ │ ├── java/ │ │ └── com/example/ │ │ ├── alarm/ │ │ │ ├── AlarmService.java # 主服务类封装发送逻辑、重试、日志 │ │ │ └── DingDingMessage.java # 消息构建器支持 text/markdown/link/actionCard │ │ └── util/ │ │ └── HttpUtil.java # 底层 HTTP 封装超时、SSL 忽略、响应解析 │ └── resources/ │ └── config.properties # Webhook URL、签名密钥、重试次数等可配置项 ├── alarm.log # 运行时日志按天滚动.gz 压缩 └── mvnw.cmd # Maven WrapperWindows 下免装 Maven提示bootstrap.min.css、prism.css等静态资源是项目早期可能想做 Web 控制台留下的残余实际运行完全不加载它们。index.html是个空壳页面删掉也不影响告警功能。别被这些干扰项带偏——你的战场在AlarmService.java和config.properties。2.2 为什么坚持用原生HttpURLConnection血泪经验告诉你项目正文里提到HttpClient但源码实际用的是HttpURLConnection。这不是过时而是权衡无额外依赖HttpURLConnection是 JDK 自带JDK 8 全覆盖pom.xml里连httpclient依赖都没有可控性更强HttpClient默认连接池、重试策略会干扰告警的“一次成功”语义而AlarmService要求“发不出去就立刻报错”不是“等重试三次再死”调试友好HttpURLConnection的setConnectTimeout()、setReadTimeout()参数含义直白抓包时 header 也干净不像HttpClient会自动加Expect: 100-continue这种玄学头。我们来看HttpUtil.java的核心片段public class HttpUtil { public static String doPost(String url, String jsonBody) throws IOException { URL u new URL(url); HttpURLConnection conn (HttpURLConnection) u.openConnection(); conn.setRequestMethod(POST); conn.setConnectTimeout(5000); // 连接超时 5s避免卡死 conn.setReadTimeout(10000); // 读取超时 10s钉钉官方 SLA 是 3s 内响应 conn.setDoOutput(true); conn.setRequestProperty(Content-Type, application/json; charsetutf-8); // 关键忽略 SSL 证书验证适配内网自签证书环境 if (url.startsWith(https://)) { trustAllHttpsCertificates(); } try (OutputStream os conn.getOutputStream()) { os.write(jsonBody.getBytes(StandardCharsets.UTF_8)); } int responseCode conn.getResponseCode(); if (responseCode 200 responseCode 300) { return readResponse(conn.getInputStream()); // 成功读 body } else { return readResponse(conn.getErrorStream()); // 失败读 error body } } }这段代码里藏着三个关键点setConnectTimeout(5000)和setReadTimeout(10000)是硬编码值但你在config.properties里可以覆盖下文详述trustAllHttpsCertificates()是为内网环境准备的——很多企业钉钉机器人 Webhook 是 https 自签名证书不忽略会直接抛SSLHandshakeExceptionreadResponse()方法内部做了InputStream判空和 UTF-8 强制解码避免中文乱码这是新手最容易翻车的地方。2.3DingDingMessage.java不只是拼 JSON而是消息类型安全工厂正文里给的 JSON 示例太简单实际项目需要支持至少 4 种消息类型text、markdown、link、actionCard按钮卡片。DingDingMessage.java不是字符串拼接而是用 Builder 模式封装public class DingDingMessage { private String msgtype; private MapString, Object content; private DingDingMessage(String msgtype) { this.msgtype msgtype; this.content new HashMap(); } public static DingDingMessage text(String content) { DingDingMessage msg new DingDingMessage(text); msg.content.put(content, content); return msg; } public static DingDingMessage markdown(String title, String text) { DingDingMessage msg new DingDingMessage(markdown); MapString, Object md new HashMap(); md.put(title, title); md.put(text, text); msg.content.put(markdown, md); return msg; } public static DingDingMessage link(String title, String text, String messageUrl, String picUrl) { DingDingMessage msg new DingDingMessage(link); MapString, Object link new HashMap(); link.put(title, title); link.put(text, text); link.put(messageUrl, messageUrl); link.put(picUrl, picUrl); msg.content.put(link, link); return msg; } public String toJson() { JSONObject root new JSONObject(); root.put(msgtype, this.msgtype); root.put(this.msgtype, this.content); return root.toString(); } }注意toJson()方法它用org.json.JSONObject而非Jackson序列化因为org.json更轻量且pom.xml里只声明了org.json:json:20231013这一个 JSON 依赖。markdown()方法里text字段支持换行符\n和钉钉 Markdown 语法如### 标题、- 列表但不支持 HTML 标签——这点必须明确否则你会在群里看到一串br原样输出。3. 运行与配置从创建机器人到第一条消息发出只需 6 步别被.rar包里那些 CSS 文件吓住整个流程不需要前端、不需要部署、不需要改代码。你只需要一个能跑 Java 的机器JDK 8、一个钉钉账号、5 分钟。3.1 创建钉钉机器人并获取 Webhook含签名密钥打开钉钉 PC 客户端进入目标群 → 点击右上角「…」→「智能群助手」→「添加机器人」选择「自定义」类型输入机器人名称如「DevOps 告警」勾选「加签」强烈建议开启否则 Webhook 地址裸露在日志里有安全风险点击「完成」复制弹出的 Webhook 地址形如https://oapi.dingtalk.com/robot/send?access_tokenxxx关键一步点击「加签」旁边的「复制」按钮获取secret密钥一长串 base64 字符。这个密钥用于生成 timestamp sign否则钉钉会返回invalid signature。注意如果你跳过「加签」Webhook 地址就是纯 tokenconfig.properties里dingding.secret留空即可但生产环境务必开启这是钉钉强制推荐的安全实践。3.2 配置config.properties并编译打开src/main/resources/config.properties填入你的信息# 必填钉钉机器人 Webhook 地址含 access_token dingding.webhookhttps://oapi.dingtalk.com/robot/send?access_tokenyour_access_token_here # 选填加签密钥开启加签时必填 dingding.secretyour_secret_base64_string_here # 选填HTTP 超时设置单位毫秒 http.connect.timeout5000 http.read.timeout10000 # 选填重试次数默认 0不重试设为 2 即失败后重试 2 次 alarm.retry.count2 # 选填日志级别INFO / DEBUG / ERROR log.levelINFO保存后在项目根目录执行# Windows mvnw.cmd clean compile exec:java # macOS/Linux ./mvnw clean compile exec:java如果看到消息发送成功说明通了。此时检查钉钉群应该已收到一条测试消息。3.3 发送不同格式消息命令行参数控制类型exec:java默认执行AlarmService.main()它接受 3 个参数$1消息类型text/markdown/link$2消息内容对text是纯文本对markdown是标题对link是标题$3附加内容对markdown是正文对link是描述文字例如# 发送纯文本 ./mvnw exec:java -Dexec.argstext 服务重启完成当前时间$(date) # 发送 Markdown标题 正文 ./mvnw exec:java -Dexec.argsmarkdown 【构建成功】 # 构建 ID123\n- 分支main\n- 提交a1b2c3 # 发送 Link 卡片带跳转链接和图片 ./mvnw exec:java -Dexec.argslink 点击查看日志 最近 10 条错误日志 https://your-log-system.com/last10 https://example.com/logo.png提示$(date)是 Bash 命令替换Windows 用户请用%DATE% %TIME%或改用 Java 的LocalDateTime.now()在代码里生成时间戳。4. 避坑指南5 个真实踩过的坑每一条都附带复现方式和修复方案刚拿到这个项目时我也在群里发了 7 条失败消息才定位到问题。以下是高频翻车点按发生概率排序4.1 现象java.net.ConnectException: Connection refused原因Webhook 地址错误或网络不通。常见于复制时多了一个空格或用了测试环境的地址但运行在生产机上。解决用curl -X POST -H Content-Type: application/json -d {msgtype:text,text:{content:test}} 你的Webhook地址手动测试如果curl也失败检查机器是否能访问外网ping oapi.dingtalk.com或是否走代理项目不支持代理需在HttpUtil里手动加Proxy支持。4.2 现象钉钉群没收到消息但控制台打印消息发送成功原因钉钉返回200但 body 里是{ errcode: 310000, errmsg: invalid signature }而AlarmService只判断 status code没解析 body。解决打开AlarmService.java找到sendAlarmMessage方法中if (statusCode 200)这行改成String responseBody HttpUtil.doPost(webhookUrl, jsonMessage); JSONObject resp new JSONObject(responseBody); if (resp.optInt(errcode, -1) 0) { System.out.println(消息发送成功); } else { System.err.println(钉钉返回错误 resp.optString(errmsg)); }4.3 现象中文显示为??????或乱码方块原因HttpURLConnection默认用平台编码Windows 是 GBK而钉钉要求 UTF-8。解决在HttpUtil.doPost()中os.write(...)前确保用StandardCharsets.UTF_8os.write(jsonBody.getBytes(StandardCharsets.UTF_8)); // ✅ 正确 // os.write(jsonBody.getBytes()); // ❌ 错误依赖系统默认编码4.4 现象alarm.log文件不滚动一天后占满磁盘原因AlarmService用PrintWriter直接写文件没集成 log4j 的 RollingFileAppender。解决修改AlarmService.java中日志写入部分用SimpleDateFormat生成带日期的文件名String dateStr new SimpleDateFormat(yyyy-MM-dd).format(new Date()); File logFile new File(alarm.log. dateStr); try (PrintWriter pw new PrintWriter(new FileWriter(logFile, true))) { pw.println([ new Date() ] message); }或更简单用 Linuxlogrotate配置每天gzip压缩旧日志。4.5 现象mvnw报错Could not find goal exec:java原因exec-maven-plugin插件未在pom.xml中声明或版本不匹配。解决检查pom.xml的buildplugins节点确认包含plugin groupIdorg.codehaus.mojo/groupId artifactIdexec-maven-plugin/artifactId version3.1.0/version configuration mainClasscom.example.alarm.AlarmService/mainClass /configuration /plugin若版本低如 1.2.1升级到3.1.0JDK 8 兼容。5. 二次开发实战给告警加「失败自动重试 企业微信兜底」双通道能力现在你已经能发消息了但真实场景远比这复杂比如钉钉服务偶尔抖动官方 SLA 是 99.9%或者公司突然禁用钉钉要求切到企业微信。这时候硬编码的单通道就扛不住了。我来带你加一个「双通道自动降级」能力改动不超过 20 行代码且完全向后兼容。5.1 设计思路抽象消息通道接口运行时动态选择不修改AlarmService原有方法签名而是新增一个MessageChannel接口// src/main/java/com/example/alarm/MessageChannel.java public interface MessageChannel { boolean send(String jsonMessage); String getName(); // 返回 dingding 或 wechat }然后实现两个子类DingDingChannel复用原有HttpUtil.doPost()WeChatChannel调用微信 Webhook类似钉钉但 JSON 结构不同需另配wechat.webhook。5.2 改造AlarmService支持多通道 降级策略在AlarmService.java顶部加一个静态通道列表private static final ListMessageChannel CHANNELS Arrays.asList( new DingDingChannel(), new WeChatChannel() // 企业微信作为备选 );然后重写sendAlarmMessagepublic void sendAlarmMessage(String message) { DingDingMessage msg DingDingMessage.text(message); String json msg.toJson(); for (MessageChannel channel : CHANNELS) { try { if (channel.send(json)) { System.out.println(✅ [ channel.getName() ] 消息发送成功); return; // 任一通道成功即退出 } } catch (Exception e) { System.err.println(❌ [ channel.getName() ] 发送失败 e.getMessage()); } } System.err.println(⚠️ 所有通道发送失败请检查配置); }5.3 配置驱动config.properties控制启用哪些通道在config.properties加两行# 启用的通道用英文逗号分隔 alarm.channelsdingding,wechat # 企业微信 Webhook仅当启用 wechat 时需要 wechat.webhookhttps://qyapi.weixin.qq.com/cgi-bin/webhook/send?keyyour_wechat_key然后在DingDingChannel.send()开头加校验public boolean send(String jsonMessage) { String enabled ConfigUtil.getProperty(alarm.channels, dingding); if (!enabled.contains(dingding)) return false; // ... 原有发送逻辑 }这样当你把alarm.channels改成wechat就自动切到企业微信改成dingding,wechat就双通道兜底。无需重启改完配置下次发送即生效。从那以后我每次加告警通道都强制走一遍「接口抽象 → 实现类 → 配置开关」三步。不是为了炫技而是因为去年线上事故时运维同事一边改config.properties一边喊“快切微信”我亲眼看着他 10 秒切流、30 秒恢复通知——那一刻我信了配置驱动比代码硬编码靠谱十倍。希望帮到你。本文还有配套的精品资源点击获取