fix
This commit is contained in:
xujiang
363
backend-old/cmd/server/CLAUDE.md
Normal file
363
backend-old/cmd/server/CLAUDE.md
Normal file
@ -0,0 +1,363 @@
|
||||
# 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. **敏感信息泄露**: 配置敏感信息过滤
|
||||
|
||||
## 💡 最佳实践
|
||||
|
||||
### 配置管理
|
||||
- 使用环境变量覆盖敏感配置
|
||||
- 配置验证和默认值设置
|
||||
- 配置变更的版本控制
|
||||
|
||||
### 错误处理
|
||||
- 统一错误响应格式
|
||||
- 详细的错误日志记录
|
||||
- 适当的错误码设计
|
||||
|
||||
### 安全考虑
|
||||
- 敏感信息不在日志中输出
|
||||
- 配置文件权限控制
|
||||
- 环境变量加密存储
|
||||
|
||||
### 性能优化
|
||||
- 合理的超时配置
|
||||
- 连接池大小调优
|
||||
- 资源及时释放
|
||||
|
||||
本模块为整个应用的入口，确保配置正确、启动流程清晰是项目成功的关键。在开发过程中，优先使用开发模式进行功能验证，在集成测试时使用生产模式。
|
||||
Reference in New Issue
Block a user