|
|
# VBase 后端架构设计文档
|
|
|
|
|
|
## 1. 概览
|
|
|
|
|
|
VBase 是一个基于 Golang 的高性能后端基础框架，旨在提供一套标准化的用户管理、作用域权限控制（Scoped RBAC）和 OAuth2 认证服务。项目采用分层架构设计，基于 `vigo` 框架构建，强调代码的可维护性、扩展性和安全性。
|
|
|
|
|
|
## 2. 技术栈
|
|
|
|
|
|
- **语言**: Golang 1.22+
|
|
|
- **Web 框架**: [vigo](https://github.com/veypi/vigo) (基于洋葱模型的高性能框架)
|
|
|
- **ORM**: GORM (支持 MySQL, PostgreSQL, SQLite 等)
|
|
|
- **配置管理**: `cfg` 包 (支持环境变量、配置文件)
|
|
|
- **认证**: JWT (JSON Web Token) + OAuth2
|
|
|
- **数据库**: 关系型数据库 (MySQL/PostgreSQL)
|
|
|
|
|
|
## 3. 系统架构
|
|
|
|
|
|
项目遵循经典的**洋葱模型**和**分层架构**：
|
|
|
|
|
|
```
|
|
|
Request -> [Global Middlewares] -> [Router] -> [Group Middlewares] -> [Handler] -> [Service/Logic] -> [Model/DAO] -> Database
|
|
|
|
|
|
|
Response <- [Global After Middleware] <------------------------------------+
|
|
|
```
|
|
|
|
|
|
### 3.1 目录结构
|
|
|
|
|
|
```
|
|
|
/
|
|
|
├── api/ # API 接口层 (路由定义、请求处理)
|
|
|
│ ├── auth/ # 认证相关接口 (登录、注册、刷新Token)
|
|
|
│ ├── oauth/ # OAuth2 Provider 接口
|
|
|
│ ├── role/ # 角色管理接口
|
|
|
│ ├── user/ # 用户管理接口
|
|
|
│ └── init.go # 路由聚合与全局中间件配置
|
|
|
├── auth/ # 核心权限控制模块 (Scoped RBAC 实现)
|
|
|
├── cfg/ # 配置与基础设施 (DB, Redis, Log)
|
|
|
├── models/ # 数据模型定义 (GORM 结构体)
|
|
|
├── libs/ # 通用工具库
|
|
|
├── cli/ # 命令行入口
|
|
|
└── docs/ # 文档
|
|
|
```
|
|
|
|
|
|
## 4. 核心模块设计
|
|
|
|
|
|
### 4.1 认证与授权 (Auth Module)
|
|
|
|
|
|
Auth 模块是系统的核心安全组件，实现了基于作用域（Scope）的角色访问控制 (RBAC) 和资源级权限管理。
|
|
|
|
|
|
#### 4.1.1 核心概念
|
|
|
|
|
|
- **Scope (作用域)**: 权限隔离的边界，不同应用或模块可以拥有独立的权限体系（如 "vb", "app1"）。
|
|
|
- **Permission (权限)**: 最小粒度的操作许可，格式为树状结构字符串。
|
|
|
- **层级定义**:
|
|
|
- **奇数层**: 资源类型 (Level 1: Create)
|
|
|
- **偶数层**: 资源实例 (Level 2: Read, Level 4: Write, Level 7: Admin)
|
|
|
- 示例: `org:orgA:project:projB`
|
|
|
- **Role (角色)**: 权限的集合。角色也属于特定 Scope。
|
|
|
- **UserRole (用户-角色关联)**: 用户在特定 Scope 下拥有的角色。
|
|
|
|
|
|
#### 4.1.2 权限验证机制
|
|
|
|
|
|
系统提供 `auth.Auth` 接口和 `auth.Factory` 工厂，支持多应用集成：
|
|
|
|
|
|
1. **获取实例**: `myAuth := auth.Factory.New("my_scope")`
|
|
|
2. **基础权限**: `myAuth.PermRead("resource:id")` - 检查读取权限。
|
|
|
3. **层级检查**:
|
|
|
- **Admin (Level 7)**: 拥有 `*` 或前缀匹配权限（向下继承）。
|
|
|
- **Standard**: 精确匹配且满足 Level 要求。
|
|
|
4. **动态解析**: 支持从 URL、Query、Header 解析 ID，如 `org:{orgID}`。
|
|
|
|
|
|
#### 4.1.3 中间件流程
|
|
|
|
|
|
1. **LoginMiddleware**: 解析 JWT Token，提取 UserID。
|
|
|
2. **PermMiddleware**: 在业务 Handler 执行前拦截请求，调用 `Check` 进行鉴权。
|
|
|
|
|
|
### 4.2 用户体系 (User Module)
|
|
|
|
|
|
- **User**: 核心用户实体，包含基本信息 (昵称、头像、邮箱等)。
|
|
|
- **Identity**: 认证信息表，支持多种登录方式 (密码、OAuth、验证码等) 关联到同一用户。
|
|
|
- **Session**: 用户会话管理，用于记录登录状态和刷新 Token。
|
|
|
|
|
|
### 4.3 OAuth2 服务 (OAuth Module)
|
|
|
|
|
|
实现了完整的 OAuth2 Provider 功能，支持第三方应用接入：
|
|
|
|
|
|
- **Client**: 第三方应用注册信息 (ClientID, ClientSecret)。
|
|
|
- **AuthorizationCode**: 授权码模式支持。
|
|
|
- **Token**: Access Token 和 Refresh Token 管理。
|
|
|
- **Flows**: 支持 Authorization Code, Client Credentials, Refresh Token 等标准流程。
|
|
|
|
|
|
## 5. 接口规范
|
|
|
|
|
|
### 5.1 请求处理
|
|
|
|
|
|
- **参数解析**: 利用 `vigo` 的泛型 Handler 机制，自动解析 Query, Path, Header, JSON Body 参数到结构体。
|
|
|
- **验证**: 结构体 Tag (`src`, `json`, `default`) 定义参数源和默认值。
|
|
|
|
|
|
### 5.2 响应格式
|
|
|
|
|
|
统一使用 JSON 格式响应，由全局后置中间件 `common.JsonResponse` 处理：
|
|
|
|
|
|
**成功响应**:
|
|
|
```json
|
|
|
{
|
|
|
"code": 200,
|
|
|
"data": { ... } // 或 null
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**错误响应**:
|
|
|
```json
|
|
|
{
|
|
|
"code": 40001, // 400 + 01 (Bad Request + Invalid Argument)
|
|
|
"message": "错误描述信息"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
## 6. 数据库设计
|
|
|
|
|
|
推荐使用 `vigo.Model` 作为基类，统一包含以下字段：
|
|
|
- `ID`: UUID (varchar(36))
|
|
|
- `CreatedAt`: 创建时间
|
|
|
- `UpdatedAt`: 更新时间
|
|
|
- `DeletedAt`: 软删除标记
|
|
|
|
|
|
所有模型在 `models/init.go` 中注册，支持服务启动时自动迁移 (`AutoMigrate`)。
|
|
|
|
|
|
## 7. 部署与运维
|
|
|
|
|
|
- **配置**: 支持 `.env` 文件和环境变量覆盖。
|
|
|
- **构建**: `go build -o vbase cli/main.go`
|
|
|
- **运行**: `./vbase -p 8080`
|
|
|
|
|
|
## 8. 开发规范
|
|
|
|
|
|
1. **资源命名**: 权限资源标识符必须使用 `kebab-case` 或 `snake_case`，使用冒号 `:` 分隔层级。
|
|
|
2. **错误处理**: 优先使用 `vigo.NewError` 或预定义错误 (如 `vigo.ErrNotFound`)，以便统一处理 HTTP 状态码。
|
|
|
3. **测试**: 编写集成测试脚本覆盖核心业务流程。
|