docs: Add API connection debugging documentation and progress update
Added comprehensive debugging tools and documentation for API connection issues. Changes: - Created test-api-connection.sh - Automated diagnostic script - Created DEBUGGING_GUIDE.md - Step-by-step debugging guide - Created API_CONNECTION_FIX_SUMMARY.md - Complete fix summary - Updated progress.md with API connection debugging enhancement entry These tools help diagnose and resolve frontend-backend connection issues. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Yaojia Wang
174
DEBUGGING_GUIDE.md
Normal file
174
DEBUGGING_GUIDE.md
Normal file
@@ -0,0 +1,174 @@
|
||||
# ColaFlow API 连接问题诊断指南
|
||||
|
||||
## 修复完成时间
|
||||
2025-11-03
|
||||
|
||||
## 问题描述
|
||||
项目列表页面无法显示项目数据，前端可以访问但无法连接到后端 API。
|
||||
|
||||
## 已实施的修复
|
||||
|
||||
### 1. 增强 API 客户端调试（lib/api/client.ts）
|
||||
- 添加了 API URL 的控制台日志输出
|
||||
- 为每个请求添加详细的日志记录
|
||||
- 增强错误处理和错误信息输出
|
||||
- 捕获网络错误并输出详细信息
|
||||
|
||||
### 2. 改进项目页面错误显示（app/(dashboard)/projects/page.tsx）
|
||||
- 显示详细的错误信息（而不是通用消息）
|
||||
- 显示当前使用的 API URL
|
||||
- 添加故障排查步骤
|
||||
- 添加重试按钮
|
||||
- 添加控制台调试日志
|
||||
|
||||
### 3. 增强 useProjects Hook（lib/hooks/use-projects.ts）
|
||||
- 添加详细的日志记录
|
||||
- 减少重试次数以更快失败（从 3次 降至 1次）
|
||||
- 捕获并记录所有错误
|
||||
|
||||
## 如何使用调试功能
|
||||
|
||||
### 步骤 1: 重启前端开发服务器
|
||||
```bash
|
||||
cd colaflow-web
|
||||
npm run dev
|
||||
```
|
||||
|
||||
重启是必要的，因为 Next.js 需要重新加载以应用环境变量更改。
|
||||
|
||||
### 步骤 2: 打开浏览器开发工具
|
||||
1. 访问 http://localhost:3000/projects
|
||||
2. 按 F12 打开开发者工具
|
||||
3. 切换到 Console 标签页
|
||||
|
||||
### 步骤 3: 查看控制台输出
|
||||
你应该看到以下日志：
|
||||
|
||||
```
|
||||
[API Client] API_URL: http://localhost:5167/api/v1
|
||||
[API Client] NEXT_PUBLIC_API_URL: http://localhost:5167/api/v1
|
||||
[useProjects] Fetching projects... {page: 1, pageSize: 20}
|
||||
[API Client] Request: {method: 'GET', url: 'http://localhost:5167/api/v1/projects?page=1&pageSize=20', endpoint: '/projects?page=1&pageSize=20'}
|
||||
```
|
||||
|
||||
如果出现错误，你会看到：
|
||||
```
|
||||
[API Client] Network error: {url: '...', error: 'Failed to fetch', errorObject: ...}
|
||||
[useProjects] Fetch failed: TypeError: Failed to fetch
|
||||
[ProjectsPage] Error loading projects: TypeError: Failed to fetch
|
||||
```
|
||||
|
||||
### 步骤 4: 检查网络请求
|
||||
1. 在开发者工具中切换到 Network 标签页
|
||||
2. 刷新页面
|
||||
3. 查找对 `http://localhost:5167/api/v1/projects` 的请求
|
||||
4. 检查请求状态：
|
||||
- **失败/红色**: 服务器未响应
|
||||
- **404**: 路由不存在
|
||||
- **500**: 服务器错误
|
||||
- **CORS错误**: 跨域配置问题
|
||||
|
||||
### 步骤 5: 查看错误屏幕
|
||||
如果 API 无法连接，页面会显示详细的错误卡片：
|
||||
- **Error Details**: 具体的错误消息
|
||||
- **API URL**: 当前配置的 API 地址
|
||||
- **Troubleshooting Steps**: 故障排查步骤
|
||||
- **Retry按钮**: 点击重试
|
||||
|
||||
## 常见问题诊断
|
||||
|
||||
### 问题 1: "Failed to fetch" 错误
|
||||
**原因**: 后端服务器未运行或无法访问
|
||||
|
||||
**解决方案**:
|
||||
```bash
|
||||
# 检查后端是否在运行
|
||||
curl http://localhost:5167/api/v1/health
|
||||
|
||||
# 如果失败，启动后端服务器
|
||||
cd ColaFlow.Api
|
||||
dotnet run
|
||||
```
|
||||
|
||||
### 问题 2: API URL 使用默认端口 5000
|
||||
**原因**: 环境变量未正确加载
|
||||
|
||||
**解决方案**:
|
||||
1. 检查 `.env.local` 文件是否存在且包含：
|
||||
```
|
||||
NEXT_PUBLIC_API_URL=http://localhost:5167/api/v1
|
||||
```
|
||||
2. 重启 Next.js 开发服务器
|
||||
3. 确保没有 `.env` 文件覆盖设置
|
||||
|
||||
### 问题 3: CORS 错误
|
||||
**原因**: 后端未配置允许前端域名
|
||||
|
||||
**解决方案**: 检查后端 CORS 配置（ColaFlow.Api/Program.cs）:
|
||||
```csharp
|
||||
builder.Services.AddCors(options =>
|
||||
{
|
||||
options.AddPolicy("AllowFrontend", policy =>
|
||||
{
|
||||
policy.WithOrigins("http://localhost:3000")
|
||||
.AllowAnyMethod()
|
||||
.AllowAnyHeader();
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
### 问题 4: 404 错误
|
||||
**原因**: API 路由不存在或路径不正确
|
||||
|
||||
**解决方案**:
|
||||
1. 检查后端路由配置
|
||||
2. 确认 API 前缀是 `/api/v1`
|
||||
3. 检查控制器路由是否正确
|
||||
|
||||
## 验证修复
|
||||
|
||||
### 成功的日志输出示例
|
||||
```
|
||||
[API Client] API_URL: http://localhost:5167/api/v1
|
||||
[useProjects] Fetching projects...
|
||||
[API Client] Request: GET http://localhost:5167/api/v1/projects?page=1&pageSize=20
|
||||
[API Client] Response: {url: '...', status: 200, data: [...]}
|
||||
[useProjects] Fetch successful: [...]
|
||||
[ProjectsPage] State: {isLoading: false, error: null, projects: [...]}
|
||||
```
|
||||
|
||||
### 检查清单
|
||||
- [ ] 控制台显示正确的 API URL (5167端口)
|
||||
- [ ] 网络请求显示 200 状态码
|
||||
- [ ] 控制台显示成功的响应数据
|
||||
- [ ] 页面显示项目列表或"No projects yet"消息
|
||||
- [ ] 没有错误消息或红色日志
|
||||
|
||||
## 下一步行动
|
||||
|
||||
### 如果问题仍然存在：
|
||||
1. **检查后端日志**: 查看后端控制台输出
|
||||
2. **测试 API 直接访问**: 使用 curl 或 Postman 测试 API
|
||||
3. **检查防火墙**: 确保端口 5167 未被阻止
|
||||
4. **检查端口冲突**: 确认没有其他程序使用 5167 端口
|
||||
|
||||
### 如果问题已解决：
|
||||
1. 移除调试日志（生产环境）
|
||||
2. 添加更好的错误处理
|
||||
3. 考虑添加 API 健康检查端点
|
||||
4. 实施重试逻辑和超时处理
|
||||
|
||||
## 相关文件
|
||||
- `colaflow-web/lib/api/client.ts` - API 客户端配置
|
||||
- `colaflow-web/lib/hooks/use-projects.ts` - Projects 数据 hook
|
||||
- `colaflow-web/app/(dashboard)/projects/page.tsx` - 项目列表页面
|
||||
- `colaflow-web/.env.local` - 环境变量配置
|
||||
|
||||
## Git 提交
|
||||
- Commit: `fix(frontend): Add comprehensive debugging for API connection issues`
|
||||
- Branch: main
|
||||
- Files changed: 3 (client.ts, use-projects.ts, page.tsx)
|
||||
|
||||
---
|
||||
|
||||
**注意**: 这些调试日志在开发环境很有用，但在生产环境应该移除或使用日志级别控制。
|
||||
Reference in New Issue
Block a user