Files

xujiang af222afc33 feat: 完成前后端API联调测试并修复配置问题

- 启动后端go-zero API服务 (端口8080)
- 修复前端API配置中的端口号 (8888→8080)
- 完善前端API状态监控组件
- 创建categoryService服务层
- 更新前端数据查询和转换逻辑
- 完成完整API集成测试，验证所有接口正常工作
- 验证用户认证、分类管理、照片管理等核心功能
- 创建API集成测试脚本
- 更新任务进度文档

测试结果:
✅ 后端健康检查正常
✅ 用户认证功能正常 (admin/admin123)
✅ 分类API正常 (5个分类)
✅ 照片API正常 (0张照片，数据库为空)
✅ 前后端API连接完全正常

下一步: 实现照片展示页面和搜索过滤功能

2025-07-11 11:42:14 +08:00

4.4 KiB

Raw Blame History

Frontend API Integration Guide

此文档说明如何将前端展示网站连接到后端 go-zero API。

🚀 快速开始

1. 环境配置

确保 .env.local 文件配置正确：

# 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 服务：

# 进入后端目录
cd ../backend

# 启动后端服务 (端口 8888)
make dev
# 或者
go run cmd/api/main.go -f etc/photographyapi-api.yaml

确保后端服务在 http://localhost:8888 运行正常。

3. 启动前端服务

在新的终端窗口中启动前端：

# 进入前端目录
cd frontend

# 安装依赖 (首次运行)
bun install

# 启动开发服务器
bun run dev

前端将在 http://localhost:3000 启动。

🔄 API 模式切换

开发环境切换

在开发环境中，你可以通过右下角的 API 状态指示器来切换 API 模式：

后端API: 连接到真实的 go-zero 后端服务 (localhost:8888)
Mock API: 使用本地模拟数据 (localhost:3001)

手动切换

使用真实 API:

# 在 .env.local 中设置
NEXT_PUBLIC_USE_REAL_API=true

使用 Mock API:

# 在 .env.local 中设置
NEXT_PUBLIC_USE_REAL_API=false

修改后需要重启前端开发服务器。

📊 数据格式转换

后端 API 数据格式

后端 go-zero API 返回的数据格式：

{
  "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
  }
}

前端显示格式

前端自动转换为统一的显示格式：

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
  }
}

🛠️ 故障排查

常见问题

无法连接到后端 API
- 确保后端服务在 localhost:8888 运行
- 检查防火墙设置
- 查看浏览器控制台错误信息
照片无法显示
- 确保后端上传了照片文件
- 检查照片文件路径是否正确
- 确认静态文件服务正常
分类显示错误
- 检查后端是否有分类数据
- 确认分类 ID 关联正确

调试技巧

查看 API 状态
- 开发环境右下角有 API 状态指示器
- 绿色表示连接正常，红色表示连接失败
查看网络请求
- 打开浏览器开发者工具
- 切换到 Network 标签
- 查看 API 请求和响应
切换到 Mock API
- 如果后端有问题，可以临时切换到 Mock API 继续开发
- 修改 NEXT_PUBLIC_USE_REAL_API=false

📈 性能优化

缓存策略

照片列表缓存 5 分钟
分类列表缓存 10 分钟
单张照片数据根据需要缓存

图片优化

使用后端提供的缩略图 (thumbnail_path)
懒加载大图
支持多种图片格式

🔒 安全考虑

API 认证

目前前端支持 JWT 认证：

Token 存储在 localStorage
自动在请求头添加 Authorization
Token 过期自动跳转登录页

跨域配置

后端需要配置 CORS 允许前端域名访问。

📚 相关文档

🎯 下一步计划

完善照片元数据: 添加 EXIF 信息显示
标签系统: 实现照片标签功能
高级搜索: 支持按分类、标签、日期搜索
用户系统: 添加用户认证和权限管理
性能优化: 图片懒加载、虚拟滚动等

此文档随项目更新，如有问题请查看具体模块的 CLAUDE.md 文件

4.4 KiB Raw Blame History