photography/backend-old/cmd/server/CLAUDE.md

Server Entry Point - CLAUDE.md

本文件为 Claude Code 在服务器入口模块中工作时提供指导。

🎯 模块概览

这是后端服务的启动入口模块，负责应用初始化、配置加载、依赖注入和服务启动。

主要职责

• 🚀 应用启动和生命周期管理
• ⚙️ 配置文件加载和环境变量解析
• 🔌 依赖注入和组件初始化
• 🌐 HTTP 服务器启动和路由注册
• 📊 数据库连接和迁移管理
• 🔧 优雅关闭和资源清理

推荐文件结构（Go 风格）

cmd/server/
├── CLAUDE.md           # 📋 当前文件 - 服务启动指导
├── main.go             # 🚀 统一入口点
├── app.go              # 🏗️ 应用构建器
├── config.go           # ⚙️ 配置加载器
├── dependencies.go     # 🔌 依赖注入容器
└── server.go           # 🌐 HTTP 服务器管理

🚀 启动模式说明

生产模式 (main.go)

// 特点：
// - PostgreSQL 数据库
// - Redis 缓存
// - 完整的中间件栈
// - 生产级日志配置
// - 健康检查端点

适用场景: 生产环境、集成测试、性能测试

开发模式 (main_with_db.go)

// 特点：
// - SQLite 数据库
// - 内存缓存
// - 开发友好的日志
// - 热重载支持
// - 调试工具集成

适用场景: 本地开发、单元测试、功能验证

Mock 模式 (simple_main.go)

// 特点：
// - 内存数据存储
// - 固定响应数据
// - 极快启动速度
// - 无数据库依赖
// - 最小化配置

适用场景: 前端开发、API 测试、演示环境

🔧 配置管理

配置文件层次

configs/
├── config.yaml      # 基础配置
├── config.dev.yaml  # 开发环境覆盖
└── config.prod.yaml # 生产环境覆盖

环境变量优先级

环境变量 > 配置文件 > 默认值

配置结构

type Config struct {
    Server    ServerConfig    `yaml:"server"`
    Database  DatabaseConfig  `yaml:"database"`
    Cache     CacheConfig     `yaml:"cache"`
    Storage   StorageConfig   `yaml:"storage"`
    Auth      AuthConfig      `yaml:"auth"`
    Log       LogConfig       `yaml:"log"`
}

🏗️ 依赖注入

依赖层次

main.go
├── 📋 Config Service
├── 📊 Database Service
├── 💾 Cache Service
├── 📁 Storage Service
├── 🔐 Auth Service
├── 📚 Repository Layer
├── 🏢 Service Layer
└── 🌐 Handler Layer

依赖注入模式

// 1. 配置加载
config := config.LoadConfig()

// 2. 基础服务初始化
db := database.NewConnection(config.Database)
cache := cache.NewRedisClient(config.Cache)
storage := storage.NewService(config.Storage)

// 3. 仓储层初始化
userRepo := repository.NewUserRepository(db)
photoRepo := repository.NewPhotoRepository(db)

// 4. 服务层初始化
userService := service.NewUserService(userRepo, cache)
photoService := service.NewPhotoService(photoRepo, storage)

// 5. 处理器层初始化
userHandler := handler.NewUserHandler(userService)
photoHandler := handler.NewPhotoHandler(photoService)

// 6. 路由设置
router := gin.New()
v1 := router.Group("/api/v1")
{
    v1.POST("/users", userHandler.Create)
    v1.GET("/users", userHandler.List)
    v1.GET("/photos", photoHandler.List)
    v1.POST("/photos", photoHandler.Create)
}

🔄 启动流程

标准启动流程

1. 配置加载: 解析配置文件和环境变量
2. 日志初始化: 设置日志级别和输出格式
3. 数据库连接: 建立数据库连接池
4. 缓存连接: 初始化 Redis 连接
5. 服务注册: 注册各层服务
6. 中间件设置: 配置认证、日志、CORS 等中间件
7. 路由注册: 注册所有 API 路由
8. 健康检查: 启动健康检查端点
9. 服务启动: 启动 HTTP 服务器
10. 优雅关闭: 处理关闭信号

启动命令

