MengStack API

MengStack 是一个基于 Go 的企业级后端框架，采用清晰的分层架构和依赖注入，帮助开发者快速构建高质量的多租户 Web 应用。

技术栈

组件	技术选型	说明
Web 框架	Gin	高性能 HTTP 路由
ORM	GORM	PostgreSQL 数据访问
缓存	go-redis	Redis 客户端
依赖注入	uber/fx	生命周期管理
配置管理	Viper	分层配置 + 环境变量
日志	Zap	结构化高性能日志
认证	JWT	Access Token + Refresh Token

架构设计

三层隔离

cmd/server/        → 启动层：组装依赖，启动服务
internal/app/      → 基础设施层：数据库、缓存、中间件、健康检查
internal/modules/  → 业务模块层：按领域划分的独立模块

模块四层结构

每个业务模块遵循统一的四层架构：

modules/auth/
├── domain/          → 领域层：实体、DTO、仓储接口
├── application/     → 应用层：业务逻辑、服务实现
├── infrastructure/  → 基础设施层：仓储实现、数据库迁移
└── interfaces/      → 接口层：HTTP Handler、路由注册

依赖注入

使用 uber/fx 管理依赖，每个模块通过 fx.Provide 注册，框架自动解析依赖图。生命周期钩子（fx.Lifecycle）管理服务器启停，禁止在 Provider 中启动 goroutine。

快速开始

前置条件

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

方式一：Docker Compose（推荐）

# 克隆项目
git clone https://mengstackgit.softunis.com/softunis/mengstack-api.git
cd mengstack-api

# 复制环境变量并修改
cp .env.example .env

# 一键启动（PostgreSQL + Redis + API）
docker-compose up -d

# 查看日志
docker-compose logs -f api

方式二：本地开发

# 1. 启动 PostgreSQL 和 Redis（可用 Docker）
docker-compose up -d postgres redis

# 2. 复制并编辑配置
cp .env.example .env
# 编辑 .env 填入数据库密码等

# 3. 安装依赖
go mod download

# 4. 启动服务
make run
# 或
go run ./cmd/server

服务启动后访问 http://localhost:2222/health 验证。

项目结构

mengstack-api/
├── cmd/server/          # 应用入口
├── configs/             # 配置模板
│   ├── config.yaml      # 基础配置
│   ├── config.dev.yaml  # 开发环境覆盖
│   └── config.prod.yaml # 生产环境覆盖
├── internal/
│   ├── app/             # 基础设施
│   │   ├── cache/       # Redis 模块
│   │   ├── database/    # PostgreSQL 模块
│   │   ├── health/      # 健康检查
│   │   └── middleware/  # 请求ID、多租户中间件
│   ├── config/          # 配置加载器
│   ├── kernel/          # 核心工具（错误、响应、租户上下文）
│   ├── logger/          # Zap 日志
│   └── modules/         # 业务模块
│       └── auth/        # 认证模块（注册/登录/刷新Token）
├── migrations/          # 数据库迁移脚本
├── docs/                # Swagger 文档
├── assets/              # 静态资源（Logo 等）
├── .env.example         # 环境变量模板
├── docker-compose.yml   # 容器编排
├── Makefile             # 常用命令
└── go.mod               # Go 模块定义

配置系统

MengStack 采用三层配置覆盖机制，优先级从低到高：

1. 基础配置 configs/config.yaml — 所有环境的默认值
2. 环境覆盖 configs/config.{mode}.yaml — 按 server.mode 加载（dev/prod）
3. 环境变量 MENGSTACK_ 前缀 — 最高优先级，适合存放密码等敏感信息

# 环境变量命名规则：MENGSTACK_{Section}_{Key}
# 例如：
MENGSTACK_SERVER_PORT=8080
MENGSTACK_DATABASE_PASSWORD=your-secret
MENGSTACK_JWT_SECRET=your-jwt-secret

安全提示：永远不要将真实密码提交到 git。使用 .env 文件（已加入 .gitignore）或系统环境变量。

常用命令

make build        # 编译二进制
make run          # 启动开发服务
make test         # 运行测试
make test-cover   # 测试覆盖率报告
make lint         # 代码检查
make swagger      # 重新生成 Swagger 文档
make docker-up    # Docker 启动全部服务
make docker-down  # Docker 停止所有服务
make clean        # 清理构建产物

API 概览

认证接口

方法	路径	说明
POST	/api/v1/auth/register	用户注册
POST	/api/v1/auth/login	用户登录
POST	/api/v1/auth/refresh	刷新 Token
GET	/api/v1/auth/me	获取当前用户（需认证）
GET	/health	健康检查

多租户

所有业务接口通过 X-Tenant-ID 请求头标识租户。框架自动解析租户上下文并注入到数据库查询中。

完整 API 文档：启动服务后访问 /swagger/index.html。

添加新模块

以创建 article 模块为例：

internal/modules/article/
├── domain/
│   ├── entity.go       # Article 实体
│   ├── dto.go          # 请求/响应 DTO
│   └── repository.go   # 仓储接口
├── application/
│   └── service.go      # 业务逻辑实现
├── infrastructure/
│   ├── repository.go   # GORM 仓储实现
│   └── migrate.go      # AutoMigrate 注册
└── interfaces/
    ├── handler.go       # HTTP Handler
    └── routes.go        # 路由注册（实现 RouteGroup 接口）

1. 创建上述目录和文件
2. 在 internal/app/app.go 中添加 fx.Provide 注册新模块
3. 在 infrastructure/migrate.go 中注册 AutoMigrate
4. 框架自动发现并注册路由

开发规范

• 依赖注入：所有依赖通过 fx.Provide 注册，使用 fx.In 结构体注入
• 生命周期：服务器启停使用 fx.Lifecycle 的 OnStart/OnStop 钩子
• 错误处理：使用 kernel/errors 统一错误码
• 响应格式：使用 kernel/response 统一 JSON 响应结构
• 日志：通过 logger.L() 获取全局 Zap 实例

演示站

• API 地址：https://mengstackdemo.softunis.com
• Swagger 文档：https://mengstackdemo.softunis.com/swagger/index.html

许可证

MIT License