team/tyapi-server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
03e615a8fdda0150a23ca929151d441475bd4978
tyapi-server/COMPLETE_ARCHITECTURE_PLAN.md

812 lines
24 KiB
Markdown
Raw Normal View History

Initial commit: Basic project structure and dependencies
2025-06-30 19:21:56 +08:00
# 🏗️ 2025 年最佳 Gin Web 架构完整实施计划
## 📋 项目概述
构建一个基于 Clean Architecture + DDD 的高性能、模块化 Gin Web 应用架构，支持快速开发、易维护、高扩展性。
## 🎯 架构目标
- ✅ **高度解耦**: 清晰的分层架构，依赖倒置
- ✅ **模块化**: 支持模块间快速复制和一键接入
- ✅ **高性能**: 优化的并发处理和自动缓存策略
- ✅ **易测试**: 完整的单元测试和集成测试
- ✅ **易维护**: 标准化的代码结构和文档
- ✅ **可扩展**: 支持微服务演进
- ✅ **生产就绪**: 完整的安全、监控、容错机制
## 📁 完整项目目录结构
```
tyapi-server-gin/
├── cmd/
│ └── api/
│ └── main.go # 应用程序入口
├── internal/
│ ├── config/ # 全局配置
│ │ ├── config.go # 配置结构体
│ │ ├── database.go # 数据库配置
│ │ ├── server.go # 服务器配置
│ │ └── loader.go # 配置加载器
│ ├── container/ # 依赖注入容器
│ │ ├── container.go # FX容器
│ │ ├── providers.go # 全局依赖提供者
│ │ └── module_registry.go # 模块注册器
│ ├── shared/ # 共享基础设施
│ │ ├── database/
│ │ │ ├── connection.go # 数据库连接
│ │ │ ├── base_repository.go # 通用仓储基类
│ │ │ └── pool_manager.go # 连接池管理器
│ │ ├── cache/
│ │ │ ├── redis.go # Redis缓存实现
│ │ │ ├── cache_wrapper.go # 查询缓存包装器
│ │ │ └── cache_manager.go # 缓存管理器
│ │ ├── logger/
│ │ │ └── logger.go # 结构化日志
│ │ ├── middleware/ # 共享中间件
│ │ │ ├── auth.go # 简单认证
│ │ │ ├── cors.go # 跨域处理
│ │ │ ├── logger.go # 日志中间件
│ │ │ ├── recovery.go # 异常恢复
│ │ │ └── security.go # 安全中间件栈
│ │ ├── events/ # 事件总线
│ │ │ ├── event_bus.go
│ │ │ └── event_handler.go
│ │ ├── saga/ # 分布式事务
│ │ │ ├── saga.go
│ │ │ └── saga_executor.go
│ │ ├── metrics/ # 指标收集
│ │ │ ├── simple_metrics.go
│ │ │ └── business_metrics.go
│ │ ├── tracing/ # 链路追踪
│ │ │ └── simple_tracer.go
│ │ ├── resilience/ # 容错机制
│ │ │ ├── circuit_breaker.go
│ │ │ └── retry.go
│ │ ├── hooks/ # 钩子系统
│ │ │ └── hook_system.go
│ │ ├── health/ # 健康检查
│ │ │ └── health_checker.go
│ │ └── interfaces/
│ │ └── module.go # 模块接口定义
│ └── domains/ # 业务域
│ ├── user/ # 用户域
│ │ ├── entities/
│ │ │ ├── user.go
│ │ │ ├── profile.go
│ │ │ └── auth_token.go
│ │ ├── repositories/
│ │ │ ├── user_repository.go # 接口
│ │ │ └── user_repository_impl.go # 实现
│ │ ├── services/
│ │ │ ├── user_service.go # 接口
│ │ │ ├── user_service_impl.go # 实现
│ │ │ └── auth_service.go
│ │ ├── dto/
│ │ │ ├── user_dto.go
│ │ │ └── auth_dto.go
│ │ ├── handlers/
│ │ │ ├── user_handler.go
│ │ │ └── auth_handler.go
│ │ ├── routes/
│ │ │ └── user_routes.go
│ │ ├── validators/
│ │ │ └── user_validator.go
│ │ ├── migrations/
│ │ │ └── 001_create_users_table.sql
│ │ ├── events/
│ │ │ └── user_events.go
│ │ └── module.go # 模块定义
│ ├── product/ # 产品域
│ │ ├── entities/
│ │ │ ├── product.go
│ │ │ ├── category.go
│ │ │ └── inventory.go
│ │ ├── repositories/
│ │ │ ├── product_repository.go
│ │ │ ├── product_repository_impl.go
│ │ │ └── category_repository.go
│ │ ├── services/
│ │ │ ├── product_service.go
│ │ │ ├── product_service_impl.go
│ │ │ └── inventory_service.go
│ │ ├── dto/
│ │ │ ├── product_dto.go
│ │ │ └── inventory_dto.go
│ │ ├── handlers/
│ │ │ ├── product_handler.go
│ │ │ └── category_handler.go
│ │ ├── routes/
│ │ │ └── product_routes.go
│ │ ├── validators/
│ │ │ └── product_validator.go
│ │ ├── migrations/
│ │ │ └── 002_create_products_table.sql
│ │ ├── events/
│ │ │ └── product_events.go
│ │ └── module.go
│ ├── finance/ # 财务域
│ │ ├── entities/
│ │ │ ├── order.go
│ │ │ ├── payment.go
│ │ │ └── invoice.go
│ │ ├── repositories/
│ │ │ ├── order_repository.go
│ │ │ ├── order_repository_impl.go
│ │ │ └── payment_repository.go
│ │ ├── services/
│ │ │ ├── order_service.go
│ │ │ ├── order_service_impl.go
│ │ │ └── payment_service.go
│ │ ├── dto/
│ │ │ ├── order_dto.go
│ │ │ └── payment_dto.go
│ │ ├── handlers/
│ │ │ ├── order_handler.go
│ │ │ └── payment_handler.go
│ │ ├── routes/
│ │ │ └── finance_routes.go
│ │ ├── validators/
│ │ │ └── order_validator.go
│ │ ├── migrations/
│ │ │ └── 003_create_orders_table.sql
│ │ ├── events/
│ │ │ └── finance_events.go
│ │ └── module.go
│ └── analytics/ # 数据业务域
│ ├── entities/
│ │ ├── report.go
│ │ ├── metric.go
│ │ └── dashboard.go
│ ├── repositories/
│ │ ├── analytics_repository.go
│ │ └── analytics_repository_impl.go
│ ├── services/
│ │ ├── analytics_service.go
│ │ ├── analytics_service_impl.go
│ │ └── report_service.go
│ ├── dto/
│ │ ├── report_dto.go
│ │ └── metric_dto.go
│ ├── handlers/
│ │ ├── analytics_handler.go
│ │ └── report_handler.go
│ ├── routes/
│ │ └── analytics_routes.go
│ ├── validators/
│ │ └── report_validator.go
│ ├── migrations/
│ │ └── 004_create_analytics_table.sql
│ ├── events/
│ │ └── analytics_events.go
│ └── module.go
├── pkg/ # 公共工具包
│ ├── utils/
│ │ ├── converter.go # 类型转换
│ │ ├── validator.go # 验证工具
│ │ └── response.go # 响应工具
│ ├── constants/
│ │ ├── errors.go # 错误常量
│ │ └── status.go # 状态常量
│ └── errors/
│ └── errors.go # 自定义错误
├── scripts/ # 脚本工具
│ ├── generate-domain.sh # 域生成器
│ ├── generate-module.sh # 模块生成器
│ ├── register-module.sh # 模块注册器
│ ├── build.sh # 构建脚本
│ └── migrate.sh # 数据库迁移脚本
├── deployments/ # 部署配置
│ ├── docker/
│ │ ├── Dockerfile # 多阶段构建
│ │ └── docker-compose.yml # 生产环境
│ └── docker-compose.dev.yml # 开发环境
├── docs/ # 文档
│ ├── DEVELOPMENT.md # 开发指南
│ ├── DEPLOYMENT.md # 部署指南
│ └── API.md # API使用说明
├── test/ # 测试
│ ├── integration/ # 集成测试
│ └── fixtures/ # 测试数据
├── .env.example # 环境变量示例
├── .gitignore
├── Makefile # 构建命令
├── go.mod
└── go.sum
```
## 🔧 技术栈选择
### 核心框架
- **Web 框架**: Gin v1.10+
- **ORM**: GORM v2 (支持泛型)
- **依赖注入**: Uber FX
- **配置管理**: Viper
- **验证**: go-playground/validator v10
### 数据存储
- **主数据库**: PostgreSQL 15+
- **缓存**: Redis 7+ (自动缓存数据库查询)
### 监控和日志
- **日志**: Zap + OpenTelemetry
- **指标收集**: 简化的业务指标系统
- **链路追踪**: 轻量级请求追踪
- **健康检查**: 数据库和 Redis 状态监控
### 开发工具
- **代码生成**: Wire (可选)
- **测试**: Testify + Testcontainers
- **Linting**: golangci-lint
## 📅 分步骤实施计划
### 🚀 阶段 1: 基础架构搭建 (预计 2-3 小时)
#### Step 1.1: 项目初始化
- [ ] 初始化 Go 模块
- [ ] 创建基础目录结构
- [ ] 配置.gitignore 和基础文件
- [ ] 安装核心依赖
#### Step 1.2: 配置系统
- [ ] 实现配置加载器 (Viper)
- [ ] 创建环境变量管理
- [ ] 设置不同环境配置 (dev/staging/prod)
#### Step 1.3: 日志系统
- [ ] 集成 Zap 日志库
- [ ] 配置结构化日志
- [ ] 实现日志中间件
#### Step 1.4: 数据库连接
- [ ] 配置 PostgreSQL 连接
- [ ] 实现连接池管理
- [ ] 集成 GORM
- [ ] 创建数据库迁移机制
### 🏗️ 阶段 2: 架构核心层 (预计 3-4 小时)
#### Step 2.1: 领域层设计
- [ ] 定义基础实体接口
- [ ] 创建用户实体示例
- [ ] 实现仓储接口定义
- [ ] 设计业务服务接口
#### Step 2.2: 基础设施层
- [ ] 实现通用仓储基类 (支持自动缓存)
- [ ] 创建缓存包装器和管理器
- [ ] 创建用户仓储实现 (集成缓存)
- [ ] 集成 Redis 缓存
- [ ] 实现监控指标收集
#### Step 2.3: 应用层
- [ ] 定义 DTO 结构
- [ ] 实现业务服务
- [ ] 创建用例处理器
- [ ] 实现数据转换器
#### Step 2.4: 依赖注入
- [ ] 配置 FX 容器
- [ ] 实现依赖提供者
- [ ] 创建模块注册机制
### 🌐 阶段 3: Web 层实现 (预计 2-3 小时)
#### Step 3.1: HTTP 层基础
- [ ] 创建 Gin 路由器
- [ ] 实现基础中间件 (CORS, Recovery, Logger)
- [ ] 配置路由组织结构
#### Step 3.2: 处理器实现
- [ ] 实现用户 CRUD 处理器
- [ ] 创建健康检查处理器
- [ ] 实现统一响应格式
- [ ] 添加请求验证
#### Step 3.3: 中间件系统
- [ ] 实现简单认证中间件
- [ ] 创建限流中间件
- [ ] 添加请求 ID 追踪
- [ ] 实现错误处理中间件
- [ ] 集成安全头中间件
### 🔧 阶段 4: 高级特性实现 (预计 3-4 小时)
#### Step 4.1: 自动缓存系统
- [ ] 实现缓存包装器
- [ ] 集成查询结果自动缓存
- [ ] 实现智能缓存失效策略
- [ ] 添加缓存穿透防护
#### Step 4.2: 跨域事务处理
- [ ] 实现 Saga 模式事务协调器
- [ ] 创建事件驱动架构
- [ ] 实现补偿机制
- [ ] 添加视图聚合模式
#### Step 4.3: 可观测性
- [ ] 集成简单指标收集
- [ ] 实现链路追踪
- [ ] 添加业务指标监控
- [ ] 创建性能监控面板
#### Step 4.4: 容错机制
- [ ] 实现简化熔断器
- [ ] 添加智能重试机制
- [ ] 集成钩子系统
- [ ] 实现优雅降级
### 🚀 阶段 5: 部署和工具 (预计 2-3 小时)
#### Step 5.1: 容器化 (Docker Compose)
- [ ] 创建多阶段 Dockerfile
- [ ] 配置生产环境 docker-compose.yml
- [ ] 配置开发环境 docker-compose.dev.yml
- [ ] 集成 PostgreSQL 和 Redis 容器
- [ ] 实现健康检查
- [ ] 配置数据卷持久化
#### Step 5.2: 开发工具
- [ ] 创建 Makefile 命令
- [ ] 实现模块生成器脚本
- [ ] 配置代码质量检查
- [ ] 创建数据库迁移脚本
#### Step 5.3: 生产就绪
- [ ] 实现优雅关闭
- [ ] 配置信号处理
- [ ] 添加安全性增强
- [ ] 创建监控和告警
## 🔄 自动缓存架构设计
### 缓存包装器实现
```go
// 缓存包装器接口
type CacheableRepository[T any] interface {
GetWithCache(ctx context.Context, key string, finder func() (*T, error)) (*T, error)
ListWithCache(ctx context.Context, key string, finder func() ([]*T, error)) ([]*T, error)
InvalidateCache(ctx context.Context, pattern string) error
}
// 自动缓存的仓储实现
type UserRepository struct {
db *gorm.DB
cache cache.Manager
}
func (r *UserRepository) GetByID(ctx context.Context, id uint) (*User, error) {
cacheKey := fmt.Sprintf("user:id:%d", id)
return r.cache.GetWithCache(ctx, cacheKey, func() (*User, error) {
var user User
err := r.db.First(&user, id).Error
return &user, err
})
}
```
### 缓存策略
- **自动查询缓存**: 数据库查询结果自动缓存
- **智能缓存失效**: 基于数据变更的缓存失效
- **多级缓存架构**: 内存 + Redis 组合
- **缓存穿透防护**: 空结果缓存和布隆过滤器
- **缓存预热**: 启动时预加载热点数据
## 🔄 跨域事务处理
### Saga 模式实现
```go
// Saga事务协调器
type Saga struct {
ID string
Steps []SagaStep
Data interface{}
Status SagaStatus
executor SagaExecutor
}
type SagaStep struct {
Name string
Action func(ctx context.Context, data interface{}) error
Compensate func(ctx context.Context, data interface{}) error
}
```
### 跨域查询处理
#### 视图聚合模式
```go
// OrderView 订单视图聚合
type OrderView struct {
// 订单基本信息 (来自finance域)
OrderID uint `json:"order_id"`
Amount float64 `json:"amount"`
Status string `json:"status"`
CreatedAt time.Time `json:"created_at"`
// 用户信息 (来自user域)
UserID uint `json:"user_id"`
UserName string `json:"user_name"`
UserEmail string `json:"user_email"`
// 产品信息 (来自product域)
ProductID uint `json:"product_id"`
ProductName string `json:"product_name"`
ProductPrice float64 `json:"product_price"`
}
```
## 🔄 模块化特性
### 快速添加新模块
```bash
# 使用脚本快速生成新模块
make add-domain name=inventory
# 自动生成：
# - 完整的目录结构和代码模板
# - 自动缓存支持的仓储层
# - 标准化的API接口
# - 依赖注入自动配置
# - 路由自动注册
# 立即可用的API：
# GET /api/v1/inventorys
# POST /api/v1/inventorys
# GET /api/v1/inventorys/:id
# PUT /api/v1/inventorys/:id
# DELETE /api/v1/inventorys/:id
# GET /api/v1/inventorys/search
```
### 模块间解耦
- 通过接口定义模块边界
- 使用事件驱动通信
- 独立的数据模型
- 可插拔的模块系统
## 🐳 Docker Compose 部署架构
### 生产环境配置
```yaml
# docker-compose.yml
version: "3.8"
services:
api:
build: .
ports:
- "8080:8080"
environment:
- ENV=production
- DB_HOST=postgres
- REDIS_HOST=redis
depends_on:
- postgres
- redis
postgres:
image: postgres:15-alpine
environment:
POSTGRES_DB: tyapi
POSTGRES_USER: tyapi
POSTGRES_PASSWORD: ${DB_PASSWORD}
volumes:
- postgres_data:/var/lib/postgresql/data
ports:
- "5432:5432"
redis:
image: redis:7-alpine
volumes:
- redis_data:/data
ports:
- "6379:6379"
volumes:
postgres_data:
redis_data:
```
### 多阶段 Dockerfile
```dockerfile
# Build stage
FROM golang:1.23.4-alpine AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -o main cmd/api/main.go
# Development stage
FROM golang:1.23.4-alpine AS development
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
CMD ["go", "run", "cmd/api/main.go"]
# Production stage
FROM alpine:latest AS production
RUN apk --no-cache add ca-certificates
WORKDIR /root/
COPY --from=builder /app/main .
CMD ["./main"]
```
## 🛡️ 安全和监控特性
### 轻量安全中间件栈
```go
// SecurityMiddleware 安全中间件集合
type SecurityMiddleware struct {
jwtSecret string
rateLimiter *rate.Limiter
trustedIPs map[string]bool
}
// Chain 安全中间件链
func (s *SecurityMiddleware) Chain() []gin.HandlerFunc {
return []gin.HandlerFunc{
s.RateLimit(),
s.SecurityHeaders(),
s.IPWhitelist(),
s.RequestID(),
}
}
```
### 简化的可观测性
```go
// SimpleMetrics 简化的指标收集器
type SimpleMetrics struct {
counters map[string]int64
gauges map[string]float64
mu sync.RWMutex
}
// BusinessMetrics 业务指标
type BusinessMetrics struct {
metrics *SimpleMetrics
}
func (b *BusinessMetrics) RecordOrderCreated(amount float64) {
b.metrics.IncCounter("orders.created.count", 1)
b.metrics.IncCounter("orders.created.amount", int64(amount*100))
}
```
### 容错机制
```go
// SimpleCircuitBreaker 简化的熔断器
type SimpleCircuitBreaker struct {
maxFailures int
resetTimeout time.Duration
state CircuitState
}
// SimpleRetry 智能重试机制
func SimpleRetry(ctx context.Context, config RetryConfig, fn func() error) error {
// 指数退避重试实现
}
```
### 健康检查
```go
// HealthChecker 健康检查器
type HealthChecker struct {
db *gorm.DB
redis *redis.Client
}
type HealthStatus struct {
Status string `json:"status"`
Timestamp time.Time `json:"timestamp"`
Checks map[string]CheckResult `json:"checks"`
}
```
## 📊 性能优化策略
### 数据库优化
- 连接池动态调优
- 查询结果自动缓存
- 索引策略优化
- 批量操作优化
### 缓存策略
- **自动查询缓存**: 透明的查询结果缓存
- **智能失效**: 数据变更时自动清理相关缓存
- **多级架构**: L1(内存) + L2(Redis) 缓存
- **穿透防护**: 空值缓存和布隆过滤器
### 并发优化
- Goroutine 池管理
- Context 超时控制
- 异步任务处理
- 批量数据加载
## 🔌 扩展性设计
### 钩子系统
```go
// SimpleHookSystem 简化的钩子系统
type SimpleHookSystem struct {
hooks map[string][]HookFunc
}
// 使用示例
hookSystem.Register("user.created", func(ctx context.Context, data interface{}) error {
user := data.(*entities.User)
return sendWelcomeEmail(user.Email)
})
```
### 事件驱动架构
```go
// 跨域事件通信
type UserCreatedEvent struct {
UserID uint `json:"user_id"`
Email string `json:"email"`
CreatedAt time.Time `json:"created_at"`
}
// 产品域监听用户创建事件
func (s *ProductService) OnUserCreated(event UserCreatedEvent) error {
return s.CreateUserRecommendations(event.UserID)
}
```
## 🛠️ 开发工具
### Makefile 快速命令
```makefile
# 添加新的业务域
add-domain:
@./scripts/generate-domain.sh $(name)
@./scripts/register-module.sh $(name)
# 开发环境运行
run-dev:
@go run cmd/api/main.go
# Docker开发环境
docker-dev:
@docker-compose -f docker-compose.dev.yml up -d
# 数据库迁移
migrate:
@go run cmd/migrate/main.go
```
### 域生成器脚本
```bash
#!/bin/bash
# scripts/generate-domain.sh
# 自动生成：
# - 实体定义和表结构
# - 仓储接口和实现(支持自动缓存)
# - 业务服务层
# - HTTP处理器
# - DTO和验证器
# - 路由注册
# - 模块定义和依赖注入
```
## 🎯 预期收益
1. **开发效率**: 模块生成器将新功能开发时间减少 70%
2. **代码质量**: 统一的架构模式和代码规范
3. **维护性**: 清晰的分层和依赖关系
4. **可测试性**: 依赖注入支持 100%的单元测试覆盖
5. **性能**: 自动缓存和并发优化策略
6. **扩展性**: 支持平滑的微服务演进
7. **稳定性**: 完整的容错和监控机制
8. **安全性**: 轻量但完备的安全防护
## ✅ 架构特色总结
### 🎯 核心优势
1. **自动缓存系统**:
- 数据库查询自动缓存，性能提升显著
- 智能缓存失效策略
- 多级缓存架构(内存 + Redis)
2. **模块化设计**:
- Clean Architecture + DDD 设计
- 5 分钟快速生成完整业务域
- 依赖注入容器(Uber FX)
3. **跨域事务处理**:
- Saga 模式处理分布式事务
- 视图聚合解决跨域查询
- 事件驱动架构
4. **Docker Compose 部署**:
- 开发和生产环境分离
- 多阶段构建优化
- 数据持久化和网络隔离
5. **生产就绪特性**:
- 轻量安全中间件栈
- 简化的可观测性
- 容错和稳定性保障
- 健康检查和监控
### 📋 技术决策
✅ **数据库**: PostgreSQL 15+ 主库 + Redis 7+ 缓存
✅ **缓存策略**: 自动查询缓存 + 智能失效
✅ **部署方式**: Docker Compose(生产/开发分离)
✅ **开发工具**: 移除热重载，保留核心工具
✅ **认证方案**: 简化 JWT 认证，无复杂 RBAC
✅ **测试策略**: 手动编写，无自动生成
✅ **文档方案**: 手动维护，无自动 API 文档
## 🚀 开始实施
架构设计已完成！总预计实施时间：**12-15 小时**，分 5 个阶段完成。
### 实施顺序：
1. **基础架构搭建** (2-3 小时)
2. **架构核心层** (3-4 小时)
3. **Web 层实现** (2-3 小时)
4. **高级特性** (3-4 小时)
5. **部署和工具** (2-3 小时)
### 关键特性：
- 🚀 **5 分钟生成新业务域** - 完整的模块化开发
- ⚡ **自动缓存系统** - 透明的性能优化
- 🔄 **跨域事务处理** - 企业级数据一致性
- 🐳 **容器化部署** - 生产就绪的部署方案
- 🛡️ **安全和监控** - 轻量但完备的保障体系
**准备好开始实施了吗？** 🎯
Reference in New Issue Copy Permalink