# 生产模式
go run cmd/server/main.go

# 开发模式
go run cmd/server/main_with_db.go

# Mock 模式
go run cmd/server/simple_main.go

# 使用 Makefile
make dev        # 开发模式
make dev-simple # Mock 模式
make prod       # 生产模式

📊 健康检查

健康检查端点

GET /health
GET /health/ready
GET /health/live

健康检查内容

• 数据库连接状态
• 缓存服务状态
• 存储服务状态
• 外部服务状态
• 系统资源状态

响应格式

{
  "status": "healthy",
  "timestamp": "2024-01-01T00:00:00Z",
  "version": "1.0.0",
  "checks": {
    "database": "healthy",
    "cache": "healthy",
    "storage": "healthy"
  }
}

🔧 优雅关闭

关闭信号处理

// 监听关闭信号
quit := make(chan os.Signal, 1)
signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)

// 等待关闭信号
<-quit
log.Println("Shutting down server...")

// 设置关闭超时
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

// 优雅关闭服务器
if err := srv.Shutdown(ctx); err != nil {
    log.Fatal("Server forced to shutdown:", err)
}

关闭流程

1. 停止接收新请求
2. 等待现有请求完成
3. 关闭数据库连接
4. 关闭缓存连接
5. 清理临时资源
6. 记录关闭日志

📋 环境变量配置

数据库配置

# PostgreSQL
DB_HOST=localhost
DB_PORT=5432
DB_NAME=photography
DB_USER=postgres
DB_PASSWORD=your_password
DB_SSL_MODE=disable

# SQLite (开发模式)
DB_TYPE=sqlite
DB_PATH=./photography.db

缓存配置

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DB=0

认证配置

# JWT
JWT_SECRET=your_jwt_secret
JWT_EXPIRES_IN=24h
JWT_REFRESH_EXPIRES_IN=168h

文件存储配置

# 本地存储
STORAGE_TYPE=local
STORAGE_PATH=./uploads
STORAGE_MAX_SIZE=10MB

# S3 存储
STORAGE_TYPE=s3
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
AWS_BUCKET_NAME=your_bucket
AWS_REGION=us-east-1

🧪 开发调试

调试模式启动

# 开启调试模式
export GIN_MODE=debug
export LOG_LEVEL=debug

# 启动服务
go run cmd/server/main_with_db.go

调试工具

• pprof: 性能分析
• gin-debug: 路由调试
• hot-reload: 代码热重载
• swagger: API 文档

调试端点

GET /debug/pprof/         # 性能分析
GET /debug/routes         # 路由列表
GET /debug/vars           # 运行时变量
GET /swagger/*            # API 文档

📊 监控指标

内置指标

• HTTP 请求数量
• HTTP 响应时间
• 数据库连接数
• 缓存命中率
• 内存使用量
• CPU 使用率

指标端点

GET /metrics             # Prometheus 指标
GET /stats               # 应用统计信息

🔍 常见问题

启动失败

1. 端口被占用: 检查端口配置，使用 lsof -i :8080 查看
2. 配置文件错误: 检查 YAML 语法，验证配置项
3. 数据库连接失败: 检查数据库服务状态和连接配置
4. 权限问题: 检查文件读写权限

性能问题

1. 启动慢: 检查数据库连接池配置
2. 内存泄漏: 使用 pprof 分析内存使用
3. 连接超时: 调整超时配置和连接池大小

日志问题

1. 日志文件过大: 配置日志轮转
2. 日志格式混乱: 统一日志格式配置
3. 敏感信息泄露: 配置敏感信息过滤

💡 最佳实践

配置管理

• 使用环境变量覆盖敏感配置
• 配置验证和默认值设置
• 配置变更的版本控制

错误处理

• 统一错误响应格式
• 详细的错误日志记录
• 适当的错误码设计

安全考虑

• 敏感信息不在日志中输出
• 配置文件权限控制
• 环境变量加密存储

性能优化

• 合理的超时配置
• 连接池大小调优
• 资源及时释放

本模块为整个应用的入口，确保配置正确、启动流程清晰是项目成功的关键。在开发过程中，优先使用开发模式进行功能验证，在集成测试时使用生产模式。