110 lines
3.2 KiB
Markdown
110 lines
3.2 KiB
Markdown
# 钉钉通知集成说明
|
||
|
||
## 功能概述
|
||
|
||
本项目已成功集成钉钉机器人通知功能，与现有的 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 配置
|
||
```yaml
|
||
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` - 测试所有通知方式
|
||
|
||
### 使用示例
|
||
|
||
```bash
|
||
# 测试钉钉通知
|
||
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 使用
|
||
|
||
```kotlin
|
||
@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. 建议在生产环境中配置错误重试机制 |