Add README with developer quick start guide
This commit is contained in:
MengStack Dev
parent
fbf9af32f0
commit
3ba93870dd
208
README.md
Normal file
208
README.md
Normal file
@ -0,0 +1,208 @@
|
||||
# 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
|
||||
Loading…
Reference in New Issue
Block a user