┌─────────────────────────────────────────────────────────────┐
│ Client Layer │
│ (Web/Mobile/API Clients) │
└────────────────────┬────────────────────────────────────────┘
│ HTTP/HTTPS
┌────────────────────▼────────────────────────────────────────┐
│ API Gateway / Load Balancer │
│ (Nginx/Traefik) │
└────────────────────┬────────────────────────────────────────┘
│
┌────────────────────▼────────────────────────────────────────┐
│ Gin Web Application │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Middleware Layer │ │
│ │ • CORS • Logger • Recovery • Rate Limit │ │
│ └──────────────────┬───────────────────────────────────┘ │
│ ┌──────────────────▼───────────────────────────────────┐ │
│ │ Controller Layer │ │
│ │ • Request Validation • Response Formatting │ │
│ └──────────────────┬───────────────────────────────────┘ │
│ ┌──────────────────▼───────────────────────────────────┐ │
│ │ Service Layer │ │
│ │ • Business Logic • Transaction Management │ │
│ └──────────────────┬───────────────────────────────────┘ │
│ ┌──────────────────▼───────────────────────────────────┐ │
│ │ Repository Layer │ │
│ │ • Data Access • Query Building │ │
│ └──────────────────┬───────────────────────────────────┘ │
└────────────────────┬────────────────────────────────────────┘
│
┌────────────┴────────────┐
│ │
┌───────▼────────┐ ┌───────▼────────┐
│ PostgreSQL │ │ Redis │
│ (Primary DB) │ │ (Cache) │
└────────────────┘ └────────────────┘
项目采用经典的三层架构模式，职责清晰分明：
- 职责: HTTP 请求处理和响应
- 功能:
- 接收和验证请求参数
- 调用 Service 层处理业务逻辑
- 格式化响应数据
- 错误处理和转换
- 原则: 薄控制器，不包含业务逻辑
- 职责: 业务逻辑实现
- 功能:
- 实现具体业务规则
- 数据验证和转换
- 事务管理
- 调用 Repository 层进行数据操作
- 原则: 业务逻辑的核心，可复用
- 职责: 数据访问和持久化
- 功能:
- 数据库 CRUD 操作
- 查询构建
- 数据映射
- 原则: 与具体数据库实现解耦
采用 Go 社区广泛认可的标准项目布局：
gin-app-start/
├── cmd/ # 应用入口
├── internal/ # 私有应用代码
├── pkg/ # 公共库代码
├── configs/ # 配置文件
└── docs/ # 文档
internal/
├── config/ # 配置管理
├── controller/ # HTTP 处理器
├── service/ # 业务逻辑
├── repository/ # 数据访问
├── model/ # 数据模型
├── middleware/ # 中间件
└── router/ # 路由配置
设计理念:
- 每个包职责单一
- 依赖关系清晰：controller → service → repository
- 便于单元测试
- 易于维护和扩展
pkg/
├── database/ # 数据库连接
├── logger/ # 日志系统
├── errors/ # 错误处理
├── response/ # 响应格式
└── utils/ # 工具函数
设计理念:
- 可被其他项目复用
- 无业务逻辑依赖
- 高内聚低耦合
┌─────────────────────────────────────────┐
│ Configuration Management │
├─────────────────────────────────────────┤
│ │
│ Environment Variable (SERVER_ENV) │
│ │ │
│ ▼ │
│ ┌──────────────────────┐ │
│ │ Viper Config Loader │ │
│ └──────────┬───────────┘ │
│ │ │
│ ┌────────┴─────────┐ │
│ │ │ │
│ ▼ ▼ │
│ config.local.yaml config.prod.yaml │
│ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ Config Struct │ │
│ └────────────────┘ │
│ │
└─────────────────────────────────────────┘
特点:
- 多环境支持（local/dev/prod）
- 环境变量覆盖
- 类型安全的配置结构
- 配置热重载（可选）
┌──────────────────────────────────────────┐
│ Logging Architecture │
├──────────────────────────────────────────┤
│ │
│ Application Code │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ Logger Facade│ │
│ │ (pkg/logger) │ │
│ └──────┬───────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ Uber Zap │ │
│ └──────┬───────┘ │
│ │ │
│ ┌────┴────┐ │
│ ▼ ▼ │
│ Console File │
│ Output Output │
│ │
└──────────────────────────────────────────┘
特点:
- 结构化日志（JSON格式）
- 多级别日志（Debug/Info/Warn/Error/Fatal）
- 日志轮转
- 性能优化（异步写入）
- 上下文传递（trace_id）
┌─────────────────────────────────────────────────────┐
│ Database Architecture │
├─────────────────────────────────────────────────────┤
│ │
│ Application │
│ │ │
│ ▼ │
│ ┌──────────┐ ┌──────────┐ │
│ │ GORM │◄────────►│ pgx/v5 │ │
│ └────┬─────┘ └────┬─────┘ │
│ │ │ │
│ │ Connection Pool │
│ │ │ │
│ └──────────┬──────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ PostgreSQL │ │
│ │ Database │ │
│ └──────────────┘ │
│ │
│ ┌──────────────────────────────────────┐ │
│ │ Connection Pool Settings │ │
│ │ • MaxIdleConns: 10 │ │
│ │ • MaxOpenConns: 100 │ │
│ │ • MaxLifetime: 3600s │ │
│ └──────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────┘
特点:
- ORM 抽象（GORM）
- 连接池管理
- 自动重连
- 查询优化
- 事务支持
- 软删除
┌───────────────────────────────────────────┐
│ Cache Architecture │
├───────────────────────────────────────────┤
│ │
│ Service Layer │
│ │ │
│ ├─── Cache Hit? ──► Redis │
│ │ │ │
│ │ │ (miss) │
│ │ ▼ │
│ └──► Database ──► Write to Cache │
│ │
│ ┌────────────────────────────┐ │
│ │ Cache Strategies │ │
│ │ • Cache-Aside Pattern │ │
│ │ • TTL: 1 hour (default) │ │
│ │ • LRU Eviction │ │
│ └────────────────────────────┘ │
│ │
└───────────────────────────────────────────┘
特点:
- Cache-Aside 模式
- 自动过期（TTL）
- 序列化/反序列化
- 缓存穿透防护
- 缓存雪崩防护
┌────────┐
│ Client │
└───┬────┘
│ 1. HTTP Request
▼
┌───────────────┐
│ Middleware │
│ - CORS │ 2. Pre-processing
│ - Logger │
│ - Recovery │
│ - RateLimit │
└───────┬───────┘
│ 3. Route Match
▼
┌───────────────┐
│ Controller │ 4. Parameter Validation
└───────┬───────┘
│ 5. Call Service
▼
┌───────────────┐
│ Service │ 6. Business Logic
└───────┬───────┘
│ 7. Data Access
▼
┌───────────────┐
│ Repository │ 8. Database Query
└───────┬───────┘
│ 9. Return Data
▼
┌───────────────┐
│ Controller │ 10. Format Response
└───────┬───────┘
│ 11. HTTP Response
▼
┌────────┐
│ Client │
└────────┘
┌─────────────┐
│ Error │
│ Occurred │
└──────┬──────┘
│
▼
┌──────────────────────┐
│ Repository Layer │ → Return raw DB error
└──────┬───────────────┘
│
▼
┌──────────────────────┐
│ Service Layer │ → Wrap with BusinessError
│ │ → Log error details
└──────┬───────────────┘
│
▼
┌──────────────────────┐
│ Controller Layer │ → Handle BusinessError
│ │ → Format error response
└──────┬───────────────┘
│
▼
┌──────────────────────┐
│ Error Response │ → {code, message, data}
└──────────────────────┘
┌─────────────────────────────────────────────┐
│ Security Layers │
├─────────────────────────────────────────────┤
│ │
│ 1. Network Layer │
│ • HTTPS/TLS │
│ • Firewall Rules │
│ │
│ 2. Application Layer │
│ • CORS Policy │
│ • Rate Limiting │
│ • Input Validation │
│ • SQL Injection Prevention (GORM) │
│ │
│ 3. Authentication Layer (Future) │
│ • JWT/Session │
│ • OAuth2 │
│ │
│ 4. Data Layer │
│ • Password Encryption (MD5+Salt) │
│ • Sensitive Data Masking │
│ • Database Encryption │
│ │
└─────────────────────────────────────────────┘
// Current Implementation
Password = MD5(原始密码 + 随机盐值)
// Recommended for Production
Password = BCrypt(原始密码, cost=12)当前实现:
- MD5 + Salt
- 每个用户独立盐值
- 盐值存储在数据库
生产环境建议:
- 使用 bcrypt/argon2
- 更高的计算成本
- 抗彩虹表攻击
1. 索引优化
• username, email, phone: UNIQUE INDEX
• deleted_at: INDEX (软删除)
• created_at: INDEX (时间范围查询)
2. 查询优化
• 使用 EXPLAIN 分析查询计划
• 避免 SELECT *
• 使用 Limit/Offset 分页
• 批量操作使用事务
3. 连接池
• MaxIdleConns: 10
• MaxOpenConns: 100
• ConnMaxLifetime: 1h
1. 缓存策略
• 热点数据 Redis 缓存
• Cache-Aside 模式
• TTL: 1小时
2. 并发控制
• Goroutine Pool
• Context 超时控制
• 优雅关闭
3. 响应优化
• GZIP 压缩
• JSON 序列化优化 (sonic)
• 响应流式输出
| 指标 | 目标值 | 说明 |
|---|---|---|
| API 响应时间 | < 100ms | P95 |
| 数据库查询时间 | < 50ms | 平均值 |
| 并发处理能力 | 1000 req/s | 单实例 |
| 内存占用 | < 512MB | 稳定运行 |
| CPU 使用率 | < 70% | 平均值 |
┌─────────────────────────────────────────┐
│ Load Balancer (Nginx) │
└────────┬────────┬────────┬──────────────┘
│ │ │
┌────▼────┐ ┌▼────┐ ┌▼────┐
│ App 1 │ │App 2│ │App 3│
└────┬────┘ └┬────┘ └┬────┘
│ │ │
└───────┴───────┘
│
┌───────▼────────┐
│ PostgreSQL │ (Master-Slave)
│ Redis │ (Cluster)
└────────────────┘
特点:
- 无状态设计
- Session 存储在 Redis
- 数据库读写分离
- Redis 集群模式
- 增加 CPU/内存资源
- 优化数据库配置
- 使用 SSD 存储
- 增加连接池大小
┌─────────────────────────────────────────┐
│ Monitoring Stack │
├─────────────────────────────────────────┤
│ │
│ Application │
│ │ │
│ ├──► Metrics (Prometheus) │
│ ├──► Logs (Loki/ELK) │
│ └──► Traces (Jaeger) │
│ │
│ ┌──────────────┐ │
│ │ Grafana │ ← Visualization │
│ └──────────────┘ │
│ │
│ ┌──────────────┐ │
│ │ AlertManager │ ← Alerting │
│ └──────────────┘ │
│ │
└─────────────────────────────────────────┘
- HTTP 请求数/成功率
- 响应时间分布
- 错误率
- Goroutine 数量
- 内存/CPU 使用率
- 连接数
- 查询耗时
- 慢查询数量
- 事务数量
- 命中率
- 键数量
- 内存使用
┌────────────────────────────────────────────────────┐
│ Production │
├────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ │
│ │ Gateway │ (TLS Termination) │
│ └──────┬───────┘ │
│ │ │
│ ┌──────▼───────┐ │
│ │ Load Balancer│ │
│ └──────┬───────┘ │
│ │ │
│ ┌────┴─────┐ │
│ │ │ │
│ ┌─▼──┐ ┌─▼──┐ │
│ │App1│ │App2│ (Kubernetes Pods) │
│ └─┬──┘ └─┬──┘ │
│ │ │ │
│ └────┬────┘ │
│ │ │
│ ┌──────▼─────────┐ ┌──────────────┐ │
│ │ PostgreSQL │ │ Redis │ │
│ │ (HA Cluster) │ │ (Cluster) │ │
│ └────────────────┘ └──────────────┘ │
│ │
└────────────────────────────────────────────────────┘
- Docker 镜像构建
- 多阶段构建优化
- Kubernetes Deployment
- Service Mesh (可选)
- ConfigMap/Secret 管理
| 技术 | 选择理由 |
|---|---|
| Go 1.24 | 最新稳定版，性能优秀，并发模型简单 |
| Gin | 高性能 Web 框架，生态成熟，文档完善 |
| GORM | 功能强大的 ORM，支持多种数据库 |
| PostgreSQL | 功能强大，支持复杂查询，数据完整性好 |
| Redis | 高性能缓存，丰富的数据结构 |
| Zap | 高性能结构化日志库 |
| Viper | 灵活的配置管理 |
- 添加 JWT 认证
- 实现 RBAC 权限控制
- 添加 Swagger API 文档
- 完善单元测试和集成测试
- 添加性能监控
- 实现分布式追踪
- 添加消息队列支持
- 实现微服务架构
- 添加 GraphQL 支持
- 实现数据库读写分离
- 实现服务网格
- 添加 gRPC 支持
- 实现多租户架构
- 添加机器学习功能
- 实现边缘计算支持
文档版本: v2.0.0
最后更新: 2025-11-20
维护者: Development Team