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`)
```go
// 特点：
// - PostgreSQL 数据库
// - Redis 缓存
// - 完整的中间件栈
// - 生产级日志配置
// - 健康检查端点
```

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

### 开发模式 (`main_with_db.go`)
```go
// 特点：
// - SQLite 数据库
// - 内存缓存
// - 开发友好的日志
// - 热重载支持
// - 调试工具集成
```

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

### Mock 模式 (`simple_main.go`)
```go
// 特点：
// - 内存数据存储
// - 固定响应数据
// - 极快启动速度
// - 无数据库依赖
// - 最小化配置
```

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

## 🔧 配置管理

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

### 环境变量优先级
```
环境变量 > 配置文件 > 默认值
```

### 配置结构
```go
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
```

### 依赖注入模式
```go
// 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. **优雅关闭**: 处理关闭信号

### 启动命令
```bash
# 生产模式
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       # 生产模式
```

## 📊 健康检查

### 健康检查端点
```go
GET /health
GET /health/ready
GET /health/live
```

### 健康检查内容
- **数据库连接状态**
- **缓存服务状态**
- **存储服务状态**
- **外部服务状态**
- **系统资源状态**

### 响应格式
```json
{
  "status": "healthy",
  "timestamp": "2024-01-01T00:00:00Z",
  "version": "1.0.0",
  "checks": {
    "database": "healthy",
    "cache": "healthy",
    "storage": "healthy"
  }
}
```

## 🔧 优雅关闭

### 关闭信号处理
```go
// 监听关闭信号
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. **记录关闭日志**

## 📋 环境变量配置

### 数据库配置
```bash
# 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
```

### 缓存配置
```bash
# Redis
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DB=0
```

### 认证配置
```bash
# JWT
JWT_SECRET=your_jwt_secret
JWT_EXPIRES_IN=24h
JWT_REFRESH_EXPIRES_IN=168h
```

### 文件存储配置
```bash
# 本地存储
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
```

## 🧪 开发调试

### 调试模式启动
```bash
# 开启调试模式
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. **敏感信息泄露**: 配置敏感信息过滤

## 💡 最佳实践

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

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

### 安全考虑
- 敏感信息不在日志中输出
- 配置文件权限控制
- 环境变量加密存储

### 性能优化
- 合理的超时配置
- 连接池大小调优
- 资源及时释放

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