You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

5.3 KiB

Raw Blame History Unescape Escape

VBase 后端架构设计文档

1. 概览

VBase 是一个基于 Golang 的高性能后端基础框架，旨在提供一套标准化的用户管理、作用域权限控制（Scoped RBAC）和 OAuth2 认证服务。项目采用分层架构设计，基于 vigo 框架构建，强调代码的可维护性、扩展性和安全性。

2. 技术栈

语言: Golang 1.22+
Web 框架: 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 工厂，支持多应用集成：

获取实例: myAuth := auth.Factory.New("my_scope")
基础权限: myAuth.PermRead("resource:id") - 检查读取权限。
层级检查:
- Admin (Level 7): 拥有 * 或前缀匹配权限（向下继承）。
- Standard: 精确匹配且满足 Level 要求。
动态解析: 支持从 URL、Query、Header 解析 ID，如 org:{orgID}。

4.1.3 中间件流程

LoginMiddleware: 解析 JWT Token，提取 UserID。
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 处理：

成功响应:

{
  "code": 200,
  "data": { ... } // 或 null
}

错误响应:

{
  "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. 开发规范

资源命名: 权限资源标识符必须使用 kebab-case 或 snake_case，使用冒号 : 分隔层级。
错误处理: 优先使用 vigo.NewError 或预定义错误 (如 vigo.ErrNotFound)，以便统一处理 HTTP 状态码。
测试: 编写集成测试脚本覆盖核心业务流程。

5.3 KiB Raw Blame History Unescape Escape