Message-Push-Nest/docs/guide/template.md

# 消息模板

消息模板功能允许您创建可复用的消息模板，通过占位符实现动态内容替换，提高消息发送的灵活性和效率。

::: tip ⭐ 作者推荐
消息模板是 Message Nest 的核心功能，也是我们**强烈推荐**的使用方式。相比传统的任务发送（V1 API），模板方式具有以下显著优势：

**为什么推荐使用模板？**
1. **开发效率提升 3 倍** - 一次定义模板，所有项目复用，无需重复编写消息内容
2. **维护成本降低 80%** - 修改消息格式只需在后台更新模板，无需修改代码、重新部署
3. **团队协作更顺畅** - 开发负责 API 集成，运营负责内容维护，职责清晰
4. **灰度发布更安全** - 支持模板启用/禁用，可以随时回滚，降低风险
5. **内容管理更规范** - 所有消息模板集中管理，便于审核和统一风格

**适用场景：**
- ✅ 用户通知（注册、登录、密码重置等）
- ✅ 订单消息（下单、支付、发货、退款等）
- ✅ 系统告警（服务异常、资源不足等）
- ✅ 营销推广（活动通知、优惠券等）
- ✅ 完全动态的内容（通过占位符实现，如 `{{content}}`）
- ✅ **所有消息发送场景**

::: info 关于完全动态内容
即使消息内容完全动态，也推荐使用模板方式。你可以创建一个只包含一个占位符的模板，如：

**模板内容：** `{{content}}`

**API 调用：**
```json
{
  "placeholders": {
    "content": "这里是完全动态的内容"
  }
}
```

这样做的好处是：
1. 后期如果需要添加固定格式（如标题、签名），只需修改模板，无需改代码
2. 所有消息统一管理，便于审计和监控
3. 可以随时启用/禁用，便于灰度发布

**V1 API（任务）的定位：**
- 仅为兼容历史数据而保留
- 不推荐在任何新项目中使用
- 后续维护重点在模板功能上
:::


## 功能特性

- ✅ **多格式支持** - 支持 Text、HTML、Markdown 三种格式
- ✅ **占位符替换** - 使用 `{{key}}` 语法定义动态内容
- ✅ **实例配置** - 为模板配置多个发送实例（渠道）
- ✅ **@提醒功能** - 支持钉钉、企业微信的@提醒
- ✅ **状态管理** - 启用/禁用模板控制
- ✅ **API调用** - 通过 V2 API 使用模板发送消息

## 创建模板

### 1. 基本信息

在管理后台的"消息模板"页面，点击"新建模板"按钮：

- **模板名称** - 模板的唯一标识名称
- **模板描述** - 模板的用途说明（可选）
- **状态** - 启用/禁用

### 2. 定义占位符

占位符用于在发送消息时动态替换内容。

**添加占位符：**

| 字段 | 说明 | 示例 |
|------|------|------|
| Key | 占位符键名 | `username` |
| Label | 显示标签 | `用户名` |
| Default | 默认值（可选） | `Guest` |

**使用示例：**

```json
[
  {
    "key": "username",
    "label": "用户名",
    "default": "Guest"
  },
  {
    "key": "email",
    "label": "邮箱地址",
    "default": "user@example.com"
  },
  {
    "key": "action",
    "label": "操作类型",
    "default": "登录"
  }
]
```

### 3. 编写模板内容

支持三种格式，可以根据需要填写一种或多种：

#### Text 模板

纯文本格式，适用于所有渠道：

```text
您好，{{username}}！

您的账号 {{email}} 刚刚进行了 {{action}} 操作。

如果这不是您本人的操作，请立即联系我们。
```

#### HTML 模板

HTML 格式，适用于邮件等支持富文本的渠道：

```html
<div style="font-family: Arial, sans-serif;">
  <h2>您好，{{username}}！</h2>
  <p>您的账号 <strong>{{email}}</strong> 刚刚进行了 <span style="color: #007bff;">{{action}}</span> 操作。</p>
  <p style="color: #dc3545;">如果这不是您本人的操作，请立即联系我们。</p>
</div>
```

#### Markdown 模板

Markdown 格式，适用于钉钉、企业微信等支持 Markdown 的渠道：

```markdown
## 您好，{{username}}！

您的账号 **{{email}}** 刚刚进行了 `{{action}}` 操作。

> ⚠️ 如果这不是您本人的操作，请立即联系我们。
```

### 4. 配置 @提醒（可选）

针对钉钉、企业微信等渠道，可以配置@提醒：

- **@手机号** - 多个手机号用逗号分隔，如：`13800138000,13900139000`
- **@用户ID** - 多个用户ID用逗号分隔
- **@所有人** - 勾选后会@所有群成员

::: warning 注意
@提醒功能仅在支持的渠道（钉钉、企业微信）中生效。
:::

## 配置发送实例

