Appearance
架构设计
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/:
| 包 | 说明 |
|---|---|
cache | Redis 缓存封装 |
dbutil | 数据库工具函数 |
errors | 统一错误定义(AppError + HTTP 状态码映射) |
eventbus | 异步事件总线(1024 队列,4 Worker) |
i18n | 国际化(中文内置) |
id | Snowflake ID 生成器 |
jobs | 定时任务调度(gocron v2) |
model | BaseModel 基类、Tenant 实体 |
plugin | 插件接口定义 + 沙箱隔离 |
response | 统一 JSON 响应格式 |
storage | 文件存储抽象(本地 / S3) |
tenant | 多租户解析器(X-Tenant-ID) |
testutil | 测试工具(Mock、Fixture) |
websocket | WebSocket 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从请求头/查询参数解析租户 IDmiddleware.MultiTenant()自动注入租户过滤条件- 所有模块的 Repository 查询自动带
tenant_id条件 - BaseModel 包含
TenantID字段(UUID 类型)
中间件链
请求经过以下中间件(按顺序):
| 中间件 | 说明 |
|---|---|
RequestID | 生成请求追踪 ID |
RequestLogger | 请求日志(Zap) |
SecurityHeaders | 安全响应头 |
CharsetUTF8 | 字符集 |
CORS | 跨域配置 |
AcceptLanguage | 语言协商(i18n) |
RateLimitRedis | Redis 限流 |
BodyLimit | 请求体大小限制(10MB) |
Recovery | Panic 恢复 |
启动流程
服务启动时按顺序执行:
- 加载配置(Viper,环境变量 > 配置文件)
- 初始化日志(Zap)
- 连接 PostgreSQL + Redis
- 执行核心数据库迁移
- 执行插件数据库迁移
- RBAC 权限种子数据
- 初始化所有插件
- 启动事件总线 Worker(4 个)
- 启动定时任务调度器
- 启动 HTTP Server
统一响应格式
json
{
"code": 0,
"message": "success",
"data": { ... },
"trace_id": "abc123"
}code: 0表示成功,-1表示失败trace_id用于日志追踪- 错误时 HTTP 状态码由
AppError决定
技术栈
| 层级 | 技术 |
|---|---|
| 语言 | Go 1.26 |
| Web 框架 | Gin |
| ORM | GORM + PostgreSQL 16 |
| 缓存 | go-redis + Redis 7 |
| 依赖注入 | uber-go/fx |
| 配置 | Viper |
| 日志 | Zap |
| 认证 | golang-jwt(Access + Refresh Token) |
| 定时任务 | gocron v2 |
| ID 生成 | Snowflake |
| API 文档 | Swagger (swag) |

