Skip to content

架构设计 ​

MengStack 采用分层架构,基于 Go 1.26 + Gin + GORM + uber/fx 构建。本文档基于实际源码介绍系统的架构设计。

总体架构 ​

┌─────────────────────────────────────────────────┐
│                    客户端                        │
│         Web / Admin / Mobile / 第三方            │
└──────────────────┬──────────────────────────────┘
                   │ HTTP / WebSocket
┌──────────────────▼──────────────────────────────┐
│              Gin Engine (中间件链)                │
│  RequestID → Logger → Security → CORS → i18n    │
│  → RateLimit → BodyLimit → Recovery             │
├─────────────────────────────────────────────────┤
│              路由层 (interfaces)                  │
│  核心模块路由 + 插件沙箱路由                       │
├─────────────────────────────────────────────────┤
│              应用层 (application)                 │
│  Service 编排、DTO 转换、事件发布                   │
├─────────────────────────────────────────────────┤
│              领域层 (domain)                      │
│  Entity、Repository 接口、领域事件                  │
├─────────────────────────────────────────────────┤
│              基础设施层 (infrastructure)           │
│  GORM Repository、Redis Cache、外部服务            │
├─────────────────────────────────────────────────┤
│  PostgreSQL 16  │  Redis 7  │  文件存储            │
└─────────────────────────────────────────────────┘

Monorepo 结构 ​

mengstack/
├── api/                 → 后端 API(Go/Gin)
│   ├── cmd/server/      → 入口 main.go
│   ├── configs/         → 配置文件
│   ├── internal/
│   │   ├── app/         → 启动层(DI、中间件、迁移、健康检查)
│   │   ├── config/      → 配置加载(Viper)
│   │   ├── kernel/      → 内核(通用能力)
│   │   ├── logger/      → 日志(Zap)
│   │   ├── modules/     → 业务模块
│   │   └── testutil/    → 测试工具
│   ├── migrations/      → 核心数据库迁移
│   ├── Dockerfile
│   ├── Makefile
│   └── go.mod
├── admin/               → 管理后台(开发中)
├── web/                 → Web 客户端(开发中)
├── docker-compose.yml   → 一键部署
└── .env.example

内核(kernel) ​

内核提供框架级通用能力,位于 internal/kernel/:

包说明
cacheRedis 缓存封装
dbutil数据库工具函数
errors统一错误定义(AppError + HTTP 状态码映射)
eventbus异步事件总线(1024 队列,4 Worker)
i18n国际化(中文内置)
idSnowflake ID 生成器
jobs定时任务调度(gocron v2)
modelBaseModel 基类、Tenant 实体
plugin插件接口定义 + 沙箱隔离
response统一 JSON 响应格式
storage文件存储抽象(本地 / S3)
tenant多租户解析器(X-Tenant-ID)
testutil测试工具(Mock、Fixture)
websocketWebSocket Hub(16 分片,按用户路由)

模块四层架构 ​

每个业务模块遵循统一的四层结构,以 auth 模块为例:

internal/modules/auth/
├── domain/              → 领域层
│   ├── user.go          → User 实体定义
│   ├── dto.go           → 领域 DTO
│   └── repository.go    → Repository 接口
├── infrastructure/      → 基础设施层
│   ├── user_repo.go     → GORM Repository 实现
│   └── migrate.go       → 模块数据迁移
├── application/         → 应用层
│   ├── service.go       → 业务逻辑编排
│   └── jwt.go           → JWT Token 管理
└── interfaces/          → 接口层
    ├── handler.go       → HTTP Handler
    ├── dto.go           → 请求/响应 DTO
    └── routes.go        → 路由注册 + fx.Module 定义

数据流向:Handler → Service → Repository → Database

依赖方向:interfaces → application → domain ← infrastructure

依赖注入 ​

使用 uber-go/fx 进行依赖注入,在 internal/app/app.go 中组装:

go
func NewApp() *fx.App {
    return fx.New(
        fx.Provide(
            func() (*config.Config, error) { return config.Load() },
            func(cfg *config.Config) (*zap.Logger, error) { return logger.New(cfg.Log) },
        ),
        database.Module,     // PostgreSQL 连接
        cache.Module,        // Redis 连接
        authinterfaces.Module,
        rbacinterfaces.Module,
        orginterfaces.Module,
        // ... 其他模块
        Module,              // 核心 Engine + Server
    )
}

每个模块通过 fx.Module() 注册自己的 Provide/Invoke,框架自动解析依赖图。

插件系统 ​

插件实现 plugin.Plugin 接口,与核心模块共享四层架构:

go
type Plugin interface {
    Metadata() Metadata           // 名称、版本、描述
    Permissions() Permissions     // 声明权限(路由、事件、存储)
    FxOption() fx.Option          // 依赖注入
    SetupRoutes(engine *gin.Engine, authMW gin.HandlerFunc,
        tenantResolver tenant.Resolver,
        requirePerm RequirePermissionFunc)  // 路由注册
    Init() error                  // 启动钩子
    MigrationsFS() fs.FS          // 数据库迁移文件
}

插件通过沙箱(Sandbox)运行,框架在启动时校验插件声明的路由和权限。

多租户 ​

基于请求头 X-Tenant-ID 的多租户隔离:

  • tenant.Resolver 从请求头/查询参数解析租户 ID
  • middleware.MultiTenant() 自动注入租户过滤条件
  • 所有模块的 Repository 查询自动带 tenant_id 条件
  • BaseModel 包含 TenantID 字段(UUID 类型)

中间件链 ​

请求经过以下中间件(按顺序):

中间件说明
RequestID生成请求追踪 ID
RequestLogger请求日志(Zap)
SecurityHeaders安全响应头
CharsetUTF8字符集
CORS跨域配置
AcceptLanguage语言协商(i18n)
RateLimitRedisRedis 限流
BodyLimit请求体大小限制(10MB)
RecoveryPanic 恢复

启动流程 ​

服务启动时按顺序执行:

  1. 加载配置(Viper,环境变量 > 配置文件)
  2. 初始化日志(Zap)
  3. 连接 PostgreSQL + Redis
  4. 执行核心数据库迁移
  5. 执行插件数据库迁移
  6. RBAC 权限种子数据
  7. 初始化所有插件
  8. 启动事件总线 Worker(4 个)
  9. 启动定时任务调度器
  10. 启动 HTTP Server

统一响应格式 ​

json
{
    "code": 0,
    "message": "success",
    "data": { ... },
    "trace_id": "abc123"
}
  • code: 0 表示成功,-1 表示失败
  • trace_id 用于日志追踪
  • 错误时 HTTP 状态码由 AppError 决定

技术栈 ​

层级技术
语言Go 1.26
Web 框架Gin
ORMGORM + PostgreSQL 16
缓存go-redis + Redis 7
依赖注入uber-go/fx
配置Viper
日志Zap
认证golang-jwt(Access + Refresh Token)
定时任务gocron v2
ID 生成Snowflake
API 文档Swagger (swag)

Released under the Apache 2.0 License.