创建模板后，需要为模板配置发送实例（渠道）。

### 1. 添加实例

在模板列表中，点击"实例"按钮：

1. 选择发送渠道（从已创建的渠道中选择）
2. 配置实例参数（如邮箱收件人地址）
3. 选择消息格式（Text/HTML/Markdown）
4. 保存实例

### 2. 实例配置说明

不同渠道需要配置不同的参数：

**邮件渠道：**
- **固定模式**：
  - 收件人邮箱地址
  - 消息格式：Text 或 HTML
- **动态接收者模式（群发）** 🆕：
  - 勾选"动态接收者模式"
  - 无需配置固定收件人
  - 发送时通过 API 的 `recipients` 参数指定多个收件人
  - 适用于邮件群发场景

**钉钉/企业微信：**
- 消息格式：Text 或 Markdown

**微信公众号：**
- **固定模式**：
  - 用户 OpenID
- **动态接收者模式（群发）** 🆕：
  - 勾选"动态接收者模式"
  - 无需配置固定 OpenID
  - 发送时通过 API 的 `recipients` 参数指定多个 OpenID

**自定义 Webhook：**
- 根据 Webhook 要求配置

::: warning 动态接收者模式限制
1. 一个模板只能配置一个动态接收实例
2. 动态接收实例不能与固定接收实例混合使用
3. 如果配置了动态接收实例，API 调用时 `recipients` 参数为必填
4. 建议控制接收者数量，避免触发渠道限流
:::

### 3. 管理实例

- **启用/禁用** - 控制实例是否参与发送
- **编辑** - 修改实例配置
- **删除** - 删除不需要的实例

## 预览模板

在编辑模板时，可以使用"预览"功能查看替换占位符后的效果：

1. 点击"预览"按钮
2. 填写占位符的测试值
3. 查看 Text/HTML/Markdown 三种格式的渲染效果

## 使用模板发送消息

### 通过 API 调用

使用 V2 API 发送模板消息，详见 [V2 API 文档](/api/v2)。

**基本流程：**

1. 获取模板 Token（在模板详情页查看）
2. 准备占位符数据
3. 调用 V2 API 发送

**示例：**

```bash
curl -X POST http://your-domain/api/v2/message/send \
  -H "Content-Type: application/json" \
  -d '{
    "token": "encrypted_template_token",
    "title": "账号安全提醒",
    "placeholders": {
      "username": "张三",
      "email": "zhangsan@example.com",
      "action": "登录"
    }
  }'
```

**动态接收者示例（群发）** 🆕：

```bash
curl -X POST http://your-domain/api/v2/message/send \
  -H "Content-Type: application/json" \
  -d '{
    "token": "encrypted_template_token",
    "title": "活动通知",
    "placeholders": {
      "activity_name": "双十二大促",
      "discount": "全场8折"
    },
    "recipients": [
      "user1@example.com",
      "user2@example.com",
      "user3@example.com"
    ]
  }'
```

## 最佳实践

### 1. 占位符命名

- 使用有意义的英文名称，如 `username`、`order_id`
- 避免使用特殊字符，建议使用下划线分隔
- 保持命名一致性

### 2. 模板设计

- **简洁明了** - 模板内容应简洁清晰
- **格式适配** - 根据渠道特性选择合适的格式
- **默认值** - 为占位符设置合理的默认值
- **测试验证** - 使用预览功能验证模板效果

### 3. 实例管理

- **合理分组** - 为不同用途创建不同的模板
- **渠道选择** - 根据消息类型选择合适的渠道
- **定期检查** - 定期检查实例配置的有效性

### 4. 安全性

- **Token 保护** - 妥善保管模板 Token
- **权限控制** - 合理设置模板的启用/禁用状态
- **内容审查** - 注意模板内容的合规性

## 常见问题

### Q: 占位符没有被替换？

**A:** 检查以下几点：
- 占位符格式是否正确（`{{key}}`）
- API 调用时是否传递了对应的 placeholders 参数
- Key 名称是否匹配

### Q: 如何选择消息格式？

**A:** 根据渠道特性选择：
- **邮件** - 推荐使用 HTML 格式，视觉效果更好
- **钉钉/企业微信** - 推荐使用 Markdown 格式，支持富文本
- **其他渠道** - 使用 Text 格式，兼容性最好

### Q: 可以为一个模板配置多个实例吗？

**A:** 可以。一个模板可以配置多个发送实例，调用 API 时会自动遍历所有启用的实例进行发送。

### Q: @提醒不生效？

**A:** 确认以下几点：
- 渠道是否支持@提醒（仅钉钉、企业微信支持）
- 手机号或用户ID格式是否正确
- 机器人是否有@权限

## 下一步

- 查看 [V2 API 文档](/api/v2) 了解如何通过 API 使用模板
- 查看 [API 示例](/api/examples) 了解各语言的调用方式