a7d44e12f0
Some checks failed
CI / Build & Test (push) Failing after 2m49s
从 github.com/mengstack/core 修正为实际的 Gitea 仓库地址
256 lines
7.9 KiB
Markdown
256 lines
7.9 KiB
Markdown
# MengStack Core
|
||
|
||
[](https://go.dev)
|
||
[](https://www.postgresql.org)
|
||
[](https://redis.io)
|
||
[](LICENSE)
|
||
|
||
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. 克隆项目
|
||
|
||
```bash
|
||
git clone https://mengstackgit.softunis.com/softunis/mengstack-api.git
|
||
cd mengstack-api
|
||
```
|
||
|
||
### 2. 配置环境
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
# 编辑 .env，填入数据库密码和 JWT 密钥
|
||
```
|
||
|
||
### 3. 启动依赖服务
|
||
|
||
```bash
|
||
docker-compose up -d postgres redis
|
||
```
|
||
|
||
### 4. 启动服务
|
||
|
||
```bash
|
||
# 安装依赖
|
||
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 一键启动
|
||
|
||
```bash
|
||
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 # 常用命令
|
||
```
|
||
|
||
## 核心能力
|
||
|
||
### 多租户
|
||
|
||
```go
|
||
// 请求头传入租户 ID
|
||
// X-Tenant-ID: tenant-abc-123
|
||
|
||
// 框架自动解析并注入上下文
|
||
tenantID := tenant.FromContext(c.Request.Context())
|
||
```
|
||
|
||
支持三种隔离策略，通过配置切换：
|
||
- **共享表 + tenant_id**（默认，适合大多数场景）
|
||
- **Schema 隔离**（高安全需求）
|
||
- **独立数据库**（企业级隔离）
|
||
|
||
### 插件系统
|
||
|
||
每个插件是一个独立的模块，声明所需权限，运行时由沙箱强制执行：
|
||
|
||
```go
|
||
func (p *MyPlugin) Permissions() plugin.Permissions {
|
||
return plugin.Permissions{
|
||
Database: []string{"my_table"}, // 只能访问声明的表
|
||
Events: []string{"order.created"}, // 只能发射声明的事件
|
||
Routes: []string{"/api/v1/orders/*"},
|
||
}
|
||
}
|
||
```
|
||
|
||
插件 panic 不会影响主进程 — 沙箱通过 `recover` 隔离故障。
|
||
|
||
创建新插件：
|
||
|
||
```bash
|
||
go run ./cmd/smrm new module order
|
||
```
|
||
|
||
### 统一响应
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": { ... },
|
||
"trace_id": "abc-123"
|
||
}
|
||
```
|
||
|
||
错误码体系：业务错误返回具体码 + 国际化消息，5xx 统一返回"服务器内部错误"，原文只进日志。
|
||
|
||
### 配置分层
|
||
|
||
优先级从低到高：
|
||
|
||
1. `configs/config.yaml` — 基础默认值
|
||
2. `configs/config.{mode}.yaml` — 环境覆盖（dev / prod）
|
||
3. `MENGSTACK_` 环境变量 — 最高优先级
|
||
|
||
```bash
|
||
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. 插件只能通过扩展点接入，内核不依赖任何插件
|
||
|
||
### 规范自检
|
||
|
||
```bash
|
||
# 检查内核纯净性（禁止业务语义泄漏）
|
||
go run ./cmd/smrm check
|
||
```
|
||
|
||
## 常用命令
|
||
|
||
```bash
|
||
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](LICENSE)
|
||
|
||
Copyright 2026 SoftUnis（软盟）
|