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