84e778e033
- 创建完整的迁移框架 (pkg/migration/) - 版本管理系统，时间戳版本号 (YYYYMMDD_HHMMSS) - 事务安全的上下迁移机制 (Up/Down) - 迁移状态跟踪和记录 (migration_records 表) - 命令行迁移工具 (cmd/migrate/main.go) - 生产环境迁移脚本 (scripts/production-migrate.sh) - 生产环境初始化脚本 (scripts/init-production-db.sh) - 迁移测试脚本 (scripts/test-migration.sh) - Makefile 集成 (migrate-up, migrate-down, migrate-status) - 5个预定义迁移 (基础表、默认数据、元数据、收藏、用户资料) - 自动备份机制、预览模式、详细日志 - 完整文档 (docs/DATABASE_MIGRATION.md) 任务13完成，项目完成率达到42.5%
245 lines
11 KiB
Markdown
245 lines
11 KiB
Markdown
# Backend API Service - CLAUDE.md
|
||
|
||
本文件为 Claude Code 在后端 API 服务模块中工作时提供指导。
|
||
|
||
## 🎯 模块概览
|
||
|
||
这是一个基于 Go + go-zero 框架的 REST API 后端服务，利用 go-zero 生态工具快速开发，采用 go-zero 推荐的项目架构。
|
||
|
||
### 主要特性
|
||
- 🏗️ go-zero 标准架构 (API → Logic → Model)
|
||
- 🚀 代码自动生成 (通过 .api 文件和 goctl 工具)
|
||
- 📊 多数据库支持 (PostgreSQL/SQLite 通过配置切换 + Redis)
|
||
- 🔐 JWT 认证 + 中间件系统
|
||
- 📁 文件上传和存储管理
|
||
- 🔗 链路追踪和监控
|
||
- 🛡️ 熔断、限流、负载均衡
|
||
- 📚 API 文档自动生成
|
||
|
||
### 技术栈
|
||
- **语言**: Go 1.23+
|
||
- **框架**: go-zero v1.8.0+
|
||
- **数据库**: PostgreSQL/SQLite (通过配置切换) + Redis (缓存)
|
||
- **ORM**: GORM v1.30.0 (统一数据访问)
|
||
- **认证**: JWT (内置 JWT 支持)
|
||
- **日志**: go-zero 内置日志系统
|
||
- **配置**: go-zero 配置系统
|
||
- **工具**: goctl (代码生成工具)
|
||
- **容器化**: Docker + Docker Compose
|
||
|
||
## 📁 go-zero 项目结构 (标准版)
|
||
```
|
||
backend/
|
||
├── CLAUDE.md # 📋 当前文件 - 后端总览
|
||
├── go.mod # Go 模块文件
|
||
├── go.sum # 依赖锁定文件
|
||
├── Makefile # 构建脚本
|
||
├── cmd/ # 🚀 应用入口目录
|
||
│ ├── api/ # API 服务入口
|
||
│ │ └── main.go # API 服务主函数
|
||
│ ├── rpc/ # RPC 服务入口 (未来扩展)
|
||
│ │ └── main.go # RPC 服务主函数
|
||
│ └── job/ # 任务服务入口 (未来扩展)
|
||
│ └── main.go # 任务服务主函数
|
||
├── api/ # 🌐 API 定义目录
|
||
│ ├── CLAUDE.md # API 模块开发指导
|
||
│ └── desc/ # 📝 API 定义文件目录
|
||
│ ├── photography.api # 📋 主 API 文件 (导入其他模块)
|
||
│ ├── user.api # 用户接口定义
|
||
│ ├── photo.api # 照片接口定义
|
||
│ ├── category.api # 分类接口定义
|
||
│ ├── auth.api # 认证接口定义
|
||
│ └── common.api # 公共类型定义
|
||
├── etc/ # ⚙️ 配置文件目录
|
||
│ ├── photographyapi-api.yaml # API 服务配置
|
||
│ ├── photography-dev.yaml # 开发环境配置
|
||
│ ├── photography-prod.yaml # 生产环境配置
|
||
│ ├── photographyrpc.yaml # RPC 服务配置 (未来)
|
||
│ └── photographyjob.yaml # 任务服务配置 (未来)
|
||
├── internal/ # 📦 内部模块 (goctl 自动生成)
|
||
│ ├── config/ # 配置结构
|
||
│ │ └── config.go # 配置定义
|
||
│ ├── handler/ # 🎯 处理器 (goctl 自动生成)
|
||
│ ├── logic/ # 🧠 业务逻辑 (goctl 自动生成)
|
||
│ ├── svc/ # 🔧 服务上下文
|
||
│ │ └── servicecontext.go # 服务上下文定义
|
||
│ ├── types/ # 📦 类型定义 (goctl 自动生成)
|
||
│ │ └── types.go # 请求/响应类型
|
||
│ ├── middleware/ # 🛡️ 中间件
|
||
│ │ ├── auth.go # 认证中间件
|
||
│ │ ├── cors.go # CORS 中间件
|
||
│ │ └── logger.go # 日志中间件
|
||
│ └── model/ # 📊 数据模型模块 (内部)
|
||
│ ├── CLAUDE.md # 数据模型开发指导
|
||
│ ├── sql/ # SQL 定义文件
|
||
│ │ ├── user.sql # 用户表结构
|
||
│ │ ├── photo.sql # 照片表结构
|
||
│ │ └── category.sql # 分类表结构
|
||
│ ├── user.go # 用户模型 (goctl 自动生成)
|
||
│ ├── photo.go # 照片模型 (goctl 自动生成)
|
||
│ ├── category.go # 分类模型 (goctl 自动生成)
|
||
│ └── vars.go # 模型变量定义
|
||
├── pkg/ # 📦 可导出包 (业务解耦)
|
||
│ ├── CLAUDE.md # 公共包开发指导
|
||
│ ├── errorx/ # 错误处理包
|
||
│ │ └── errorx.go # 统一错误定义
|
||
│ ├── response/ # 响应处理包
|
||
│ │ └── response.go # 统一响应格式
|
||
│ ├── utils/ # 通用工具包
|
||
│ │ ├── jwt/ # JWT 工具
|
||
│ │ │ └── jwt.go # JWT 实现
|
||
│ │ ├── hash/ # 哈希工具
|
||
│ │ │ └── hash.go # 哈希实现
|
||
│ │ ├── file/ # 文件处理工具
|
||
│ │ │ └── file.go # 文件处理实现
|
||
│ │ └── database/ # 数据库工具
|
||
│ │ └── database.go # 数据库连接工厂
|
||
│ └── constants/ # 常量定义包
|
||
│ └── constants.go # 全局常量定义
|
||
├── configs/ # 📋 静态配置文件目录
|
||
│ ├── sql/ # SQL 初始化文件
|
||
│ │ ├── init.sql # 数据库初始化
|
||
│ │ └── seed.sql # 种子数据
|
||
│ └── docker/ # Docker 相关配置
|
||
│ ├── Dockerfile # Docker 镜像定义
|
||
│ ├── docker-compose.yml # 本地开发环境
|
||
│ └── docker-compose.prod.yml # 生产环境配置
|
||
├── scripts/ # 🛠️ 脚本目录
|
||
│ ├── build.sh # 构建脚本
|
||
│ ├── deploy.sh # 部署脚本
|
||
│ └── gen-code.sh # 代码生成脚本
|
||
├── deploy/ # 🚀 部署配置
|
||
│ ├── k8s/ # Kubernetes 配置
|
||
│ └── systemd/ # Systemd 配置
|
||
└── tests/ # 🧪 测试模块 (简化)
|
||
├── CLAUDE.md # 测试开发指导
|
||
├── api_test.go # API 集成测试
|
||
└── benchmark_test.go # 性能测试
|
||
```
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 环境准备
|
||
```bash
|
||
# 1. 安装 Go 1.23+
|
||
go version
|
||
|
||
# 2. 安装 goctl 工具
|
||
go install github.com/zeromicro/go-zero/tools/goctl@latest
|
||
|
||
# 3. 验证安装
|
||
goctl --version
|
||
```
|
||
|
||
### 项目初始化
|
||
```bash
|
||
# 1. 创建项目目录
|
||
mkdir photography-backend && cd photography-backend
|
||
|
||
# 2. 初始化 Go 模块
|
||
go mod init photography-backend
|
||
|
||
# 3. 创建 API 定义文件
|
||
mkdir -p api/desc
|
||
```
|
||
|
||
### 快速开发流程
|
||
```bash
|
||
# 1. 定义 API 接口 (api/desc/photography.api)
|
||
# 2. 生成 API 服务代码
|
||
goctl api go -api api/desc/photography.api -dir ./
|
||
|
||
# 3. 定义数据库表结构 (internal/model/sql/*.sql)
|
||
# 4. 生成数据模型代码
|
||
goctl model mysql ddl -src internal/model/sql/user.sql -dir internal/model/
|
||
|
||
# 5. 启动开发服务器
|
||
go run cmd/api/main.go -f etc/photographyapi-api.yaml
|
||
```
|
||
|
||
### 多模块扩展
|
||
当项目需要拆分为多个服务时，可以在 cmd 目录下添加不同的服务入口：
|
||
|
||
```bash
|
||
# API 服务 (HTTP 接口)
|
||
go run cmd/api/main.go -f etc/photographyapi-api.yaml
|
||
|
||
# RPC 服务 (内部调用)
|
||
go run cmd/rpc/main.go -f etc/photographyrpc.yaml
|
||
|
||
# 任务服务 (定时任务/队列处理)
|
||
go run cmd/job/main.go -f etc/photographyjob.yaml
|
||
```
|
||
|
||
### 服务职责划分
|
||
- **API 服务**: 对外提供 HTTP 接口，处理用户请求
|
||
- **RPC 服务**: 内部服务间通信，提供核心业务逻辑
|
||
- **任务服务**: 异步任务处理，如图片处理、邮件发送等
|
||
|
||
### 开发模式
|
||
- **快速开发**: 使用 SQLite 进行本地开发，无需额外数据库
|
||
- **生产模式**: 使用 PostgreSQL + Redis，完整的生产环境配置
|
||
- **测试模式**: 使用内存数据库，用于单元测试和集成测试
|
||
|
||
## 🗄️ 数据库迁移系统
|
||
|
||
### 迁移系统架构
|
||
|
||
项目采用自定义的数据库迁移系统，提供完整的版本控制和回滚机制：
|
||
|
||
```
|
||
pkg/migration/
|
||
├── migration.go # 迁移管理器核心逻辑
|
||
├── migrations.go # 所有迁移定义
|
||
└── README.md # 迁移开发指南
|
||
|
||
cmd/migrate/
|
||
└── main.go # 命令行迁移工具
|
||
|
||
scripts/
|
||
├── production-migrate.sh # 生产环境迁移脚本
|
||
└── init-production-db.sh # 生产环境初始化脚本
|
||
|
||
docs/
|
||
└── DATABASE_MIGRATION.md # 完整迁移文档
|
||
```
|
||
|
||
### 快速迁移命令
|
||
|
||
```bash
|
||
# 开发环境
|
||
make migrate-status # 查看迁移状态
|
||
make migrate-up # 运行所有迁移
|
||
make migrate-down STEPS=1 # 回滚1步迁移
|
||
make migrate-create NAME=xxx # 创建新迁移
|
||
make db-backup # 创建备份
|
||
make db-restore BACKUP=file # 恢复备份
|
||
|
||
# 生产环境
|
||
./scripts/production-migrate.sh status # 查看状态
|
||
./scripts/production-migrate.sh migrate # 执行迁移
|
||
./scripts/production-migrate.sh -d migrate # 预览模式
|
||
./scripts/init-production-db.sh # 全新初始化
|
||
```
|
||
|
||
### 迁移开发流程
|
||
|
||
1. **创建迁移**: `make migrate-create NAME="add_user_field"`
|
||
2. **编辑迁移**: 在 `pkg/migration/migrations.go` 中添加迁移定义
|
||
3. **测试迁移**: `make migrate-up` 和 `make migrate-down STEPS=1`
|
||
4. **部署生产**: `./scripts/production-migrate.sh migrate`
|
||
|
||
### 特性
|
||
|
||
- ✅ **版本控制**: 时间戳版本号，确保迁移顺序
|
||
- ✅ **回滚支持**: 每个迁移都支持安全回滚
|
||
- ✅ **自动备份**: 生产环境迁移前自动备份
|
||
- ✅ **SQLite 优化**: 针对 SQLite 限制的特殊处理
|
||
- ✅ **事务安全**: 每个迁移在事务中执行
|
||
- ✅ **状态跟踪**: 完整的迁移状态记录
|
||
- ✅ **预览模式**: 支持预览迁移而不实际执行
|
||
- ✅ **日志记录**: 详细的迁移日志和错误追踪
|
||
|
||
详细使用方法请参考: [数据库迁移文档](docs/DATABASE_MIGRATION.md)
|
||
|
||
本 CLAUDE.md 文件为后端开发提供了全面的指导，遵循 go-zero 框架的最佳实践。 |