---
name: exception-handling-spec
description: 异常处理规格模板
---

# 异常处理规格模板

## 并发请求处理 ⚠️ 必填

| 场景 | 处理策略 | 实现方式 | 用户反馈 |
|------|----------|----------|----------|
| 快速重复点击 | 防重复提交 | 按钮loading+禁用 | 按钮显示加载状态 |
| 多次搜索 | 取消前次请求 | AbortController | 只显示最新结果 |
| 分页快速切换 | 取消前次请求 | AbortController | 只显示当前页 |
| 表单多次提交 | 幂等键 | X-Idempotency-Key | 返回首次结果 |

## 请求生命周期 ⚠️ 必填

| 场景 | 处理策略 | 说明 |
|------|----------|------|
| 页面切换时有未完成请求 | 取消请求 | 组件卸载时取消 |
| 请求超时 | 自动重试1次 | 超时时间10秒 |
| 请求失败 | 显示错误+重试按钮 | 用户可手动重试 |
| 网络断开 | 显示离线提示 | 恢复后自动重试 |

## Token/登录态处理 ⚠️ 必填

| 场景 | 检测方式 | 处理策略 | 用户体验 |
|------|----------|----------|----------|
| Token过期 | 401响应 | 尝试刷新Token | 静默刷新，用户无感 |
| 刷新Token失败 | 刷新接口失败 | 跳转登录页 | 保存当前页面URL |
| 操作中Token过期 | 401响应 | 弹窗提示重新登录 | "登录已过期，请重新登录" |
| 多标签页登出 | storage事件 | 同步登出 | 所有标签页跳转登录 |
| 账号被踢 | WebSocket推送 | 强制登出 | "账号在其他设备登录" |

## 网络异常处理 ⚠️ 必填

| 网络状态 | 检测方式 | 处理策略 | 用户提示 |
|----------|----------|----------|----------|
| 断网 | navigator.onLine | 显示离线banner | "网络已断开" |
| 恢复网络 | online事件 | 自动重试失败请求 | "网络已恢复" |
| 弱网 | 请求耗时>3秒 | 显示加载进度 | 显示加载百分比 |
| 请求超时 | 超时10秒 | 提示重试 | "请求超时，请重试" |

## 浏览器行为处理 ⚠️ 必填

| 场景 | 处理策略 | 实现方式 |
|------|----------|----------|
| 页面刷新 | 恢复状态 | 关键状态存localStorage |
| 浏览器后退 | 确认提示 | beforeunload事件 |
| 关闭标签页 | 确认提示 | beforeunload事件 |
| 前进/后退 | 恢复滚动位置 | scrollRestoration |

### 表单未保存提示
```
触发条件：表单有修改且未保存
提示文案："您有未保存的更改，确定要离开吗？"
按钮：[取消] [离开]
```

## 多标签页同步 ⚠️ 必填

| 数据类型 | 同步策略 | 实现方式 |
|----------|----------|----------|
| 登录状态 | 实时同步 | storage事件监听 |
| 用户信息 | 实时同步 | storage事件监听 |
| 主题设置 | 实时同步 | storage事件监听 |
| 业务数据 | 不同步 | 各标签页独立 |

## 错误边界处理 ⚠️ 必填

| 错误类型 | 捕获方式 | 处理策略 | 用户体验 |
|----------|----------|----------|----------|
| 组件渲染错误 | ErrorBoundary | 显示降级UI | "页面出错，请刷新" |
| JS运行时错误 | window.onerror | 上报+提示 | toast提示 |
| Promise未捕获 | unhandledrejection | 上报+静默 | 不打扰用户 |
| 资源加载失败 | error事件 | 重试/降级 | 显示占位图 |

## 降级策略 ⚠️ 必填

| 功能 | 降级条件 | 降级方案 |
|------|----------|----------|
| 图片加载 | 加载失败 | 显示占位图 |
| 字体加载 | 加载失败 | 使用系统字体 |
| 第三方服务 | 服务不可用 | 隐藏相关功能 |
| WebSocket | 连接失败 | 降级为轮询 |
| 本地存储 | 存储已满 | 清理旧数据 |

