# MengStack API

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

## 技术栈

| 组件 | 技术选型 | 说明 |
|------|---------|------|
| Web 框架 | [Gin](https://github.com/gin-gonic/gin) | 高性能 HTTP 路由 |
| ORM | [GORM](https://gorm.io) | PostgreSQL 数据访问 |
| 缓存 | [go-redis](https://github.com/redis/go-redis) | Redis 客户端 |
| 依赖注入 | [uber/fx](https://github.com/uber-go/fx) | 生命周期管理 |
| 配置管理 | [Viper](https://github.com/spf13/viper) | 分层配置 + 环境变量 |
| 日志 | [Zap](https://github.com/uber-go/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（推荐）

```bash
# 克隆项目
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
```

### 方式二：本地开发

```bash
# 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_` 前缀 — 最高优先级，适合存放密码等敏感信息

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

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

## 常用命令

```bash
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