# 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 文件，确保开发过程中可以快速获取相关信息，提高开发效率。