af222afc33
- 启动后端go-zero API服务 (端口8080) - 修复前端API配置中的端口号 (8888→8080) - 完善前端API状态监控组件 - 创建categoryService服务层 - 更新前端数据查询和转换逻辑 - 完成完整API集成测试，验证所有接口正常工作 - 验证用户认证、分类管理、照片管理等核心功能 - 创建API集成测试脚本 - 更新任务进度文档 测试结果: ✅ 后端健康检查正常 ✅ 用户认证功能正常 (admin/admin123) ✅ 分类API正常 (5个分类) ✅ 照片API正常 (0张照片，数据库为空) ✅ 前后端API连接完全正常 下一步: 实现照片展示页面和搜索过滤功能
213 lines
4.4 KiB
Markdown
213 lines
4.4 KiB
Markdown
# 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 文件* |