# API 测试指南

本文档介绍如何测试 svc-code 项目的后端API接口。

## 测试架构

项目采用 **双路径调用架构**：

1. **业务API路径** (`src/api/`): 供Vue页面使用，通过Vite代理
2. **测试API路径** (`src/test/`): 独立测试使用，直接调用后端

## 快速开始

### 1. 启动服务

```bash
# 启动后端服务 (端口8020)
cd svc-code && go run main.go

# 启动前端开发服务器 (端口3000) - 可选
cd svc-code/web && npm run dev
```

### 2. 运行测试

#### 方法A: 使用测试页面 (推荐)
在浏览器中打开: [http://localhost:3000/test-api.html](http://localhost:3000/test-api.html)

或直接打开文件: `svc-code/web/public/test-api.html`

#### 方法B: 在浏览器控制台中测试
1. 打开浏览器开发者工具 (F12)
2. 在Console标签页中输入:

```javascript
// 加载测试模块
import('./src/test/api-test-standalone.js').then(module => {
  module.runAllTests();
});

// 或者使用全局对象（如果页面已加载）
testAPI.runAllTests();
```

#### 方法C: 使用curl命令行测试
```bash
# 测试健康检查
curl http://localhost:8020/api/health

# 测试项目列表
curl http://localhost:8020/api/projects
```

## 测试用例

### 1. 健康检查 API
- **端点**: `GET /api/health`
- **预期响应**: `{ "success": true, "data": { "healthy": true, "version": "1.0" } }`
- **测试命令**: `testAPI.testHealth()`

### 2. 项目列表 API
- **端点**: `GET /api/projects`
- **预期响应**: `{ "success": true, "data": [ ... ] }` (包含3个模拟项目)
- **测试命令**: `testAPI.testProjects()`

## 测试模块说明

### 业务API模块 (`src/api/`)
供Vue组件使用，通过Vite代理配置转发请求：

```typescript
// 页面中使用
import { getProjects } from '@/api/project';

// 实际调用路径: /projects → 代理到 http://localhost:8020/api/projects
const projects = await getProjects();
```

### 独立测试模块 (`src/test/api-test-standalone.ts`)
纯TypeScript模块，不依赖Vite配置，直接调用后端：

```typescript
// 在浏览器控制台或Node.js中使用
import { testApi } from './src/test/api-test-standalone.js';

// 直接调用后端API
const projects = await testApi.getProjects();
```

主要功能：
- `runAllTests()` - 运行所有测试
- `testGetProjects()` - 测试项目列表API
- `testHealthCheck()` - 测试健康检查API
- `testBackendConnection()` - 测试后端连接
- `testApi` - 直接API调用对象

## 故障排除

### 常见问题

#### 1. 连接失败
```
错误: NetworkError 或 Failed to fetch
```
**解决方案**:
- 检查后端服务是否运行: `lsof -i :8020`
- 检查网络连接
- 检查跨域设置

#### 2. 404错误
```
错误: HTTP 404
```
**解决方案**:
- 确认API端点正确: `/api/health`, `/api/projects`
- 检查Vite代理配置 (`vite.config.ts`)

#### 3. 跨域问题 (CORS)
```
错误: Access-Control-Allow-Origin
```
**解决方案**:
- 后端需要配置CORS头
- 使用Vite代理避免跨域

#### 4. 响应格式错误
```
错误: 无法解析JSON 或 success字段不正确
```
**解决方案**:
- 检查后端返回格式是否符合预期
- 查看原始响应: `curl -v http://localhost:8020/api/health`

### 调试技巧

1. **查看原始请求**:
```javascript
// 在浏览器控制台
fetch('http://localhost:8020/api/health')
  .then(r => r.text())
  .then(console.log);
```

2. **检查网络请求**:
- 打开浏览器开发者工具的Network标签页
- 查看请求详情和响应

3. **后端日志**:
- 查看后端终端输出
- 检查日志文件: `svc-code/logs/`

## 开发指南

### 添加新的API测试

1. 在 `src/api/` 添加业务API模块
2. 在 `src/test/api-test-standalone.ts` 添加对应的测试函数
3. 更新测试页面 (`public/test-api.html`) 添加测试按钮

### 示例: 添加用户API测试

```typescript
// src/api/user.ts - 业务API
export const getUsers = () => request.get('/users');

// src/test/api-test-standalone.ts - 测试API
export const testGetUsers = async () => {
  return testApi.get('/users');
};
```

## 相关文件

- `src/api/project.ts` - 项目API业务模块
- `src/api/health.ts` - 健康检查API业务模块
- `src/test/api-test-standalone.ts` - 独立测试模块
- `public/test-api.html` - 测试页面
- `vite.config.ts` - Vite代理配置

## 下一步

- [ ] 添加更多的API测试用例
- [ ] 集成单元测试框架 (Vitest/Jest)
- [ ] 添加API文档生成
- [ ] 实现自动化测试流水线