hoperun-custom-sign/DINGTALK_SETUP.md

钉钉通知集成说明

功能概述

本项目已成功集成钉钉机器人通知功能，与现有的 ServerChan3 通知系统并存，提供多渠道消息通知能力。

新增文件

1. 配置类

• src/main/kotlin/com/pomelotea/hoperun/sign/config/DingTalkConfig.kt - 钉钉配置类

2. 数据模型

• src/main/kotlin/com/pomelotea/hoperun/sign/api/model/DingTalkNotifyRequest.kt - 钉钉消息请求/响应模型

3. 通知助手

• src/main/kotlin/com/pomelotea/hoperun/sign/notify/DingTalkNotifyHelper.kt - 钉钉通知助手类

4. 统一通知服务

• src/main/kotlin/com/pomelotea/hoperun/sign/service/NotificationService.kt - 统一管理多种通知方式

配置说明

application-dev.yml 配置

dingtalk:
  enabled: false                                      # 是否启用钉钉通知
  webhook: https://oapi.dingtalk.com/robot/send?access_token=YOUR_ACCESS_TOKEN
  secret: YOUR_SECRET                                 # 钉钉机器人密钥（可选）

获取钉钉机器人信息

1. 在钉钉群中添加"自定义机器人"
2. 安全设置选择"加签"，获取密钥
3. 获取 Webhook 地址
4. 将配置信息填入 application-dev.yml

API 接口

测试接口

• GET /api/daka/test/dingtalk - 测试钉钉通知
• GET /api/daka/test/serverchan - 测试ServerChan3通知
• GET /api/daka/test/all - 测试所有通知方式

使用示例

# 测试钉钉通知
curl http://localhost:8982/api/daka/test/dingtalk

# 测试ServerChan3通知
curl http://localhost:8982/api/daka/test/serverchan

# 测试所有通知
curl http://localhost:8982/api/daka/test/all

编程接口

NotificationService 使用

@Autowired
private lateinit var notificationService: NotificationService

// 发送所有类型的通知
notificationService.sendAllNotifications("标题", "内容")

// 只发送钉钉通知
val response = notificationService.sendDingTalkNotification("标题", "内容")

// 只发送ServerChan3通知
val response = notificationService.sendServerChanNotification("标题", "内容")

// 发送钉钉文本消息
val response = notificationService.sendDingTalkText("纯文本消息")

// 发送钉钉Markdown消息
val response = notificationService.sendDingTalkMarkdown("标题", "**Markdown** 内容")

功能特性

消息类型支持

• 文本消息: 简单文本内容
• Markdown消息: 支持丰富的格式化内容

安全特性

• 支持钉钉机器人加签验证
• 自动URL签名生成
• 错误处理和日志记录

智能切换

• 自动检测配置有效性
• 支持同时启用多种通知方式
• 配置错误时自动跳过对应通知

使用建议

1. 开发测试: 先使用测试接口验证配置正确性
2. 生产部署: 确保 enabled: true 并填入正确的 webhook 和 secret
3. 消息格式: 建议使用 Markdown 格式，支持更丰富的展示效果
4. 监控日志: 关注应用日志，及时发现通知发送问题

注意事项

1. 确保钉钉机器人在群中有发送消息权限
2. Webhook 地址不要泄露到公开仓库
3. 消息发送频率不要超过钉钉限制（通常每分钟最多20条）
4. 建议在生产环境中配置错误重试机制