176 lines
4.6 KiB
Markdown
176 lines
4.6 KiB
Markdown
# AccessToken 自动重试机制说明
|
||
|
||
## 功能概述
|
||
|
||
已为小程序二维码生成功能添加了 AccessToken 失效自动检测和重试机制，确保在 Token 失效时能够自动恢复。
|
||
|
||
## 实现的功能
|
||
|
||
### 1. AccessToken 强制刷新支持
|
||
|
||
**方法**: `getWxAccessToken($appId, $appSecret, $forceRefresh = false)`
|
||
|
||
**新增参数**:
|
||
- `$forceRefresh` (bool): 是否强制刷新，不使用缓存
|
||
|
||
**功能**:
|
||
- 默认从缓存获取 AccessToken
|
||
- 当 `$forceRefresh = true` 时，清除缓存并重新获取
|
||
- 记录详细日志，便于追踪
|
||
|
||
**使用示例**:
|
||
```php
|
||
// 正常获取（使用缓存）
|
||
$token = self::getWxAccessToken($appId, $appSecret);
|
||
|
||
// 强制刷新（不使用缓存）
|
||
$token = self::getWxAccessToken($appId, $appSecret, true);
|
||
```
|
||
|
||
### 2. 自动重试机制
|
||
|
||
**方法**: `generateWxQrcode($config, $page, $scene, $retryCount = 0)`
|
||
|
||
**新增参数**:
|
||
- `$retryCount` (int): 当前重试次数，默认为 0
|
||
|
||
**工作流程**:
|
||
1. 首次调用时使用缓存的 AccessToken
|
||
2. 如果微信返回 40001 或 42001 错误（Token 失效）
|
||
3. 自动清除缓存
|
||
4. 递归调用自己，重试一次（`$retryCount + 1`）
|
||
5. 重试时强制刷新 AccessToken
|
||
6. 最多重试 1 次，避免无限循环
|
||
|
||
**错误码说明**:
|
||
- `40001`: invalid credential, access_token is invalid
|
||
- `42001`: access_token expired
|
||
|
||
## 使用场景
|
||
|
||
### 场景1: 正常生成（Token 有效）
|
||
```
|
||
用户点击生成 → 使用缓存Token → 成功生成二维码
|
||
```
|
||
|
||
### 场景2: Token 失效自动恢复
|
||
```
|
||
用户点击生成
|
||
→ 使用缓存Token
|
||
→ 微信返回40001错误
|
||
→ 自动清除缓存
|
||
→ 重新获取Token
|
||
→ 再次调用微信API
|
||
→ 成功生成二维码
|
||
```
|
||
|
||
### 场景3: 配置错误（无法恢复）
|
||
```
|
||
用户点击生成
|
||
→ 使用缓存Token
|
||
→ 微信返回40001错误
|
||
→ 自动重试
|
||
→ 重新获取Token失败（AppID/AppSecret错误）
|
||
→ 返回错误信息给用户
|
||
```
|
||
|
||
## 日志记录
|
||
|
||
所有关键步骤都会记录日志，便于追踪问题：
|
||
|
||
### 正常流程日志
|
||
```
|
||
[info] 使用缓存的AccessToken
|
||
[info] 开始生成小程序码 {"page":"...","scene":"...","app_id":"...","retry_count":0}
|
||
[info] 调用微信API生成小程序码 {"data":{...}}
|
||
[info] 小程序码生成成功 {"url":"...","retry_count":0}
|
||
```
|
||
|
||
### 自动重试流程日志
|
||
```
|
||
[info] 使用缓存的AccessToken
|
||
[info] 开始生成小程序码 {"page":"...","scene":"...","app_id":"...","retry_count":0}
|
||
[info] 调用微信API生成小程序码 {"data":{...}}
|
||
[error] 生成小程序码失败: errcode=40001, errmsg=invalid credential...
|
||
[info] AccessToken失效，自动重试（第1次）
|
||
[info] 强制刷新AccessToken，清除缓存
|
||
[info] 微信AccessToken响应: {"access_token":"...","expires_in":7200}
|
||
[info] AccessToken获取成功并已缓存
|
||
[info] 开始生成小程序码 {"page":"...","scene":"...","app_id":"...","retry_count":1}
|
||
[info] 调用微信API生成小程序码 {"data":{...}}
|
||
[info] 小程序码生成成功 {"url":"...","retry_count":1}
|
||
```
|
||
|
||
## 优势
|
||
|
||
### 1. 用户体验提升
|
||
- 无需手动清除缓存
|
||
- 无需重新点击按钮
|
||
- 自动恢复，对用户透明
|
||
|
||
### 2. 系统稳定性
|
||
- 自动处理 Token 失效
|
||
- 避免因缓存问题导致的失败
|
||
- 限制重试次数，防止无限循环
|
||
|
||
### 3. 问题排查
|
||
- 详细的日志记录
|
||
- 记录重试次数
|
||
- 便于追踪问题根源
|
||
|
||
## 注意事项
|
||
|
||
### 1. 重试限制
|
||
- 最多重试 1 次
|
||
- 避免无限递归
|
||
- 如果重试后仍失败，返回错误
|
||
|
||
### 2. 性能考虑
|
||
- 首次调用使用缓存，性能最优
|
||
- 重试时才强制刷新，影响可控
|
||
- 缓存时长 7000 秒，减少请求频率
|
||
|
||
### 3. 错误处理
|
||
- 配置错误（AppID/AppSecret）无法通过重试解决
|
||
- 网络问题可能导致重试失败
|
||
- 需要查看日志确定具体原因
|
||
|
||
## 测试建议
|
||
|
||
### 测试1: 正常流程
|
||
1. 配置正确的小程序信息
|
||
2. 首次生成二维码
|
||
3. 查看日志确认使用缓存
|
||
4. 验证生成成功
|
||
|
||
### 测试2: Token 失效恢复
|
||
1. 手动清除 AccessToken 缓存
|
||
```bash
|
||
php server/clear_wx_token_cache.php
|
||
```
|
||
2. 立即生成二维码
|
||
3. 查看日志确认自动重试
|
||
4. 验证生成成功
|
||
|
||
### 测试3: 配置错误
|
||
1. 故意配置错误的 AppSecret
|
||
2. 尝试生成二维码
|
||
3. 查看日志确认重试流程
|
||
4. 验证返回正确的错误信息
|
||
|
||
## 相关文档
|
||
|
||
- `QRCODE_README.md` - 完整文档导航
|
||
- `QRCODE_DEBUG_GUIDE.md` - 问题排查指南
|
||
- `QRCODE_QUICK_START.md` - 快速开始
|
||
|
||
## 版本信息
|
||
|
||
- 实现时间: 2024-03-06
|
||
- 版本: v1.1
|
||
- 状态: ✅ 已完成并测试
|
||
|
||
---
|
||
|
||
**重要提示**: 此机制大大提升了系统的健壮性，但不能解决配置错误问题。请确保 AppID 和 AppSecret 配置正确！
|