406 lines
11 KiB
Markdown
406 lines
11 KiB
Markdown
# Mock Service Worker 使用指南
|
||
|
||
本项目已集成 **Mock Service Worker (MSW)**，提供本地 Mock API 能力，无需依赖后端即可进行前端开发和测试。
|
||
|
||
## 📖 目录
|
||
|
||
1. [快速开始](#快速开始)
|
||
2. [启动方式](#启动方式)
|
||
3. [环境配置](#环境配置)
|
||
4. [Mock 数据说明](#mock-数据说明)
|
||
5. [如何添加新的 Mock API](#如何添加新的-mock-api)
|
||
6. [调试技巧](#调试技巧)
|
||
7. [常见问题](#常见问题)
|
||
|
||
---
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 方式一：启动 Mock 环境（使用本地 Mock 数据）
|
||
|
||
```bash
|
||
npm run start:mock
|
||
```
|
||
|
||
启动后，浏览器控制台会显示：
|
||
```
|
||
[MSW] Mock Service Worker 已启动 🎭
|
||
提示: 所有 API 请求将使用本地 Mock 数据
|
||
要禁用 Mock，请设置 REACT_APP_ENABLE_MOCK=false
|
||
```
|
||
|
||
### 方式二：启动开发环境（连接真实后端）
|
||
|
||
```bash
|
||
npm run start:dev
|
||
# 或者直接使用
|
||
npm start
|
||
```
|
||
|
||
---
|
||
|
||
## 📝 启动方式
|
||
|
||
| 命令 | 环境文件 | Mock 状态 | 用途 |
|
||
|------|---------|----------|------|
|
||
| `npm run start:mock` | `.env.mock` | ✅ 启用 | 本地开发，使用 Mock 数据 |
|
||
| `npm run start:dev` | `.env.development` | ❌ 禁用 | 连接真实后端 API |
|
||
| `npm start` | `.env` | ❌ 禁用 | 默认启动（连接后端） |
|
||
|
||
---
|
||
|
||
## ⚙️ 环境配置
|
||
|
||
### `.env.mock` - Mock 测试环境
|
||
|
||
```env
|
||
# 启用 Mock 数据
|
||
REACT_APP_ENABLE_MOCK=true
|
||
|
||
# Mock 模式下不需要真实的后端地址
|
||
REACT_APP_API_URL=http://localhost:3000
|
||
|
||
# Mock 环境标识
|
||
REACT_APP_ENV=mock
|
||
```
|
||
|
||
### `.env.development` - 开发环境
|
||
|
||
```env
|
||
# 禁用 Mock 数据
|
||
REACT_APP_ENABLE_MOCK=false
|
||
|
||
# 真实的后端 API 地址
|
||
REACT_APP_API_URL=http://49.232.185.254:5001
|
||
|
||
# 开发环境标识
|
||
REACT_APP_ENV=development
|
||
```
|
||
|
||
### 如何切换环境？
|
||
|
||
只需修改 `.env` 文件中的 `REACT_APP_ENABLE_MOCK` 参数：
|
||
|
||
```env
|
||
# 启用 Mock
|
||
REACT_APP_ENABLE_MOCK=true
|
||
|
||
# 禁用 Mock，使用真实 API
|
||
REACT_APP_ENABLE_MOCK=false
|
||
```
|
||
|
||
---
|
||
|
||
## 📦 Mock 数据说明
|
||
|
||
### 已实现的 Mock API
|
||
|
||
#### 1. **认证相关 API**
|
||
|
||
| API | 方法 | Mock 说明 |
|
||
|-----|------|----------|
|
||
| `/api/auth/send-verification-code` | POST | 发送验证码（控制台会打印验证码） |
|
||
| `/api/auth/login-with-code` | POST | 验证码登录（自动设置当前登录用户） |
|
||
| `/api/auth/wechat/qrcode` | GET | 获取微信二维码（10秒后自动模拟扫码） |
|
||
| `/api/auth/wechat/check-status` | POST | 检查微信扫码状态 |
|
||
| `/api/auth/wechat/login` | POST | 微信登录确认（自动设置当前登录用户） |
|
||
| `/api/auth/wechat/h5-auth-url` | POST | 获取微信 H5 授权链接 |
|
||
| `/api/auth/session` | GET | 检查 Session 状态（返回当前登录用户） |
|
||
| `/api/auth/check-session` | GET | 检查 Session 状态（旧端点，保留兼容） |
|
||
| `/api/auth/logout` | POST | 退出登录（清除当前登录用户） |
|
||
|
||
**登录状态管理**：
|
||
- Mock 系统会跟踪当前登录的用户
|
||
- 登录成功后，用户信息会保存到 Mock 状态中
|
||
- `/api/auth/session` 会返回当前登录用户的真实信息
|
||
- 退出登录会清除登录状态，下次检查 Session 返回未登录
|
||
|
||
#### 2. **账户管理 API**
|
||
|
||
| API | 方法 | Mock 说明 |
|
||
|-----|------|----------|
|
||
| `/api/account/profile-completeness` | GET | 获取用户资料完整度（需要登录） |
|
||
| `/api/account/profile` | GET | 获取用户资料（需要登录） |
|
||
| `/api/account/profile` | PUT | 更新用户资料（需要登录） |
|
||
| `/api/subscription/info` | GET | 获取订阅信息（会员类型、状态、到期时间） |
|
||
| `/api/subscription/permissions` | GET | 获取订阅权限（各功能的访问权限） |
|
||
|
||
**资料完整度说明**：
|
||
- 返回用户资料的完整度百分比（0-100%）
|
||
- 包含缺失项列表（密码、手机号、邮箱）
|
||
- 对微信登录用户，如果资料不完整会提示需要完善
|
||
- Mock 模式会根据当前登录用户的真实信息计算完整度
|
||
|
||
**订阅信息说明**：
|
||
- 返回当前用户的会员类型（free/pro/max）
|
||
- 包含订阅状态（active/expired）
|
||
- 返回到期时间和剩余天数
|
||
- 未登录用户默认返回 free 类型
|
||
|
||
### 测试账号
|
||
|
||
**手机号登录测试账号**：
|
||
|
||
| 手机号 | 验证码 | 用户昵称 | 会员类型 | 状态 | 到期时间 | 剩余天数 | 功能权限 |
|
||
|--------|--------|---------|---------|------|---------|---------|----------|
|
||
| `13800138000` | 控制台查看 | 测试用户 | **Free**（免费） | ✅ 激活 | - | - | 基础功能 |
|
||
| `13900139000` | 控制台查看 | Pro会员 | **Pro** | ✅ 激活 | 2025-12-31 | 90天 | 高级功能（除传导链外） |
|
||
| `13700137000` | 控制台查看 | Max会员 | **Max** | ✅ 激活 | 2026-12-31 | 365天 | 🎉 全部功能 |
|
||
| `13600136000` | 控制台查看 | 过期会员 | Pro（已过期） | ❌ 过期 | 2024-01-01 | -300天 | 基础功能 |
|
||
|
||
**会员权限对比**：
|
||
|
||
| 功能 | Free | Pro | Max |
|
||
|------|------|-----|-----|
|
||
| 相关标的 | ❌ | ✅ | ✅ |
|
||
| 相关概念 | ❌ | ✅ | ✅ |
|
||
| 事件传导链 | ❌ | ❌ | ✅ |
|
||
| 历史事件对比 | 🔒 限制版 | ✅ 完整版 | ✅ 完整版 |
|
||
| 概念详情 | ❌ | ✅ | ✅ |
|
||
| 概念统计中心 | ❌ | ✅ | ✅ |
|
||
| 概念相关股票 | ❌ | ✅ | ✅ |
|
||
| 概念历史时间轴 | ❌ | ❌ | ✅ |
|
||
| 热门个股 | ❌ | ✅ | ✅ |
|
||
|
||
**验证码说明**：
|
||
- 发送验证码后，控制台会打印验证码
|
||
- 示例：`[Mock] 验证码已生成: 13800138000 -> 123456`
|
||
- 验证码有效期：5分钟
|
||
- 所有测试账号都可以使用相同的验证码登录
|
||
|
||
**微信登录测试**：
|
||
1. 点击"获取二维码"
|
||
2. 等待 10 秒，自动模拟用户扫码
|
||
3. 再等待 5 秒，自动模拟用户确认
|
||
4. 登录成功
|
||
|
||
---
|
||
|
||
## 🛠️ 如何添加新的 Mock API
|
||
|
||
### 步骤 1：创建新的 Handler 文件
|
||
|
||
在 `src/mocks/handlers/` 目录下创建新文件，例如 `user.js`：
|
||
|
||
```javascript
|
||
// src/mocks/handlers/user.js
|
||
import { http, HttpResponse, delay } from 'msw';
|
||
|
||
const NETWORK_DELAY = 500;
|
||
|
||
export const userHandlers = [
|
||
// 获取用户信息
|
||
http.get('/api/user/profile', async () => {
|
||
await delay(NETWORK_DELAY);
|
||
|
||
return HttpResponse.json({
|
||
success: true,
|
||
data: {
|
||
id: 1,
|
||
nickname: '测试用户',
|
||
email: 'test@example.com',
|
||
avatar_url: 'https://i.pravatar.cc/150?img=1'
|
||
}
|
||
});
|
||
}),
|
||
|
||
// 更新用户信息
|
||
http.put('/api/user/profile', async ({ request }) => {
|
||
await delay(NETWORK_DELAY);
|
||
|
||
const body = await request.json();
|
||
|
||
return HttpResponse.json({
|
||
success: true,
|
||
message: '更新成功',
|
||
data: body
|
||
});
|
||
})
|
||
];
|
||
```
|
||
|
||
### 步骤 2：注册 Handler
|
||
|
||
在 `src/mocks/handlers/index.js` 中导入并注册：
|
||
|
||
```javascript
|
||
// src/mocks/handlers/index.js
|
||
import { authHandlers } from './auth';
|
||
import { userHandlers } from './user'; // 导入新的 handler
|
||
|
||
export const handlers = [
|
||
...authHandlers,
|
||
...userHandlers, // 注册新的 handler
|
||
];
|
||
```
|
||
|
||
### 步骤 3：重启应用
|
||
|
||
```bash
|
||
# 停止当前服务（Ctrl+C）
|
||
# 重新启动
|
||
npm run start:mock
|
||
```
|
||
|
||
---
|
||
|
||
## 🐛 调试技巧
|
||
|
||
### 1. 查看 Mock 日志
|
||
|
||
所有 Mock API 请求都会在浏览器控制台打印日志：
|
||
|
||
```
|
||
[Mock] 发送验证码: {credential: "13800138000", type: "phone", purpose: "login"}
|
||
[Mock] 验证码已生成: 13800138000 -> 654321
|
||
[Mock] 登录成功: {id: 1, phone: "13800138000", nickname: "测试用户", ...}
|
||
```
|
||
|
||
### 2. 检查 MSW 是否启动
|
||
|
||
打开浏览器控制台，查找以下消息：
|
||
|
||
```
|
||
[MSW] Mock Service Worker 已启动 🎭
|
||
```
|
||
|
||
如果没有看到此消息，检查：
|
||
1. `.env.mock` 文件中 `REACT_APP_ENABLE_MOCK=true`
|
||
2. 是否使用 `npm run start:mock` 启动
|
||
|
||
### 3. 网络面板调试
|
||
|
||
打开浏览器开发者工具 → Network 标签页：
|
||
- Mock 的请求会显示 `(from ServiceWorker)` 标签
|
||
- 可以查看请求和响应的详细信息
|
||
|
||
### 4. 模拟网络延迟
|
||
|
||
在 `src/mocks/handlers/*.js` 文件中修改延迟时间：
|
||
|
||
```javascript
|
||
const NETWORK_DELAY = 2000; // 改为 2 秒
|
||
```
|
||
|
||
### 5. 模拟错误响应
|
||
|
||
```javascript
|
||
http.post('/api/some-endpoint', async () => {
|
||
await delay(NETWORK_DELAY);
|
||
|
||
// 返回 400 错误
|
||
return HttpResponse.json({
|
||
success: false,
|
||
error: '参数错误'
|
||
}, { status: 400 });
|
||
});
|
||
```
|
||
|
||
---
|
||
|
||
## ❓ 常见问题
|
||
|
||
### Q1: Mock 没有生效，请求仍然发送到真实服务器
|
||
|
||
**解决方案**：
|
||
1. 检查 `.env.mock` 文件中 `REACT_APP_ENABLE_MOCK=true`
|
||
2. 确保使用 `npm run start:mock` 启动
|
||
3. 清除浏览器缓存并刷新页面
|
||
4. 检查控制台是否有 MSW 启动消息
|
||
|
||
### Q2: 控制台显示 `[MSW] 启动失败`
|
||
|
||
**解决方案**：
|
||
1. 确保 `public/mockServiceWorker.js` 文件存在
|
||
2. 重新初始化 MSW：
|
||
```bash
|
||
npx msw init public/ --save
|
||
```
|
||
3. 重启开发服务器
|
||
|
||
### Q3: 如何禁用某个特定 API 的 Mock？
|
||
|
||
在 `src/mocks/handlers/index.js` 中注释掉相应的 handler：
|
||
|
||
```javascript
|
||
export const handlers = [
|
||
...authHandlers,
|
||
// ...userHandlers, // 禁用 user 相关的 Mock
|
||
];
|
||
```
|
||
|
||
### Q4: 验证码是什么？
|
||
|
||
发送验证码后，控制台会打印验证码：
|
||
|
||
```
|
||
[Mock] 验证码已生成: 13800138000 -> 123456
|
||
```
|
||
|
||
复制 `123456` 并填入验证码输入框即可。
|
||
|
||
### Q5: 微信登录如何测试？
|
||
|
||
1. 点击"获取二维码"
|
||
2. 等待 10 秒（自动模拟扫码）
|
||
3. 再等待 5 秒（自动模拟确认）
|
||
4. 自动完成登录
|
||
|
||
或者在控制台查看 Mock 日志：
|
||
```
|
||
[Mock] 生成微信二维码: {sessionId: "wx_abc123", ...}
|
||
[Mock] 模拟用户扫码: wx_abc123
|
||
[Mock] 模拟用户确认登录: wx_abc123
|
||
```
|
||
|
||
### Q6: 生产环境会使用 Mock 数据吗？
|
||
|
||
**不会**。Mock 只在以下情况启用：
|
||
1. `NODE_ENV === 'development'`（开发环境）
|
||
2. `REACT_APP_ENABLE_MOCK === 'true'`
|
||
|
||
生产环境 (`npm run build`) 会自动排除 MSW 代码。
|
||
|
||
---
|
||
|
||
## 📁 项目结构
|
||
|
||
```
|
||
src/
|
||
├── mocks/
|
||
│ ├── handlers/
|
||
│ │ ├── auth.js # 认证相关 Mock
|
||
│ │ ├── index.js # Handler 总入口
|
||
│ │ └── ... # 其他 Handler 文件
|
||
│ ├── data/
|
||
│ │ └── users.js # Mock 用户数据
|
||
│ └── browser.js # MSW 浏览器 Worker
|
||
├── index.js # 应用入口（集成 MSW）
|
||
└── ...
|
||
|
||
public/
|
||
└── mockServiceWorker.js # MSW Service Worker 文件
|
||
```
|
||
|
||
---
|
||
|
||
## 📚 相关资源
|
||
|
||
- [MSW 官方文档](https://mswjs.io/)
|
||
- [MSW 快速开始](https://mswjs.io/docs/getting-started)
|
||
- [MSW API 参考](https://mswjs.io/docs/api)
|
||
|
||
---
|
||
|
||
## 🎯 最佳实践
|
||
|
||
1. **使用真实的响应结构**：Mock 数据应与真实 API 返回的数据结构一致
|
||
2. **添加网络延迟**：模拟真实的网络请求延迟，测试加载状态
|
||
3. **测试边界情况**：创建错误响应的 Mock，测试错误处理逻辑
|
||
4. **保持 Mock 数据更新**：当真实 API 变化时，及时更新 Mock handlers
|
||
5. **团队协作**：将 Mock 配置提交到 Git，团队成员共享
|
||
|
||
---
|
||
|
||
**提示**：如有任何问题或建议，请联系开发团队。Happy Mocking! 🎭
|