photography/backend/CLAUDE.md

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，完整的生产环境配置
• 测试模式: 使用内存数据库，用于单元测试和集成测试

本 CLAUDE.md 文件为后端开发提供了全面的指导，遵循 go-zero 框架的最佳实践。