feat: 完成前后端API联调测试并修复配置问题
- 启动后端go-zero API服务 (端口8080) - 修复前端API配置中的端口号 (8888→8080) - 完善前端API状态监控组件 - 创建categoryService服务层 - 更新前端数据查询和转换逻辑 - 完成完整API集成测试，验证所有接口正常工作 - 验证用户认证、分类管理、照片管理等核心功能 - 创建API集成测试脚本 - 更新任务进度文档 测试结果: ✅ 后端健康检查正常 ✅ 用户认证功能正常 (admin/admin123) ✅ 分类API正常 (5个分类) ✅ 照片API正常 (0张照片，数据库为空) ✅ 前后端API连接完全正常 下一步: 实现照片展示页面和搜索过滤功能
This commit is contained in:
xujiang
213
frontend/API_INTEGRATION.md
Normal file
213
frontend/API_INTEGRATION.md
Normal file
@ -0,0 +1,213 @@
|
||||
# Frontend API Integration Guide
|
||||
|
||||
此文档说明如何将前端展示网站连接到后端 go-zero API。
|
||||
|
||||
## 🚀 快速开始
|
||||
|
||||
### 1. 环境配置
|
||||
|
||||
确保 `.env.local` 文件配置正确：
|
||||
|
||||
```bash
|
||||
# API配置 - 连接到后端 go-zero API
|
||||
NEXT_PUBLIC_API_URL=http://localhost:8888/api/v1
|
||||
|
||||
# Mock API (仅开发时使用)
|
||||
NEXT_PUBLIC_MOCK_API_URL=http://localhost:3001/api
|
||||
|
||||
# 开发环境配置
|
||||
NODE_ENV=development
|
||||
|
||||
# 启用真实API
|
||||
NEXT_PUBLIC_USE_REAL_API=true
|
||||
```
|
||||
|
||||
### 2. 启动后端服务
|
||||
|
||||
首先启动后端 go-zero API 服务：
|
||||
|
||||
```bash
|
||||
# 进入后端目录
|
||||
cd ../backend
|
||||
|
||||
# 启动后端服务 (端口 8888)
|
||||
make dev
|
||||
# 或者
|
||||
go run cmd/api/main.go -f etc/photographyapi-api.yaml
|
||||
```
|
||||
|
||||
确保后端服务在 `http://localhost:8888` 运行正常。
|
||||
|
||||
### 3. 启动前端服务
|
||||
|
||||
在新的终端窗口中启动前端：
|
||||
|
||||
```bash
|
||||
# 进入前端目录
|
||||
cd frontend
|
||||
|
||||
# 安装依赖 (首次运行)
|
||||
bun install
|
||||
|
||||
# 启动开发服务器
|
||||
bun run dev
|
||||
```
|
||||
|
||||
前端将在 `http://localhost:3000` 启动。
|
||||
|
||||
## 🔄 API 模式切换
|
||||
|
||||
### 开发环境切换
|
||||
|
||||
在开发环境中，你可以通过右下角的 API 状态指示器来切换 API 模式：
|
||||
|
||||
- **后端API**: 连接到真实的 go-zero 后端服务 (localhost:8888)
|
||||
- **Mock API**: 使用本地模拟数据 (localhost:3001)
|
||||
|
||||
### 手动切换
|
||||
|
||||
1. **使用真实 API**:
|
||||
```bash
|
||||
# 在 .env.local 中设置
|
||||
NEXT_PUBLIC_USE_REAL_API=true
|
||||
```
|
||||
|
||||
2. **使用 Mock API**:
|
||||
```bash
|
||||
# 在 .env.local 中设置
|
||||
NEXT_PUBLIC_USE_REAL_API=false
|
||||
```
|
||||
|
||||
修改后需要重启前端开发服务器。
|
||||
|
||||
## 📊 数据格式转换
|
||||
|
||||
### 后端 API 数据格式
|
||||
|
||||
后端 go-zero API 返回的数据格式：
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"photos": [
|
||||
{
|
||||
"id": 1,
|
||||
"title": "照片标题",
|
||||
"description": "照片描述",
|
||||
"file_path": "/uploads/photos/xxx.jpg",
|
||||
"thumbnail_path": "/uploads/photos/thumb_xxx.jpg",
|
||||
"user_id": 1,
|
||||
"category_id": 1,
|
||||
"created_at": 1641024000,
|
||||
"updated_at": 1641024000
|
||||
}
|
||||
],
|
||||
"total": 1,
|
||||
"page": 1,
|
||||
"size": 10
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 前端显示格式
|
||||
|
||||
前端自动转换为统一的显示格式：
|
||||
|
||||
```typescript
|
||||
interface Photo {
|
||||
id: number
|
||||
title: string
|
||||
description: string
|
||||
src: string // 转换自 file_path
|
||||
category: string // 通过 category_id 查找分类名称
|
||||
tags: string[] // 暂时为空数组
|
||||
date: string // 转换自 created_at 时间戳
|
||||
exif: { // 暂时使用默认值
|
||||
camera: string
|
||||
lens: string
|
||||
settings: string
|
||||
location: string
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 🛠️ 故障排查
|
||||
|
||||
### 常见问题
|
||||
|
||||
1. **无法连接到后端 API**
|
||||
- 确保后端服务在 `localhost:8888` 运行
|
||||
- 检查防火墙设置
|
||||
- 查看浏览器控制台错误信息
|
||||
|
||||
2. **照片无法显示**
|
||||
- 确保后端上传了照片文件
|
||||
- 检查照片文件路径是否正确
|
||||
- 确认静态文件服务正常
|
||||
|
||||
3. **分类显示错误**
|
||||
- 检查后端是否有分类数据
|
||||
- 确认分类 ID 关联正确
|
||||
|
||||
### 调试技巧
|
||||
|
||||
1. **查看 API 状态**
|
||||
- 开发环境右下角有 API 状态指示器
|
||||
- 绿色表示连接正常，红色表示连接失败
|
||||
|
||||
2. **查看网络请求**
|
||||
- 打开浏览器开发者工具
|
||||
- 切换到 Network 标签
|
||||
- 查看 API 请求和响应
|
||||
|
||||
3. **切换到 Mock API**
|
||||
- 如果后端有问题，可以临时切换到 Mock API 继续开发
|
||||
- 修改 `NEXT_PUBLIC_USE_REAL_API=false`
|
||||
|
||||
## 📈 性能优化
|
||||
|
||||
### 缓存策略
|
||||
|
||||
- 照片列表缓存 5 分钟
|
||||
- 分类列表缓存 10 分钟
|
||||
- 单张照片数据根据需要缓存
|
||||
|
||||
### 图片优化
|
||||
|
||||
- 使用后端提供的缩略图 (thumbnail_path)
|
||||
- 懒加载大图
|
||||
- 支持多种图片格式
|
||||
|
||||
## 🔒 安全考虑
|
||||
|
||||
### API 认证
|
||||
|
||||
目前前端支持 JWT 认证：
|
||||
|
||||
- Token 存储在 localStorage
|
||||
- 自动在请求头添加 Authorization
|
||||
- Token 过期自动跳转登录页
|
||||
|
||||
### 跨域配置
|
||||
|
||||
后端需要配置 CORS 允许前端域名访问。
|
||||
|
||||
## 📚 相关文档
|
||||
|
||||
- [后端 API 文档](../backend/CLAUDE.md)
|
||||
- [前端开发文档](./CLAUDE.md)
|
||||
- [部署文档](../docs/deployment/CLAUDE.md)
|
||||
|
||||
## 🎯 下一步计划
|
||||
|
||||
1. **完善照片元数据**: 添加 EXIF 信息显示
|
||||
2. **标签系统**: 实现照片标签功能
|
||||
3. **高级搜索**: 支持按分类、标签、日期搜索
|
||||
4. **用户系统**: 添加用户认证和权限管理
|
||||
5. **性能优化**: 图片懒加载、虚拟滚动等
|
||||
|
||||
---
|
||||
|
||||
*此文档随项目更新，如有问题请查看具体模块的 CLAUDE.md 文件*
|
||||
Reference in New Issue
Block a user