17 KiB
17 KiB
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. 环境准备
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 风格开发规范
代码结构规范
- 四层架构: API → Service → Repository → Model
- 接口导向: 使用接口定义契约，便于测试和替换
- 依赖注入: 构造函数注入，避免全局变量
- 错误处理: 显式错误处理，避免 panic
- 并发安全: 使用 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)
接口设计规范
// 接口定义
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
统一响应格式
// 成功响应
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"`
}
错误处理规范
// 自定义错误类型
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(),
})
}
日志记录规范
// 结构化日志
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"),
)
配置管理规范
// 配置结构体
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 认证流程
- 用户登录 → 验证凭据
- 生成 JWT Token (AccessToken + RefreshToken)
- 客户端携带 Token 访问受保护资源
- 服务器验证 Token 有效性
权限角色
- Admin: 系统管理员 (所有权限)
- Editor: 内容编辑者 (内容管理)
- User: 普通用户 (查看权限)
🧪 测试策略
测试类型
- 单元测试: 业务逻辑和工具函数
- 集成测试: API 接口和数据库交互
- 性能测试: 接口响应时间和并发测试
测试工具
- Go Testing: 内置测试框架
- Testify: 断言和模拟工具
- Mockery: 接口模拟生成
📚 API 文档
文档生成
- Swagger/OpenAPI: 自动生成 API 文档
- Postman Collection: 接口测试集合
- README: 快速开始指南
文档维护
- 接口变更时同步更新文档
- 提供完整的请求/响应示例
- 包含错误码和处理说明
🚀 部署配置
环境变量
# 数据库配置
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 部署
# 构建镜像
make build-image
# 启动服务
make prod-up
# 查看日志
make logs
📋 常用命令
开发命令
# 代码生成
make generate # 生成代码 (mocks, swagger)
# 代码检查
make lint # 代码检查
make fmt # 代码格式化
make vet # 代码分析
# 测试
make test # 运行测试
make test-cover # 测试覆盖率
make test-integration # 集成测试
# 构建
make build # 构建二进制文件
make build-image # 构建 Docker 镜像
数据库命令
# 迁移
make migrate-up # 应用迁移
make migrate-down # 回滚迁移
make migrate-create # 创建迁移文件
# 数据库管理
make db-reset # 重置数据库
make db-seed # 导入种子数据
🔍 问题排查
常见问题
- 数据库连接失败: 检查配置文件和环境变量
- JWT 验证失败: 检查密钥配置和 Token 格式
- 文件上传失败: 检查存储配置和权限设置
- API 响应慢: 检查数据库查询和缓存配置
日志查看
# 查看应用日志
tail -f logs/app.log
# 查看错误日志
tail -f logs/error.log
# 查看访问日志
tail -f logs/access.log
🎯 模块工作指南
根据工作内容选择模块
🚀 应用启动和配置
cd cmd/server/
# 参考 cmd/server/CLAUDE.md
适用场景: 服务启动、配置初始化、依赖注入
🌐 API 接口开发
cd internal/api/
# 参考 internal/api/CLAUDE.md
适用场景: 路由定义、HTTP 处理器、中间件、请求验证
📋 业务逻辑开发
cd internal/application/
# 参考 internal/application/CLAUDE.md
适用场景: 业务逻辑、服务编排、数据传输对象
🏢 领域模型设计
cd internal/domain/
# 参考 internal/domain/CLAUDE.md
适用场景: 业务实体、业务规则、仓储接口
🔧 基础设施开发
cd internal/infrastructure/
# 参考 internal/infrastructure/CLAUDE.md
适用场景: 数据库、缓存、文件存储、外部服务
📦 工具包开发
cd pkg/
# 参考 pkg/CLAUDE.md
适用场景: 通用工具、日志、验证器、响应格式
🧪 测试开发
cd tests/
# 参考 tests/CLAUDE.md
适用场景: 单元测试、集成测试、性能测试
📚 文档维护
cd docs/
# 参考 docs/CLAUDE.md
适用场景: API 文档、架构设计、部署指南
🔄 最佳实践
开发流程
- 功能分析: 确定需求和技术方案
- 选择模块: 根据工作内容选择对应模块
- 阅读指导: 详细阅读模块的 CLAUDE.md 文件
- 编码实现: 遵循模块规范进行开发
- 测试验证: 编写和运行相关测试
- 文档更新: 同步更新相关文档
代码质量
- 代码审查: 提交前进行代码审查
- 测试覆盖: 保持合理的测试覆盖率
- 性能优化: 关注接口响应时间和资源使用
- 安全检查: 验证认证、授权和数据验证
模块协调
- 接口一致性: 确保模块间接口的一致性
- 依赖管理: 合理管理模块间的依赖关系
- 配置统一: 统一配置管理和环境变量
- 错误处理: 统一错误处理和响应格式
📈 项目状态
已完成功能
- ✅ 清洁架构设计
- ✅ 多数据库支持
- ✅ 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 文件，确保开发过程中可以快速获取相关信息，提高开发效率。