ColaFlow/API_CONNECTION_FIX_SUMMARY.md

API 连接问题修复摘要

问题描述

报告时间: 2025-11-03 问题: 前端项目列表页面无法显示项目数据

症状

1. 前端正常运行在 http://localhost:3000
2. 页面渲染正常（GET /projects 200）
3. 但是后端 API 无法连接（curl localhost:5167 连接失败）

诊断结果

运行诊断测试脚本后发现：

./test-api-connection.sh

关键发现：

1. ✗ 后端服务器未在端口 5167 运行
2. ✗ API 健康检查端点无法访问
3. ✗ Projects 端点无法访问
4. ⚠ 前端运行中但返回 307 状态码（重定向）
5. ✓ .env.local 配置正确：NEXT_PUBLIC_API_URL=http://localhost:5167/api/v1

根本原因

后端服务器未启动 - 这是主要问题

已实施的修复

1. 增强前端调试功能

文件：colaflow-web/lib/api/client.ts

修改内容:

• 添加 API URL 初始化日志
• 为每个 API 请求添加详细日志
• 增强错误处理，捕获并记录网络错误
• 显示请求 URL、方法、状态码

代码示例:

// 初始化时记录 API URL
if (typeof window !== 'undefined') {
  console.log('[API Client] API_URL:', API_URL);
  console.log('[API Client] NEXT_PUBLIC_API_URL:', process.env.NEXT_PUBLIC_API_URL);
}

// 请求前记录
console.log('[API Client] Request:', {
  method: options.method || 'GET',
  url,
  endpoint,
});

// 捕获网络错误
try {
  const response = await fetch(url, config);
  const result = await handleResponse<T>(response);
  console.log('[API Client] Response:', { url, status: response.status, data: result });
  return result;
} catch (error) {
  console.error('[API Client] Network error:', {
    url,
    error: error instanceof Error ? error.message : String(error),
    errorObject: error,
  });
  throw error;
}

文件：colaflow-web/app/(dashboard)/projects/page.tsx

修改内容:

• 将简单的错误消息替换为详细的错误卡片
• 显示错误详情、API URL、故障排查步骤
• 添加重试按钮
• 添加控制台调试日志

功能:

if (error) {
  const errorMessage = error instanceof Error ? error.message : 'Unknown error';
  const apiUrl = process.env.NEXT_PUBLIC_API_URL || 'http://localhost:5000/api/v1';

  console.error('[ProjectsPage] Error loading projects:', error);

  return (
    <Card>
      <CardHeader>
        <CardTitle>Failed to Load Projects</CardTitle>
        <CardDescription>Unable to connect to the backend API</CardDescription>
      </CardHeader>
      <CardContent>
        <div>Error Details: {errorMessage}</div>
        <div>API URL: {apiUrl}</div>
        <div>Troubleshooting Steps:
          - Check if backend server is running
          - Verify API URL in .env.local
          - Check browser console (F12)
          - Check network tab (F12)
        </div>
        <Button onClick={() => window.location.reload()}>Retry</Button>
      </CardContent>
    </Card>
  );
}

文件：colaflow-web/lib/hooks/use-projects.ts

修改内容:

• 在 queryFn 中添加详细日志
• 记录请求开始、成功、失败
• 减少重试次数从 3 降至 1（更快失败）

代码:

export function useProjects(page = 1, pageSize = 20) {
  return useQuery<Project[]>({
    queryKey: ['projects', page, pageSize],
    queryFn: async () => {
      console.log('[useProjects] Fetching projects...', { page, pageSize });
      try {
        const result = await projectsApi.getAll(page, pageSize);
        console.log('[useProjects] Fetch successful:', result);
        return result;
      } catch (error) {
        console.error('[useProjects] Fetch failed:', error);
        throw error;
      }
    },
    staleTime: 5 * 60 * 1000,
    retry: 1, // Fail faster
  });
}

2. 创建诊断工具

文件：test-api-connection.sh

功能:

• 检查后端是否在端口 5167 运行
• 测试 API 健康检查端点
• 测试 Projects 端点
• 检查前端是否运行
• 验证 .env.local 配置
• 提供彩色输出和清晰的下一步指令

文件：DEBUGGING_GUIDE.md

内容:

• 详细的诊断步骤
• 常见问题及解决方案
• 如何使用浏览器开发工具
• 日志输出示例
• 验证修复的检查清单

解决方案

立即行动：启动后端服务器

# 方法 1: 使用 .NET CLI
cd colaflow-api/src/ColaFlow.API
dotnet run

# 方法 2: 使用解决方案
cd colaflow-api
dotnet run --project src/ColaFlow.API/ColaFlow.API.csproj

