596 lines
17 KiB
Markdown
596 lines
17 KiB
Markdown
# Backend API Service - CLAUDE.md
|
||
|
||
本文件为 Claude Code 在后端 API 服务模块中工作时提供指导。
|
||
|
||
## 🎯 模块概览
|
||
|
||
这是一个基于 Go + Gin 框架的 REST API 后端服务，采用简洁的四层架构模式，遵循 Go 语言的简洁设计哲学。
|
||
|
||
### 主要特性
|
||
- 🏗️ 简洁四层架构 (API → Service → Repository → Model)
|
||
- 🚀 多种部署模式 (生产/开发/Mock)
|
||
- 📊 多数据库支持 (PostgreSQL + SQLite + Redis)
|
||
- 🔐 JWT 认证 + 基于角色的访问控制
|
||
- 📁 文件上传和存储管理
|
||
- 🐳 Docker 容器化部署
|
||
- 📊 健康检查和监控
|
||
- 📚 API 文档生成
|
||
|
||
### 技术栈
|
||
- **语言**: Go 1.23+
|
||
- **框架**: Gin v1.10.1
|
||
- **数据库**: PostgreSQL (生产) + SQLite (开发) + Redis (缓存)
|
||
- **ORM**: GORM v1.30.0
|
||
- **认证**: JWT (golang-jwt/jwt/v5)
|
||
- **日志**: Uber Zap
|
||
- **配置**: Viper
|
||
- **容器化**: Docker + Docker Compose
|
||
|
||
## 📁 简洁架构设计
|
||
|
||
### 核心模块结构（重构后）
|
||
```
|
||
backend/
|
||
├── CLAUDE.md # 📋 当前文件 - 后端总览
|
||
├── cmd/ # 🚀 应用入口模块
|
||
│ ├── server/ # 服务启动器
|
||
│ │ ├── CLAUDE.md # 启动服务配置指导
|
||
│ │ └── main.go # 统一入口（支持多模式）
|
||
│ └── migrate/ # 数据库迁移工具
|
||
│ └── main.go
|
||
├── internal/ # 📦 核心业务模块
|
||
│ ├── api/ # 🌐 HTTP 接口层
|
||
│ │ ├── CLAUDE.md # API 路由和处理器指导
|
||
│ │ ├── handlers/ # HTTP 处理器
|
||
│ │ ├── middleware/ # 中间件
|
||
│ │ ├── routes/ # 路由定义
|
||
│ │ └── validators/ # 请求验证
|
||
│ ├── service/ # 📋 业务逻辑层
|
||
│ │ ├── CLAUDE.md # 业务逻辑开发指导
|
||
│ │ ├── auth/ # 认证服务
|
||
│ │ ├── user/ # 用户服务
|
||
│ │ ├── photo/ # 照片服务
|
||
│ │ ├── category/ # 分类服务
|
||
│ │ └── storage/ # 文件存储服务
|
||
│ ├── repository/ # 🔧 数据访问层
|
||
│ │ ├── CLAUDE.md # 数据访问开发指导
|
||
│ │ ├── interfaces/ # 仓储接口
|
||
│ │ ├── postgres/ # PostgreSQL 实现
|
||
│ │ ├── redis/ # Redis 实现
|
||
│ │ └── sqlite/ # SQLite 实现
|
||
│ ├── model/ # 📦 数据模型层
|
||
│ │ ├── CLAUDE.md # 数据模型设计指导
|
||
│ │ ├── entity/ # 实体模型
|
||
│ │ ├── dto/ # 数据传输对象
|
||
│ │ └── request/ # 请求响应模型
|
||
│ └── config/ # ⚙️ 配置管理
|
||
│ ├── CLAUDE.md # 配置文件管理指导
|
||
│ └── config.go # 配置结构体
|
||
├── pkg/ # 📦 共享包模块
|
||
│ ├── CLAUDE.md # 公共工具包指导
|
||
│ ├── logger/ # 日志工具
|
||
│ ├── response/ # 响应格式
|
||
│ ├── validator/ # 验证器
|
||
│ └── utils/ # 通用工具
|
||
├── configs/ # 📋 配置文件
|
||
├── migrations/ # 📊 数据库迁移
|
||
├── tests/ # 🧪 测试模块
|
||
│ ├── CLAUDE.md # 测试编写和执行指导
|
||
│ ├── unit/ # 单元测试
|
||
│ ├── integration/ # 集成测试
|
||
│ └── mocks/ # 模拟对象
|
||
└── docs/ # 📚 文档模块
|
||
├── CLAUDE.md # API 文档和接口设计指导
|
||
└── api/ # API 文档
|
||
```
|
||
|
||
### Go 风格的四层架构
|
||
|
||
#### 🌐 API 层 (`internal/api/`)
|
||
- **职责**: HTTP 请求处理、路由定义、中间件、参数验证
|
||
- **文件**: `handlers/`, `middleware/`, `routes/`, `validators/`
|
||
- **指导**: `internal/api/CLAUDE.md`
|
||
|
||
#### 📋 Service 层 (`internal/service/`)
|
||
- **职责**: 业务逻辑处理、服务编排、事务管理
|
||
- **文件**: `auth/`, `user/`, `photo/`, `category/`, `storage/`
|
||
- **指导**: `internal/service/CLAUDE.md`
|
||
|
||
#### 🔧 Repository 层 (`internal/repository/`)
|
||
- **职责**: 数据访问、数据库操作、缓存管理
|
||
- **文件**: `interfaces/`, `postgres/`, `redis/`, `sqlite/`
|
||
- **指导**: `internal/repository/CLAUDE.md`
|
||
|
||
#### 📦 Model 层 (`internal/model/`)
|
||
- **职责**: 数据模型、实体定义、DTO 转换
|
||
- **文件**: `entity/`, `dto/`, `request/`
|
||
- **指导**: `internal/model/CLAUDE.md`
|
||
|
||
### 简洁性原则
|
||
|
||
1. **单一职责**: 每个模块只负责一个明确的功能
|
||
2. **依赖注入**: 使用接口解耦，便于测试和扩展
|
||
3. **配置集中**: 所有配置统一管理，支持多环境
|
||
4. **错误处理**: 统一的错误处理机制
|
||
5. **代码生成**: 减少重复代码，提高开发效率
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 开发环境设置
|
||
```bash
|
||
# 1. 环境准备
|
||
cd backend/
|
||
make setup # 初始化开发环境
|
||
|
||
# 2. 开发模式选择
|
||
make dev-simple # Mock 服务器 (前端开发)
|
||
make dev # SQLite 开发服务器 (全功能)
|
||
make dev-full # PostgreSQL 开发服务器 (生产环境)
|
||
|
||
# 3. 生产部署
|
||
make prod-up # Docker 容器部署
|
||
```
|
||
|
||
### 服务模式说明
|
||
- **Mock 模式**: 快速响应的模拟 API，用于前端开发
|
||
- **开发模式**: 完整功能的 SQLite 数据库，用于本地开发
|
||
- **生产模式**: PostgreSQL + Redis，用于生产环境
|
||
|
||
## 🔧 Go 风格开发规范
|
||
|
||
### 代码结构规范
|
||
1. **四层架构**: API → Service → Repository → Model
|
||
2. **接口导向**: 使用接口定义契约，便于测试和替换
|
||
3. **依赖注入**: 构造函数注入，避免全局变量
|
||
4. **错误处理**: 显式错误处理，避免 panic
|
||
5. **并发安全**: 使用 context 和 sync 包确保并发安全
|
||
|
||
### Go 语言命名规范
|
||
```
|
||
文件和目录:
|
||
- 文件名: snake_case (user_service.go)
|
||
- 包名: 小写单词 (userservice 或 user)
|
||
- 目录名: 小写单词 (auth, user, photo)
|
||
|
||
代码命名:
|
||
- 结构体: PascalCase (UserService, PhotoEntity)
|
||
- 接口: PascalCase + er结尾 (UserServicer, PhotoStorer)
|
||
- 方法/函数: PascalCase (GetUser, CreatePhoto)
|
||
- 变量: camelCase (userService, photoList)
|
||
- 常量: PascalCase (MaxUserCount, DefaultPageSize)
|
||
- 枚举: PascalCase (UserStatusActive, UserStatusInactive)
|
||
```
|
||
|
||
### 接口设计规范
|
||
```go
|
||
// 接口定义
|
||
type UserServicer interface {
|
||
GetUser(ctx context.Context, id uint) (*entity.User, error)
|
||
CreateUser(ctx context.Context, req *dto.CreateUserRequest) (*entity.User, error)
|
||
UpdateUser(ctx context.Context, id uint, req *dto.UpdateUserRequest) error
|
||
DeleteUser(ctx context.Context, id uint) error
|
||
ListUsers(ctx context.Context, opts *dto.ListUsersOptions) ([]*entity.User, int64, error)
|
||
}
|
||
|
||
// 实现规范
|
||
type UserService struct {
|
||
userRepo repository.UserRepositoryr
|
||
logger logger.Logger
|
||
}
|
||
|
||
func NewUserService(userRepo repository.UserRepositoryr, logger logger.Logger) UserServicer {
|
||
return &UserService{
|
||
userRepo: userRepo,
|
||
logger: logger,
|
||
}
|
||
}
|
||
```
|
||
|
||
### RESTful API 设计规范
|
||
```
|
||
资源路径规范:
|
||
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/users/:id/photos # 获取用户的照片
|
||
POST /api/v1/users/:id/photos # 为用户创建照片
|
||
|
||
查询参数:
|
||
GET /api/v1/users?page=1&limit=20&sort=created_at&order=desc
|
||
```
|
||
|
||
### 统一响应格式
|
||
```go
|
||
// 成功响应
|
||
type SuccessResponse struct {
|
||
Success bool `json:"success"`
|
||
Data interface{} `json:"data,omitempty"`
|
||
Message string `json:"message,omitempty"`
|
||
Timestamp int64 `json:"timestamp"`
|
||
}
|
||
|
||
// 错误响应
|
||
type ErrorResponse struct {
|
||
Success bool `json:"success"`
|
||
Error Error `json:"error"`
|
||
Timestamp int64 `json:"timestamp"`
|
||
}
|
||
|
||
type Error struct {
|
||
Code string `json:"code"`
|
||
Message string `json:"message"`
|
||
Details string `json:"details,omitempty"`
|
||
}
|
||
```
|
||
|
||
### 错误处理规范
|
||
```go
|
||
// 自定义错误类型
|
||
type AppError struct {
|
||
Code string
|
||
Message string
|
||
Details string
|
||
Err error
|
||
}
|
||
|
||
func (e *AppError) Error() string {
|
||
return e.Message
|
||
}
|
||
|
||
// 错误码定义
|
||
const (
|
||
ErrCodeUserNotFound = "USER_NOT_FOUND"
|
||
ErrCodeInvalidParameter = "INVALID_PARAMETER"
|
||
ErrCodePermissionDenied = "PERMISSION_DENIED"
|
||
ErrCodeInternalError = "INTERNAL_ERROR"
|
||
)
|
||
|
||
// 错误处理函数
|
||
func HandleError(c *gin.Context, err error) {
|
||
var appErr *AppError
|
||
if errors.As(err, &appErr) {
|
||
c.JSON(http.StatusBadRequest, ErrorResponse{
|
||
Success: false,
|
||
Error: Error{
|
||
Code: appErr.Code,
|
||
Message: appErr.Message,
|
||
Details: appErr.Details,
|
||
},
|
||
Timestamp: time.Now().Unix(),
|
||
})
|
||
return
|
||
}
|
||
|
||
// 未知错误
|
||
c.JSON(http.StatusInternalServerError, ErrorResponse{
|
||
Success: false,
|
||
Error: Error{
|
||
Code: ErrCodeInternalError,
|
||
Message: "内部服务器错误",
|
||
},
|
||
Timestamp: time.Now().Unix(),
|
||
})
|
||
}
|
||
```
|
||
|
||
### 日志记录规范
|
||
```go
|
||
// 结构化日志
|
||
logger.Info("user created successfully",
|
||
zap.String("user_id", user.ID),
|
||
zap.String("username", user.Username),
|
||
zap.String("operation", "create_user"),
|
||
)
|
||
|
||
// 错误日志
|
||
logger.Error("failed to create user",
|
||
zap.Error(err),
|
||
zap.String("username", req.Username),
|
||
zap.String("operation", "create_user"),
|
||
)
|
||
```
|
||
|
||
### 配置管理规范
|
||
```go
|
||
// 配置结构体
|
||
type Config struct {
|
||
Server ServerConfig `mapstructure:"server"`
|
||
Database DatabaseConfig `mapstructure:"database"`
|
||
Redis RedisConfig `mapstructure:"redis"`
|
||
JWT JWTConfig `mapstructure:"jwt"`
|
||
Storage StorageConfig `mapstructure:"storage"`
|
||
}
|
||
|
||
// 环境变量映射
|
||
type ServerConfig struct {
|
||
Port string `mapstructure:"port" env:"SERVER_PORT"`
|
||
Mode string `mapstructure:"mode" env:"SERVER_MODE"`
|
||
LogLevel string `mapstructure:"log_level" env:"LOG_LEVEL"`
|
||
}
|
||
```
|
||
|
||
## 📊 数据库设计
|
||
|
||
### 主要实体
|
||
- **User**: 用户信息和权限
|
||
- **Photo**: 照片信息和元数据
|
||
- **Category**: 照片分类
|
||
- **Tag**: 照片标签
|
||
- **Album**: 相册管理
|
||
|
||
### 关系设计
|
||
```
|
||
User (1:N) Photo
|
||
Photo (N:M) Category
|
||
Photo (N:M) Tag
|
||
User (1:N) Album
|
||
Album (N:M) Photo
|
||
```
|
||
|
||
## 🔐 认证和授权
|
||
|
||
### JWT 认证流程
|
||
1. 用户登录 → 验证凭据
|
||
2. 生成 JWT Token (AccessToken + RefreshToken)
|
||
3. 客户端携带 Token 访问受保护资源
|
||
4. 服务器验证 Token 有效性
|
||
|
||
### 权限角色
|
||
- **Admin**: 系统管理员 (所有权限)
|
||
- **Editor**: 内容编辑者 (内容管理)
|
||
- **User**: 普通用户 (查看权限)
|
||
|
||
## 🧪 测试策略
|
||
|
||
### 测试类型
|
||
- **单元测试**: 业务逻辑和工具函数
|
||
- **集成测试**: API 接口和数据库交互
|
||
- **性能测试**: 接口响应时间和并发测试
|
||
|
||
### 测试工具
|
||
- **Go Testing**: 内置测试框架
|
||
- **Testify**: 断言和模拟工具
|
||
- **Mockery**: 接口模拟生成
|
||
|
||
## 📚 API 文档
|
||
|
||
### 文档生成
|
||
- **Swagger/OpenAPI**: 自动生成 API 文档
|
||
- **Postman Collection**: 接口测试集合
|
||
- **README**: 快速开始指南
|
||
|
||
### 文档维护
|
||
- 接口变更时同步更新文档
|
||
- 提供完整的请求/响应示例
|
||
- 包含错误码和处理说明
|
||
|
||
## 🚀 部署配置
|
||
|
||
### 环境变量
|
||
```bash
|
||
# 数据库配置
|
||
DB_HOST=localhost
|
||
DB_PORT=5432
|
||
DB_NAME=photography
|
||
DB_USER=postgres
|
||
DB_PASSWORD=password
|
||
|
||
# JWT 配置
|
||
JWT_SECRET=your-secret-key
|
||
JWT_EXPIRES_IN=24h
|
||
|
||
# 文件存储
|
||
STORAGE_TYPE=local
|
||
STORAGE_PATH=./uploads
|
||
```
|
||
|
||
### Docker 部署
|
||
```bash
|
||
# 构建镜像
|
||
make build-image
|
||
|
||
# 启动服务
|
||
make prod-up
|
||
|
||
# 查看日志
|
||
make logs
|
||
```
|
||
|
||
## 📋 常用命令
|
||
|
||
### 开发命令
|
||
```bash
|
||
# 代码生成
|
||
make generate # 生成代码 (mocks, swagger)
|
||
|
||
# 代码检查
|
||
make lint # 代码检查
|
||
make fmt # 代码格式化
|
||
make vet # 代码分析
|
||
|
||
# 测试
|
||
make test # 运行测试
|
||
make test-cover # 测试覆盖率
|
||
make test-integration # 集成测试
|
||
|
||
# 构建
|
||
make build # 构建二进制文件
|
||
make build-image # 构建 Docker 镜像
|
||
```
|
||
|
||
### 数据库命令
|
||
```bash
|
||
# 迁移
|
||
make migrate-up # 应用迁移
|
||
make migrate-down # 回滚迁移
|
||
make migrate-create # 创建迁移文件
|
||
|
||
# 数据库管理
|
||
make db-reset # 重置数据库
|
||
make db-seed # 导入种子数据
|
||
```
|
||
|
||
## 🔍 问题排查
|
||
|
||
### 常见问题
|
||
1. **数据库连接失败**: 检查配置文件和环境变量
|
||
2. **JWT 验证失败**: 检查密钥配置和 Token 格式
|
||
3. **文件上传失败**: 检查存储配置和权限设置
|
||
4. **API 响应慢**: 检查数据库查询和缓存配置
|
||
|
||
### 日志查看
|
||
```bash
|
||
# 查看应用日志
|
||
tail -f logs/app.log
|
||
|
||
# 查看错误日志
|
||
tail -f logs/error.log
|
||
|
||
# 查看访问日志
|
||
tail -f logs/access.log
|
||
```
|
||
|
||
## 🎯 模块工作指南
|
||
|
||
### 根据工作内容选择模块
|
||
|
||
#### 🚀 应用启动和配置
|
||
```bash
|
||
cd cmd/server/
|
||
# 参考 cmd/server/CLAUDE.md
|
||
```
|
||
**适用场景**: 服务启动、配置初始化、依赖注入
|
||
|
||
#### 🌐 API 接口开发
|
||
```bash
|
||
cd internal/api/
|
||
# 参考 internal/api/CLAUDE.md
|
||
```
|
||
**适用场景**: 路由定义、HTTP 处理器、中间件、请求验证
|
||
|
||
#### 📋 业务逻辑开发
|
||
```bash
|
||
cd internal/application/
|
||
# 参考 internal/application/CLAUDE.md
|
||
```
|
||
**适用场景**: 业务逻辑、服务编排、数据传输对象
|
||
|
||
#### 🏢 领域模型设计
|
||
```bash
|
||
cd internal/domain/
|
||
# 参考 internal/domain/CLAUDE.md
|
||
```
|
||
**适用场景**: 业务实体、业务规则、仓储接口
|
||
|
||
#### 🔧 基础设施开发
|
||
```bash
|
||
cd internal/infrastructure/
|
||
# 参考 internal/infrastructure/CLAUDE.md
|
||
```
|
||
**适用场景**: 数据库、缓存、文件存储、外部服务
|
||
|
||
#### 📦 工具包开发
|
||
```bash
|
||
cd pkg/
|
||
# 参考 pkg/CLAUDE.md
|
||
```
|
||
**适用场景**: 通用工具、日志、验证器、响应格式
|
||
|
||
#### 🧪 测试开发
|
||
```bash
|
||
cd tests/
|
||
# 参考 tests/CLAUDE.md
|
||
```
|
||
**适用场景**: 单元测试、集成测试、性能测试
|
||
|
||
#### 📚 文档维护
|
||
```bash
|
||
cd docs/
|
||
# 参考 docs/CLAUDE.md
|
||
```
|
||
**适用场景**: API 文档、架构设计、部署指南
|
||
|
||
## 🔄 最佳实践
|
||
|
||
### 开发流程
|
||
1. **功能分析**: 确定需求和技术方案
|
||
2. **选择模块**: 根据工作内容选择对应模块
|
||
3. **阅读指导**: 详细阅读模块的 CLAUDE.md 文件
|
||
4. **编码实现**: 遵循模块规范进行开发
|
||
5. **测试验证**: 编写和运行相关测试
|
||
6. **文档更新**: 同步更新相关文档
|
||
|
||
### 代码质量
|
||
- **代码审查**: 提交前进行代码审查
|
||
- **测试覆盖**: 保持合理的测试覆盖率
|
||
- **性能优化**: 关注接口响应时间和资源使用
|
||
- **安全检查**: 验证认证、授权和数据验证
|
||
|
||
### 模块协调
|
||
- **接口一致性**: 确保模块间接口的一致性
|
||
- **依赖管理**: 合理管理模块间的依赖关系
|
||
- **配置统一**: 统一配置管理和环境变量
|
||
- **错误处理**: 统一错误处理和响应格式
|
||
|
||
## 📈 项目状态
|
||
|
||
### 已完成功能
|
||
- ✅ 清洁架构设计
|
||
- ✅ 多数据库支持
|
||
- ✅ JWT 认证系统
|
||
- ✅ 文件上传功能
|
||
- ✅ Docker 部署
|
||
- ✅ 基础 API 接口
|
||
|
||
### 开发中功能
|
||
- 🔄 完整的测试覆盖
|
||
- 🔄 API 文档生成
|
||
- 🔄 性能监控
|
||
- 🔄 缓存优化
|
||
|
||
### 计划中功能
|
||
- 📋 微服务架构
|
||
- 📋 分布式文件存储
|
||
- 📋 消息队列集成
|
||
- 📋 监控和报警系统
|
||
|
||
## 🔧 开发环境
|
||
|
||
### 必需工具
|
||
- **Go 1.23+**: 编程语言
|
||
- **PostgreSQL 14+**: 主数据库
|
||
- **Redis 6+**: 缓存数据库
|
||
- **Docker**: 容器化部署
|
||
- **Make**: 构建工具
|
||
|
||
### 推荐工具
|
||
- **GoLand/VSCode**: 代码编辑器
|
||
- **Postman**: API 测试
|
||
- **DBeaver**: 数据库管理
|
||
- **Redis Desktop Manager**: Redis 管理
|
||
|
||
## 💡 开发技巧
|
||
|
||
### 性能优化
|
||
- 使用数据库连接池
|
||
- 实现查询结果缓存
|
||
- 优化 SQL 查询语句
|
||
- 使用异步处理
|
||
|
||
### 安全防护
|
||
- 输入参数验证
|
||
- SQL 注入防护
|
||
- XSS 攻击防护
|
||
- 访问频率限制
|
||
|
||
### 错误处理
|
||
- 统一错误响应格式
|
||
- 详细的错误日志记录
|
||
- 适当的错误码设计
|
||
- 友好的错误提示
|
||
|
||
本 CLAUDE.md 文件为后端开发提供了全面的指导，每个子模块都有详细的 CLAUDE.md 文件，确保开发过程中可以快速获取相关信息，提高开发效率。 |