92 lines
2.7 KiB
Markdown
92 lines
2.7 KiB
Markdown
|
# 前端 API 路径对齐修复总结
|
|||
|
|
|
|||
|
|
## 修复日期
|
|||
|
|
2026-03-13
|
|||
|
|
|
|||
|
|
## 问题背景
|
|||
|
|
|
|||
|
|
后端所有 Controller 统一使用 `/api/v1/` 前缀：
|
|||
|
|
- 超管端：`/api/v1/admin/*`
|
|||
|
|
- 学校端：`/api/v1/school/*`
|
|||
|
|
- 教师端：`/api/v1/teacher/*`
|
|||
|
|
- 家长端：`/api/v1/parent/*`
|
|||
|
|
- 认证：`/api/v1/auth/*`
|
|||
|
|
- 文件：`/api/v1/files/*`
|
|||
|
|
|
|||
|
|
但前端适配层的 API 路径缺少 `/v1` 前缀，导致请求失败。
|
|||
|
|
|
|||
|
|
## 修复的文件
|
|||
|
|
|
|||
|
|
### 1. 适配层文件（手动修复）
|
|||
|
|
|
|||
|
|
| 文件 | 修复内容 |
|
|||
|
|
|------|----------|
|
|||
|
|
| `src/api/auth.ts` | `/auth/xxx` → `/v1/auth/xxx` |
|
|||
|
|
| `src/api/school.ts` | `/school/xxx` → `/v1/school/xxx` |
|
|||
|
|
| `src/api/teacher.ts` | 使用生成的 API，无需手动修复 |
|
|||
|
|
| `src/api/parent.ts` | `/parent/xxx` → `/v1/parent/xxx` |
|
|||
|
|
| `src/api/growth.ts` | `/school/xxx` → `/v1/school/xxx`<br>`/teacher/xxx` → `/v1/teacher/xxx` |
|
|||
|
|
| `src/api/task.ts` | `/school/xxx` → `/v1/school/xxx`<br>`/teacher/xxx` → `/v1/teacher/xxx` |
|
|||
|
|
| `src/api/resource.ts` | `/admin/xxx` → `/v1/admin/xxx` |
|
|||
|
|
| `src/api/package.ts` | `/school/xxx` → `/v1/school/xxx` |
|
|||
|
|
| `src/api/file.ts` | 已正确使用 `/api/v1/files` ✅ |
|
|||
|
|
|
|||
|
|
### 2. 生成的 API 文件（自动修复）
|
|||
|
|
|
|||
|
|
| 文件 | 修复方式 |
|
|||
|
|
|------|----------|
|
|||
|
|
| `src/api/generated/index.ts` | 使用 sed 批量替换：<br>`/api/xxx` → `/api/v1/xxx` |
|
|||
|
|
|
|||
|
|
### 3. Orval 配置（预防未来问题）
|
|||
|
|
|
|||
|
|
| 文件 | 修复内容 |
|
|||
|
|
|------|----------|
|
|||
|
|
| `orval.config.ts` | 添加 transformer 配置，在生成时自动修复路径 |
|
|||
|
|
|
|||
|
|
## 验证方法
|
|||
|
|
|
|||
|
|
### 1. 启动服务
|
|||
|
|
```bash
|
|||
|
|
# 启动后端
|
|||
|
|
cd reading-platform-java
|
|||
|
|
mvn spring-boot:run
|
|||
|
|
|
|||
|
|
# 启动前端（新终端）
|
|||
|
|
cd reading-platform-frontend
|
|||
|
|
npm run dev
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 2. 测试 API 调用
|
|||
|
|
使用浏览器开发者工具检查 API 请求路径：
|
|||
|
|
- 登录功能（`/v1/auth/login`）
|
|||
|
|
- 学校端接口（`/v1/school/xxx`）
|
|||
|
|
- 教师端接口（`/v1/teacher/xxx`）
|
|||
|
|
- 家长端接口（`/v1/parent/xxx`）
|
|||
|
|
- 超管端接口（`/v1/admin/xxx`）
|
|||
|
|
|
|||
|
|
### 3. 运行 E2E 测试
|
|||
|
|
```bash
|
|||
|
|
npm run test:e2e
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 注意事项
|
|||
|
|
|
|||
|
|
1. **生成的 API 文件**: `src/api/generated/index.ts` 是 Orval 自动生成的，不应手动修改
|
|||
|
|
2. **重新生成**: 当需要重新生成 API 时，确保后端服务正在运行，然后执行：
|
|||
|
|
```bash
|
|||
|
|
npm run api:update
|
|||
|
|
```
|
|||
|
|
3. **orval 配置**: `orval.config.ts` 中已添加 transformer，下次生成时会自动修复路径
|
|||
|
|
|
|||
|
|
## 修复完成检查清单
|
|||
|
|
|
|||
|
|
- [x] auth.ts API 路径修复
|
|||
|
|
- [x] school.ts API 路径修复
|
|||
|
|
- [x] parent.ts API 路径修复
|
|||
|
|
- [x] growth.ts API 路径修复
|
|||
|
|
- [x] task.ts API 路径修复
|
|||
|
|
- [x] resource.ts API 路径修复
|
|||
|
|
- [x] package.ts API 路径修复
|
|||
|
|
- [x] generated/index.ts 路径修复
|
|||
|
|
- [x] orval.config.ts 配置更新
|