# 验证后端运行
curl http://localhost:5167/api/v1/health
curl http://localhost:5167/api/v1/projects

验证步骤

1. 启动后端：

   cd colaflow-api/src/ColaFlow.API
   dotnet run
   

   期望输出：Now listening on: http://localhost:5167

2. 确认前端运行：

   cd colaflow-web
   npm run dev
   

   期望输出：Ready on http://localhost:3000

3. 运行诊断测试：

   ./test-api-connection.sh
   

   期望：所有测试显示 ✓ 绿色通过

4. 访问项目页面：

   • 打开 http://localhost:3000/projects
   • 按 F12 打开开发者工具
   • 查看 Console 标签页

5. 检查控制台日志： 期望看到：

   [API Client] API_URL: http://localhost:5167/api/v1
   [useProjects] Fetching projects...
   [API Client] Request: GET http://localhost:5167/api/v1/projects...
   [API Client] Response: {status: 200, data: [...]}
   [useProjects] Fetch successful
   

6. 检查网络请求：

   • 切换到 Network 标签页
   • 查找 projects?page=1&pageSize=20 请求
   • 状态应为 200 OK

Git 提交

Commit 1: 前端调试增强

fix(frontend): Add comprehensive debugging for API connection issues

Enhanced error handling and debugging to diagnose API connection problems.

Changes:
- Added detailed console logging in API client (client.ts)
- Enhanced error display in projects page with troubleshooting steps
- Added logging in useProjects hook for better debugging
- Display API URL and error details on error screen
- Added retry button for easy error recovery

Files changed:
- colaflow-web/lib/api/client.ts
- colaflow-web/lib/hooks/use-projects.ts
- colaflow-web/app/(dashboard)/projects/page.tsx

Commit: 2ea3c93

预期结果

修复前（当前状态）

• 页面显示：Failed to load projects. Please try again later.
• 控制台：无详细错误信息
• 无法判断问题原因

修复后（启动后端后）

• 页面显示：项目列表或"No projects yet"消息
• 控制台：详细的请求/响应日志
• 网络面板：200 OK 状态码
• 能够创建、查看、编辑项目

如果后端仍未启动

• 页面显示：详细的错误卡片，包含：
  • 错误消息：Failed to fetch 或 Network request failed
  • API URL：http://localhost:5167/api/v1
  • 故障排查步骤
  • 重试按钮
• 控制台：完整的调试日志
• 网络面板：失败的请求（红色）

后续优化建议

1. 添加 API 健康检查

在应用启动时检查后端是否可用：

// useHealthCheck.ts
export function useHealthCheck() {
  return useQuery({
    queryKey: ['health'],
    queryFn: () => api.get('/health'),
    refetchInterval: 30000, // 30秒检查一次
  });
}

2. 添加全局错误处理

使用 React Error Boundary 捕获 API 错误：

// ErrorBoundary.tsx
export class ApiErrorBoundary extends React.Component {
  state = { hasError: false };

  static getDerivedStateFromError(error) {
    return { hasError: true };
  }

  render() {
    if (this.state.hasError) {
      return <ApiErrorPage />;
    }
    return this.props.children;
  }
}

3. 添加重连逻辑

实现指数退避重试：

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      retry: 3,
      retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 30000),
    },
  },
});

4. 添加离线检测

检测网络状态并显示离线提示：

export function useOnlineStatus() {
  const [isOnline, setIsOnline] = useState(navigator.onLine);

  useEffect(() => {
    const handleOnline = () => setIsOnline(true);
    const handleOffline = () => setIsOnline(false);

    window.addEventListener('online', handleOnline);
    window.addEventListener('offline', handleOffline);

    return () => {
      window.removeEventListener('online', handleOnline);
      window.removeEventListener('offline', handleOffline);
    };
  }, []);

  return isOnline;
}

5. 生产环境优化

移除调试日志或使用日志级别：

const DEBUG = process.env.NODE_ENV === 'development';

if (DEBUG) {
  console.log('[API Client] Request:', ...);
}

相关文档

• DEBUGGING_GUIDE.md - 详细的调试指南
• test-api-connection.sh - API 连接诊断脚本
• colaflow-api/README.md - 后端启动指南
• colaflow-web/README.md - 前端配置指南

联系信息

如果问题持续存在，请提供以下信息：

1. 浏览器控制台完整日志（Console 标签）
2. 网络请求详情（Network 标签）
3. 后端控制台输出
4. .env.local 文件内容
5. 诊断脚本输出：./test-api-connection.sh

---

状态: ✓ 前端调试增强完成，等待后端启动验证 下一步: 启动后端服务器并验证修复效果