1e828e03fe
## 主要功能 - ✅ 用户认证模块 (登录/注册/JWT) - ✅ 照片管理模块 (上传/查询/分页/搜索) - ✅ 分类管理模块 (创建/查询/分页) - ✅ 用户管理模块 (用户列表/分页查询) - ✅ 健康检查接口 ## 技术实现 - 基于 go-zero v1.8.0 标准架构 - Handler → Logic → Model 三层架构 - SQLite/PostgreSQL 数据库支持 - JWT 认证机制 - bcrypt 密码加密 - 统一响应格式 - 自定义模型方法 (分页/搜索) ## API 接口 - POST /api/v1/auth/login - 用户登录 - POST /api/v1/auth/register - 用户注册 - GET /api/v1/health - 健康检查 - GET /api/v1/photos - 照片列表 - POST /api/v1/photos - 上传照片 - GET /api/v1/categories - 分类列表 - POST /api/v1/categories - 创建分类 - GET /api/v1/users - 用户列表 ## 配置完成 - 开发环境配置 (SQLite) - 生产环境支持 (PostgreSQL) - JWT 认证配置 - 文件上传配置 - Makefile 构建脚本 服务已验证可正常构建和启动。
184 lines
8.7 KiB
Markdown
184 lines
8.7 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，完整的生产环境配置
|
||
- **测试模式**: 使用内存数据库，用于单元测试和集成测试
|
||
|
||
本 CLAUDE.md 文件为后端开发提供了全面的指导，遵循 go-zero 框架的最佳实践。 |