cc83b84c80
- 新增基于设备令牌的推送通知接口 - 添加推送测试服务，支持应用启动时自动测试 - 新增推送测试文档说明 - 更新 APNS 配置和日志记录 - 迁移至 apns2 库的 PushType 枚举 - 替换订阅密钥文件 - 添加项目规则文档
132 lines
3.3 KiB
Markdown
132 lines
3.3 KiB
Markdown
# 推送测试功能
|
||
|
||
本文档介绍如何使用推送测试功能，该功能可以在应用程序启动时自动获取表中的已有 token 进行消息推送。
|
||
|
||
## 功能概述
|
||
|
||
推送测试功能包括以下特性：
|
||
|
||
1. **自动测试**：应用程序启动时自动执行推送测试（可通过环境变量控制）
|
||
2. **手动触发**：通过 API 接口手动触发推送测试
|
||
3. **统计信息**：获取推送令牌的统计信息
|
||
4. **可配置内容**：可以自定义测试推送的标题和内容
|
||
|
||
## 环境变量配置
|
||
|
||
在 `.env` 文件中添加以下配置：
|
||
|
||
```env
|
||
# 推送测试配置
|
||
# 启用/禁用应用启动时的推送测试
|
||
ENABLE_PUSH_TEST=false
|
||
|
||
# 测试推送消息内容（可选，如果不提供将使用默认值）
|
||
PUSH_TEST_TITLE=测试推送
|
||
PUSH_TEST_BODY=这是一条测试推送消息，用于验证推送功能是否正常工作。
|
||
```
|
||
|
||
### 环境变量说明
|
||
|
||
- `ENABLE_PUSH_TEST`: 设置为 `true` 启用应用启动时的推送测试，设置为 `false` 禁用（默认为 `false`）
|
||
- `PUSH_TEST_TITLE`: 测试推送的标题（可选）
|
||
- `PUSH_TEST_BODY`: 测试推送的内容（可选）
|
||
|
||
## API 接口
|
||
|
||
### 1. 手动触发推送测试
|
||
|
||
**请求方式**: `POST`
|
||
**请求路径**: `/api/push-test/trigger`
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "Push test completed",
|
||
"data": {
|
||
"success": true,
|
||
"message": "Push test completed"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. 获取推送令牌统计信息
|
||
|
||
**请求方式**: `GET`
|
||
**请求路径**: `/api/push-test/stats`
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "获取推送令牌统计信息成功",
|
||
"data": {
|
||
"totalTokens": 100,
|
||
"activeTokens": 85,
|
||
"inactiveTokens": 15,
|
||
"recentlyActiveTokens": 60
|
||
}
|
||
}
|
||
```
|
||
|
||
## 工作原理
|
||
|
||
1. **自动测试流程**:
|
||
- 应用启动时，`PushTestService` 会检查 `ENABLE_PUSH_TEST` 环境变量
|
||
- 如果启用，服务会在应用完全启动后 5 秒执行推送测试
|
||
- 测试会获取最多 10 个活跃的推送令牌
|
||
- 向这些令牌发送测试推送消息
|
||
|
||
2. **手动测试流程**:
|
||
- 通过调用 `/api/push-test/trigger` 接口手动触发测试
|
||
- 测试流程与自动测试相同
|
||
|
||
3. **统计信息**:
|
||
- `totalTokens`: 总令牌数
|
||
- `activeTokens`: 活跃令牌数
|
||
- `inactiveTokens`: 非活跃令牌数
|
||
- `recentlyActiveTokens`: 最近 7 天活跃的令牌数
|
||
|
||
## 注意事项
|
||
|
||
1. **生产环境使用**:
|
||
- 在生产环境中使用前，请确保测试推送内容不会对用户造成困扰
|
||
- 建议在非高峰时段进行测试
|
||
|
||
2. **令牌限制**:
|
||
- 自动测试每次最多获取 10 个令牌，避免发送过多推送
|
||
- 只会向标记为 `isActive=true` 的令牌发送推送
|
||
|
||
3. **错误处理**:
|
||
- 如果推送失败，服务会记录详细的错误日志
|
||
- 无效的令牌会被自动标记为非活跃状态
|
||
|
||
## 日志记录
|
||
|
||
推送测试功能会记录以下日志：
|
||
|
||
- 测试开始和结束
|
||
- 发送成功和失败的统计
|
||
- 每个令牌的推送结果
|
||
- 错误详情
|
||
|
||
这些日志可以帮助排查推送问题。
|
||
|
||
## 示例用法
|
||
|
||
### 启用自动测试
|
||
|
||
1. 在 `.env` 文件中设置 `ENABLE_PUSH_TEST=true`
|
||
2. 重启应用程序
|
||
3. 查看日志确认测试是否成功执行
|
||
|
||
### 手动触发测试
|
||
|
||
```bash
|
||
curl -X POST http://localhost:3002/api/push-test/trigger
|
||
```
|
||
|
||
### 查看统计信息
|
||
|
||
```bash
|
||
curl -X GET http://localhost:3002/api/push-test/stats |