photography/backend/README.md

摄影作品集后端 API

基于 Go + Gin + GORM + PostgreSQL 的摄影作品集后端服务。

🚀 快速开始

环境要求

• Go 1.21+
• PostgreSQL 12+
• Git

启动服务

# 1. 克隆项目（如果需要）
git clone <repository-url>
cd photography/backend

# 2. 安装依赖
go mod tidy

# 3. 配置数据库
# 确保 PostgreSQL 正在运行
# 创建数据库: CREATE DATABASE photography_dev;

# 4. 启动服务
./start.sh
# 或者
go run cmd/server/main_simple.go

服务启动后访问：

• 健康检查: http://localhost:8080/health
• API 根路径: http://localhost:8080/api/v1

📁 项目结构

backend/
├── cmd/server/           # 应用入口
├── internal/
│   ├── config/          # 配置管理
│   ├── database/        # 数据库连接
│   ├── models/          # 数据模型
│   ├── service/         # 业务逻辑
│   ├── handlers/        # HTTP 处理器
│   └── middleware/      # 中间件
├── migrations/          # 数据库迁移文件
├── configs/            # 配置文件
├── uploads/            # 文件上传目录
└── test_api.http       # API 测试文件

🗄️ 数据库架构

核心表

• users: 用户表
• categories: 分类表（支持层级）
• tags: 标签表
• albums: 相册表
• photos: 照片表
• photo_tags: 照片标签关联表
• album_tags: 相册标签关联表

数据库迁移

项目使用 SQL 迁移文件：

1. 001_create_users.sql - 用户表
2. 002_create_photos.sql - 照片表
3. 003_create_albums.sql - 相册表
4. 004_create_categories.sql - 分类表
5. 005_create_tags.sql - 标签表
6. 006_add_foreign_keys.sql - 外键约束

🔌 API 接口

认证接口

• POST /api/v1/auth/register - 用户注册
• POST /api/v1/auth/login - 用户登录
• POST /api/v1/auth/refresh - 刷新令牌

用户管理

• GET /api/v1/users - 获取用户列表
• POST /api/v1/users - 创建用户
• GET /api/v1/users/:id - 获取用户详情
• PUT /api/v1/users/:id - 更新用户
• DELETE /api/v1/users/:id - 删除用户

分类管理

• GET /api/v1/categories - 获取分类列表
• POST /api/v1/categories - 创建分类
• GET /api/v1/categories/:id - 获取分类详情
• PUT /api/v1/categories/:id - 更新分类
• DELETE /api/v1/categories/:id - 删除分类

标签管理

• GET /api/v1/tags - 获取标签列表
• POST /api/v1/tags - 创建标签
• GET /api/v1/tags/:id - 获取标签详情
• PUT /api/v1/tags/:id - 更新标签
• DELETE /api/v1/tags/:id - 删除标签

相册管理

• GET /api/v1/albums - 获取相册列表
• POST /api/v1/albums - 创建相册
• GET /api/v1/albums/:id - 获取相册详情
• PUT /api/v1/albums/:id - 更新相册
• DELETE /api/v1/albums/:id - 删除相册

照片管理

• GET /api/v1/photos - 获取照片列表
• POST /api/v1/photos - 创建照片记录
• GET /api/v1/photos/:id - 获取照片详情
• PUT /api/v1/photos/:id - 更新照片
• DELETE /api/v1/photos/:id - 删除照片

文件上传

• POST /api/v1/upload/photo - 上传照片（需要认证）
• DELETE /api/v1/upload/photo/:id - 删除照片（需要认证）
• GET /api/v1/upload/stats - 获取上传统计（需要管理员权限）

静态文件

• GET /uploads/photos/:filename - 获取照片文件
• GET /uploads/thumbnails/:filename - 获取缩略图

🔧 配置

环境配置文件

• configs/config.yaml - 基础配置
• configs/config.dev.yaml - 开发环境
• configs/config.prod.yaml - 生产环境

环境变量

# 数据库
DB_HOST=localhost
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=password
DB_NAME=photography_dev

# JWT
JWT_SECRET=your-secret-key

# 服务器
PORT=8080

🧪 测试

使用 test_api.http 文件进行 API 测试：

# 1. 健康检查
GET http://localhost:8080/health

# 2. 用户注册
POST http://localhost:8080/api/v1/auth/register
Content-Type: application/json

{
  "username": "testuser",
  "email": "test@example.com",
  "password": "password123",
  "name": "测试用户"
}

📝 功能特性

已实现功能

• ✅ 用户认证和授权
• ✅ 用户管理（CRUD）
• ✅ 分类管理（支持层级）
• ✅ 标签管理（多对多关系）
• ✅ 相册管理
• ✅ 照片管理和上传
• ✅ 文件存储（本地）
• ✅ 数据库自动迁移
• ✅ JWT 认证
• ✅ 权限控制
• ✅ 静态文件服务

计划功能

• 📋 密码加密（bcrypt）
• 📋 完整的 JWT 认证流程
• 📋 图片缩略图生成
• 📋 EXIF 数据提取
• 📋 阿里云 OSS 集成
• 📋 Redis 缓存
• 📋 API 文档（Swagger）
• 📋 单元测试
• 📋 Docker 支持

🔄 部署

开发环境

./start.sh

生产环境

export CONFIG_PATH="configs/config.prod.yaml"
go build -o photography-backend cmd/server/main_simple.go
./photography-backend

📚 依赖

• Gin: HTTP Web 框架
• GORM: ORM 库
• PostgreSQL: 数据库驱动
• JWT: 认证令牌
• Viper: 配置管理
• Zap: 日志库

🤝 贡献

1. Fork 项目
2. 创建功能分支
3. 提交更改
4. 推送到分支
5. 创建 Pull Request

📄 许可证

MIT License