OneAuth/doc/integration.md

VBase 集成指南

1. 引入路由

import "github.com/veypi/vbase/api"

func main() {
    // 挂载 vbase 路由到 /api/v1/vb
    rootRouter.Extend("/api/v1/vb", api.Router)
}

2. 集成配置

配置自动从 vigo 的 config.toml 读取：

[vbase]
jwt_secret = "your-secret-key"
jwt_expire = 7200          # token 过期时间(秒)
refresh_expire = 604800    # refresh token 过期时间(秒)
bcrypt_cost = 10           # 密码加密强度

[vbase.redis]
addr = "localhost:6379"    # 留空或填 memory 使用内存缓存
password = ""
db = 0

或在代码中自定义：

import "github.com/veypi/vbase/cfg"

cfg.Config.JWTSecret = "your-secret"
cfg.Config.JWTExpire = 7200

3. 配置策略

创建组织时自动初始化默认策略：

import "github.com/veypi/vbase/api/middleware"

// 创建组织后调用
middleware.InitOrgPolicies(orgID)

默认创建的策略：

策略	资源	操作	条件	说明
policy:manage	policy	*	admin	管理策略
role:manage	role	*	admin	管理角色
user:update	user	update	owner	只能改自己

自定义策略：

import "github.com/veypi/vbase/models"

policy := &models.Policy{
    Code:     "project:delete",
    Name:     "删除项目",
    Resource: "project",
    Action:   "delete",
    Effect:   models.PolicyEffectAllow,
    Condition: "owner",  // 只有所有者能删
    Scope:    models.PolicyScopeOrg,
}
cfg.DB().Create(policy)

4. 使用鉴权

4.1 全局中间件（已内置）

// api/init.go 已自动配置：
Router.Use(middleware.AuthRequired())   // JWT 认证
Router.Use(middleware.OrgContext())     // 组织上下文

4.2 公开接口（跳过认证）

Router.Get("/public", vigo.SkipBefore, "公开接口", handler)

4.3 接口级权限控制

import "github.com/veypi/vbase/api/middleware"

// 需要管理员权限
Router.Post("/users", middleware.RequireAdmin(), "创建用户", createUser)

// 基于 Policy 的细粒度控制
Router.Post("/projects", middleware.Permission("project", "create"), "创建项目", createProject)

// 带所有者检查（用户只能改自己的数据）
Router.Patch("/users/{id}", middleware.PermissionWithOwner("user", "update", "owner_id"), "更新用户", updateUser)

// 管理员或所有者
Router.Delete("/projects/{id}", middleware.AdminOrOwner("owner_id"), "删除项目", deleteProject)

4.4 代码中手动检查

func myHandler(x *vigo.X, req *Req) error {
    checker := middleware.NewChecker(x)

    // 检查是否为管理员
    if !checker.IsOrgAdmin() {
        return vigo.ErrForbidden
    }

    // 检查具体权限
    if err := checker.RequirePermission("resource", "write"); err != nil {
        return err
    }

    return nil
}

5. 完整示例

package main

import (
    "github.com/veypi/vbase/api"
    "github.com/veypi/vbase/api/middleware"
    "github.com/veypi/vigo"
)

func main() {
    r := vigo.NewRouter()

    // 1. 挂载 vbase
    r.Extend("/api/vb", api.Router)

    // 2. 业务路由加权限
    project := r.SubRouter("/projects")
    project.Use(middleware.AuthRequired())

    project.Get("/", middleware.Permission("project", "list"), "项目列表", listProjects)
    project.Post("/", middleware.Permission("project", "create"), "创建项目", createProject)
    project.Patch("/{id}", middleware.PermissionWithOwner("project", "update", "owner_id"), "更新项目", updateProject)
    project.Delete("/{id}", middleware.AdminOrOwner("owner_id"), "删除项目", deleteProject)

    vigo.Run(r)
}