|
|
# VBase 集成文档
|
|
|
|
|
|
本文档介绍如何将 VBase 集成到您的 Golang (Vigo) 项目中，快速实现用户管理、权限控制和组织架构功能。
|
|
|
|
|
|
## 1. 快速集成 (Quick Start)
|
|
|
|
|
|
集成 VBase 仅需简单几步：
|
|
|
|
|
|
### 1.1 引入依赖
|
|
|
|
|
|
在您的项目中引入 VBase：
|
|
|
|
|
|
```go
|
|
|
import "github.com/veypi/vbase"
|
|
|
```
|
|
|
|
|
|
### 1.2 挂载路由
|
|
|
|
|
|
在您的项目根路由初始化处，挂载 VBase 路由：
|
|
|
|
|
|
```go
|
|
|
// 您的项目初始化代码
|
|
|
func init() {
|
|
|
// 挂载 vbase 路由到 /vbase 路径下
|
|
|
// 这样 vbase 的 API 将可以通过 /vb/api/auth/login 等访问
|
|
|
MyRouter.Extend("/vb", vbase.Router)
|
|
|
}
|
|
|
```
|
|
|
|
|
|
### 1.3 配置数据库
|
|
|
|
|
|
确保您的项目已经配置了 GORM 数据库连接，VBase 将复用该连接。
|
|
|
|
|
|
```go
|
|
|
// VBase 会自动读取您的配置，前提是您使用了兼容的配置结构或手动设置
|
|
|
vbase.Config.SetDB(yourDB)
|
|
|
// 或者直接集成到您的项目配置中，由vigo.Flags 自动加载
|
|
|
type AppConfig struct {
|
|
|
Vbase any
|
|
|
}
|
|
|
var Config = *AppConfig{
|
|
|
Vbase: vbase.Config,
|
|
|
}
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
## 2. 详细集成方案
|
|
|
|
|
|
### 2.1 路由集成
|
|
|
|
|
|
VBase 提供了一个标准的 `vigo.Router` 实例，包含所有用户、组织、权限相关的 API。
|
|
|
|
|
|
```go
|
|
|
package main
|
|
|
|
|
|
import (
|
|
|
"github.com/veypi/vbase"
|
|
|
"github.com/veypi/vigo"
|
|
|
)
|
|
|
|
|
|
var Router = vigo.NewRouter()
|
|
|
|
|
|
func init() {
|
|
|
// 1. 挂载 VBase 路由
|
|
|
// 建议挂载在独立的前缀下，避免路由冲突
|
|
|
Router.Extend("/vb", vbase.Router)
|
|
|
}
|
|
|
```
|
|
|
|
|
|
### 2.2 权限系统集成
|
|
|
|
|
|
VBase 提供了强大的 RBAC (基于角色的访问控制) 权限系统。
|
|
|
|
|
|
#### 2.2.1 初始化应用权限
|
|
|
|
|
|
在您的应用中，使用 `vbase.Auth.New` 创建应用专属的权限实例。
|
|
|
|
|
|
```go
|
|
|
import (
|
|
|
"github.com/veypi/vbase"
|
|
|
"github.com/veypi/vbase/models"
|
|
|
)
|
|
|
|
|
|
// 定义您的应用权限实例
|
|
|
var AppAuth = vbase.Auth.New("my_app", models.AppConfig{
|
|
|
Name: "My Application",
|
|
|
Description: "我的应用描述",
|
|
|
// 定义应用的默认角色
|
|
|
DefaultRoles: []models.RoleDefinition{
|
|
|
{
|
|
|
Code: "admin",
|
|
|
Name: "管理员",
|
|
|
Policies: []string{"*:*"}, // 拥有所有权限
|
|
|
},
|
|
|
{
|
|
|
Code: "editor",
|
|
|
Name: "编辑",
|
|
|
Policies: []string{"article:create", "article:update"},
|
|
|
},
|
|
|
},
|
|
|
})
|
|
|
```
|
|
|
|
|
|
#### 2.2.2 使用权限中间件
|
|
|
|
|
|
使用 `vbase.AuthMiddleware` 进行认证，并结合 `AppAuth.Perm` 进行权限检查。
|
|
|
|
|
|
```go
|
|
|
func init() {
|
|
|
// 1. 全局认证中间件 (解析 Token, 注入 user_id, org_id)
|
|
|
Router.Use(vbase.AuthMiddleware())
|
|
|
Router.Get("/info", "获取app信息", vigo.SkipBefore, getInfo)
|
|
|
// 2. 路由权限控制
|
|
|
// 检查 "article:create" 权限
|
|
|
Router.Post("/articles", "发布文章", AppAuth.Perm("article:create"), createArticle)
|
|
|
|
|
|
// 检查资源所有权 (确保用户只能修改自己的文章)
|
|
|
// 检查 "article:update" 权限，且文章的 owner_id 必须等于当前用户 ID
|
|
|
Router.Patch("/articles/{id}", "更新文章", AppAuth.PermWithOwner("article:update", "id"), updateArticle)
|
|
|
}
|
|
|
```
|
|
|
|
|
|
### 2.3 配置管理
|
|
|
|
|
|
VBase 允许自定义部分配置。
|
|
|
|
|
|
```go
|
|
|
import "github.com/veypi/vbase"
|
|
|
|
|
|
func main() {
|
|
|
// 获取配置单例
|
|
|
cfg := vbase.Config
|
|
|
|
|
|
// 启用调试模式
|
|
|
cfg.Debug = true
|
|
|
|
|
|
// 设置 JWT 密钥 (建议从环境变量读取)
|
|
|
cfg.JwtSecret = "your-secret-key"
|
|
|
|
|
|
// 自定义短信服务提供商 (可选)
|
|
|
// vbase.Config.SetSmsProvider(...)
|
|
|
}
|
|
|
```
|
|
|
|
|
|
### 2.4 上下文使用
|
|
|
|
|
|
通过 `vbase.AuthMiddleware` 认证后，您可以在 Handler 中通过 `*vigo.X` 获取用户信息。
|
|
|
|
|
|
```go
|
|
|
func MyHandler(x *vigo.X) error {
|
|
|
// 获取当前用户 ID
|
|
|
userID := x.Get("user_id").(string)
|
|
|
|
|
|
// 获取当前组织 ID (如果有)
|
|
|
orgID := x.Get("org_id").(string)
|
|
|
|
|
|
// ... 业务逻辑
|
|
|
}
|
|
|
```
|