245 lines
5.2 KiB
Markdown
245 lines
5.2 KiB
Markdown
# 摄影作品集后端 API
|
||
|
||
基于 Go + Gin + GORM + PostgreSQL 的摄影作品集后端服务。
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 环境要求
|
||
|
||
- Go 1.21+
|
||
- PostgreSQL 12+
|
||
- Git
|
||
|
||
### 启动服务
|
||
|
||
```bash
|
||
# 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` - 生产环境
|
||
|
||
### 环境变量
|
||
|
||
```bash
|
||
# 数据库
|
||
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 测试：
|
||
|
||
```bash
|
||
# 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 支持
|
||
|
||
## 🔄 部署
|
||
|
||
### 开发环境
|
||
|
||
```bash
|
||
./start.sh
|
||
```
|
||
|
||
### 生产环境
|
||
|
||
```bash
|
||
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 |