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%
11 KiB
11 KiB
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 # 性能测试
🚀 快速开始
环境准备
# 1. 安装 Go 1.23+
go version
# 2. 安装 goctl 工具
go install github.com/zeromicro/go-zero/tools/goctl@latest
# 3. 验证安装
goctl --version
项目初始化
# 1. 创建项目目录
mkdir photography-backend && cd photography-backend
# 2. 初始化 Go 模块
go mod init photography-backend
# 3. 创建 API 定义文件
mkdir -p api/desc
快速开发流程
# 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 目录下添加不同的服务入口：
# 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 # 完整迁移文档
快速迁移命令
# 开发环境
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 # 全新初始化
迁移开发流程
- 创建迁移:
make migrate-create NAME="add_user_field" - 编辑迁移: 在
pkg/migration/migrations.go中添加迁移定义 - 测试迁移:
make migrate-up和make migrate-down STEPS=1 - 部署生产:
./scripts/production-migrate.sh migrate
特性
- ✅ 版本控制: 时间戳版本号，确保迁移顺序
- ✅ 回滚支持: 每个迁移都支持安全回滚
- ✅ 自动备份: 生产环境迁移前自动备份
- ✅ SQLite 优化: 针对 SQLite 限制的特殊处理
- ✅ 事务安全: 每个迁移在事务中执行
- ✅ 状态跟踪: 完整的迁移状态记录
- ✅ 预览模式: 支持预览迁移而不实际执行
- ✅ 日志记录: 详细的迁移日志和错误追踪
详细使用方法请参考: 数据库迁移文档
本 CLAUDE.md 文件为后端开发提供了全面的指导，遵循 go-zero 框架的最佳实践。