MengStack Core

MengStack（软盟开发框架）是一个面向多租户 SaaS 应用的 Go 通用底座。把账号、权限、租户、组织、审计、配置、消息、插件等所有 Web 应用共享的能力一次性做好，让你只专注于业务逻辑。

为什么选择 MengStack

• 多租户内建 — 共享表 + tenant_id 显式过滤，可选 Schema 隔离与 PG 行级安全（RLS）兜底
• 插件架构 — 通过扩展点和 .mengplugin 包格式扩展功能，不改动内核代码
• 四层分层 — domain → application → infrastructure → interfaces，职责清晰、可测试
• 编译期依赖注入 — 基于 Uber fx，依赖错误在编译时暴露，不是运行时
• 安全默认 — JWT 双 Token、RBAC 权限、bcrypt 密码、参数化查询、XSS 过滤、三级限流
• 可观测性 — Zap 结构化日志（含 trace_id / tenant_id）、健康检查、就绪探针

快速开始

前置条件

• Go 1.23+
• PostgreSQL 16+
• Redis 7+

1. 克隆项目

git clone https://github.com/mengstack/core.git
cd core

2. 配置环境

cp .env.example .env
# 编辑 .env，填入数据库密码和 JWT 密钥

3. 启动依赖服务

docker-compose up -d postgres redis

4. 启动服务

# 安装依赖
go mod download

# 运行迁移 + 启动
make run

服务启动后：

端点	地址
API	http://localhost:2222
健康检查	http://localhost:2222/health
就绪探针	http://localhost:2222/readyz
Swagger 文档	http://localhost:2222/swagger/index.html

或者用 Docker 一键启动

cp .env.example .env
docker-compose up -d
docker-compose logs -f api

项目结构

.
├── cmd/
│   ├── server/          # 主服务入口
│   ├── migrate/         # 数据库迁移工具
│   └── smrm/            # CLI 脚手架工具
├── internal/
│   ├── app/             # 应用基础设施
│   │   ├── cache/       #   Redis 连接
│   │   ├── database/    #   PostgreSQL 连接
│   │   ├── health/      #   健康检查 & 就绪探针
│   │   ├── middleware/  #   请求 ID、认证、多租户、i18n
│   │   ├── migrate/     #   迁移执行器
│   │   └── upgrade/     #   在线升级预留
│   ├── config/          # Viper 配置加载
│   ├── kernel/          # ★ 内核（开源部分）
│   │   ├── errors/      #   统一错误码
│   │   ├── response/    #   统一响应格式
│   │   ├── tenant/      #   多租户抽象
│   │   ├── model/       #   公共基础实体
│   │   ├── plugin/      #   插件接口 & 沙箱
│   │   ├── eventbus/    #   事件总线
│   │   ├── storage/     #   存储抽象
│   │   ├── cache/       #   缓存工具
│   │   ├── jobs/        #   后台任务调度
│   │   ├── i18n/        #   国际化框架
│   │   └── websocket/   #   WebSocket 推送
│   ├── logger/          # Zap 结构化日志
│   └── modules/         # 业务模块
│       ├── auth/        #   认证（注册/登录/刷新）
│       ├── rbac/        #   角色权限
│       ├── org/         #   组织架构
│       ├── audit/       #   审计日志
│       ├── settings/    #   配置管理
│       ├── notification/#   消息通知
│       └── example/     #   示例插件
├── migrations/          # 核心数据库迁移脚本
├── configs/             # 分层配置模板
├── docs/                # Swagger 生成文档
├── test/                # 测试工具
├── AGENTS.md            # AI 辅助开发规范
└── Makefile             # 常用命令

核心能力

多租户

// 请求头传入租户 ID
// X-Tenant-ID: tenant-abc-123

// 框架自动解析并注入上下文
tenantID := tenant.FromContext(c.Request.Context())

支持三种隔离策略，通过配置切换：

• 共享表 + tenant_id（默认，适合大多数场景）
• Schema 隔离（高安全需求）
• 独立数据库（企业级隔离）

插件系统

每个插件是一个独立的模块，声明所需权限，运行时由沙箱强制执行：

func (p *MyPlugin) Permissions() plugin.Permissions {
    return plugin.Permissions{
        Database: []string{"my_table"},     // 只能访问声明的表
        Events:   []string{"order.created"}, // 只能发射声明的事件
        Routes:   []string{"/api/v1/orders/*"},
    }
}

插件 panic 不会影响主进程 — 沙箱通过 recover 隔离故障。

创建新插件：

go run ./cmd/smrm new module order

统一响应

{
  "code": 0,
  "message": "success",
  "data": { ... },
  "trace_id": "abc-123"
}

错误码体系：业务错误返回具体码 + 国际化消息，5xx 统一返回"服务器内部错误"，原文只进日志。

配置分层

优先级从低到高：

1. configs/config.yaml — 基础默认值
2. configs/config.{mode}.yaml — 环境覆盖（dev / prod）
3. MENGSTACK_ 环境变量 — 最高优先级

MENGSTACK_DATABASE_PASSWORD=secret
MENGSTACK_JWT_SECRET=your-jwt-key

开发规范

四层分层

层	文件	职责	禁止
Domain	model.go	实体、领域接口	import gorm/http/redis
Application	service.go	用例编排、事务	直接操作数据库
Infrastructure	repo.go	数据库/缓存实现	含业务逻辑
Interfaces	handler.go	参数校验、调 service	写业务逻辑

十条铁律

1. 内核绝不装业务语义（无 article / order / goods）
2. 依赖只能由外向内（domain 层零外部依赖）
3. 跨模块只走接口（禁止直接 import 其他模块的 repo）
4. 依赖方向单调：modules → kernel，禁止反向
5. tenantID 显式传递（禁止 context 隐式透传）
6. 统一响应格式与错误码
7. 所有数据库变更走迁移脚本
8. 禁止 SELECT *、禁止字符串拼接 SQL
9. 品牌写法统一：MengStack + 软盟开发框架
10. 插件只能通过扩展点接入，内核不依赖任何插件

规范自检

# 检查内核纯净性（禁止业务语义泄漏）
go run ./cmd/smrm check

常用命令

make build        # 编译
make run          # 启动开发服务
make test         # 运行测试
make test-cover   # 测试覆盖率
make lint         # 代码检查
make swagger      # 重新生成 Swagger 文档
make migrate      # 运行数据库迁移
make docker-up    # Docker 启动全部服务
make docker-down  # Docker 停止所有服务

演示站

• API：https://mengstackdemo.softunis.com
• Swagger：https://mengstackdemo.softunis.com/swagger/index.html

技术栈

组件	选型	说明
语言	Go 1.23+	编译为单文件，部署极简
Web 框架	Gin	高性能 HTTP 路由
ORM	GORM v2	PostgreSQL 数据访问
数据库	PostgreSQL 16	多租户原生 + 许可可闭源
缓存	Redis 7	会话 / 缓存 / 队列
依赖注入	Uber fx	编译期装配，生命周期管理
配置	Viper	分层配置 + 环境变量
日志	Zap	结构化高性能日志
认证	JWT	Access + Refresh 双 Token
迁移	golang-migrate	版本化数据库变更
API 文档	Swag	注解自动生成 Swagger

许可证

Apache License 2.0

Copyright 2026 SoftUnis（软盟）