go-svc-code/web/TESTING.md

API 测试指南

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

测试架构

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

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

快速开始

1. 启动服务

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

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

2. 运行测试

方法A: 使用测试页面 (推荐)

在浏览器中打开: http://localhost:3000/test-api.html

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

方法B: 在浏览器控制台中测试

1. 打开浏览器开发者工具 (F12)
2. 在Console标签页中输入:

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

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

方法C: 使用curl命令行测试

# 测试健康检查
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代理配置转发请求：

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

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

独立测试模块 (src/test/api-test-standalone.ts)

纯TypeScript模块，不依赖Vite配置，直接调用后端：

// 在浏览器控制台或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. 查看原始请求:

   // 在浏览器控制台
   fetch('http://localhost:8020/api/health')
   .then(r => r.text())
   .then(console.log);
   

2. 检查网络请求:

3. 打开浏览器开发者工具的Network标签页

4. 查看请求详情和响应

5. 后端日志:

6. 查看后端终端输出

7. 检查日志文件: svc-code/logs/

开发指南

添加新的API测试

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

示例: 添加用户API测试

// 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文档生成
• 实现自动化测试流水线