Runtime 核心 API

Runtime

sdk.Runtime 是一个进程内的全局容器，持有数据库连接、缓存/队列适配器、Casbin enforcer、定时任务等运行时对象，供业务代码随取随用。多租户场景下，大部分方法都有 xxxByTenant(tenant string) 的变体，租户标识通常传 c.Request.Host。

1. 系统配置

用于在运行时读写任意键值，不需要提前声明结构体字段——适合存运营可调整的开关、临时配置，而不是每次改都要发版的场景。

SetConfigValue / GetConfigValue

// 设置默认租户下的配置
sdk.Runtime.SetConfigValue("sys_wechat_webhook", "https://...")

// 读取，返回 interface{}，需要按实际类型断言
url, _ := sdk.Runtime.GetConfigValue("sys_wechat_webhook").(string)

多租户场景使用 SetConfigValueByTenant(tenant, key, value) / GetConfigValueByTenant(tenant, key)。

2. 队列

GetQueuePrefix（推荐）

获取当前配置选中的队列——配置文件里配了 redis 就是 Redis 实现，没配就是内存实现。业务代码应该始终用这个方法，见队列。

// prefix 通常传 c.Request.Host，多租户下用于区分消息归属；单租户传空字符串
queue := sdk.Runtime.GetQueuePrefix("")
queue.Register("log", models.SaveLoginLog)
go queue.Run()

WARNING

Register 之后必须调用 Run()，否则消息只会被 Append 进去，永远不会被消费。

GetMemoryQueue（已弃用）

始终返回进程内内存队列，无视配置文件里选的是什么。 早期版本这是获取队列的唯一方式，现在请改用 GetQueuePrefix——继续使用 GetMemoryQueue 意味着即使配置文件里配了 Redis，这处代码依然只在本进程内工作，多实例部署时互相看不到对方的消息。

3. 数据库

GetDb

获取默认租户的数据库连接：

sdk.Runtime.GetDb()
// 返回 *gorm.DB

GetDbByTenant

获取指定租户的数据库连接，多租户场景下按 c.Request.Host 区分：

sdk.Runtime.GetDbByTenant(c.Request.Host)
// 返回 *gorm.DB

未启用多租户时，数据库统一注册在通配符键 "*" 下，此时无论传入什么租户标识都会返回同一个连接——这也是为什么单租户项目里到处传 c.Request.Host 也能正常工作。真正按域名区分数据库，只在启用多租户、且该域名确实注册过时才会发生；查无此租户又没有 "*" 兜底时返回 nil。

GetAllDb

获取全部租户的数据库连接，用于需要遍历所有库的场景（例如定时任务对每个租户各跑一遍）：

sdk.Runtime.GetAllDb()
// 返回 map[string]*gorm.DB

SetDb / SetDbByTenant

sdk.Runtime.SetDb(db)                    // 设置默认租户
sdk.Runtime.SetDbByTenant(tenant, db)    // 设置指定租户

WARNING

GetDb() 和 GetAllDb() 容易搞混——前者返回单个 *gorm.DB，后者返回 map[string]*gorm.DB。这两个方法在早期版本中是反过来命名的（当时的 GetDb() 就是现在的 GetAllDb()），照抄旧代码或旧文章容易在这里出编译错误。

4. 用户信息

以下方法均需要 gin.Context，来自包 github.com/go-admin-team/go-admin-core/v2/jwtauth/user：

user.GetUserId(c)     // 用户 ID
user.GetUserName(c)   // 用户名
user.GetRoleId(c)     // 角色 ID
user.GetRoleName(c)   // 角色名称
user.GetDeptId(c)     // 部门 ID
user.GetDeptName(c)   // 部门名称

WARNING

go-admin-core 目前是 v2（模块路径 github.com/go-admin-team/go-admin-core/v2）。v1 时代 sdk/pkg/ 下的 jwtauth、jwtauth/user、casbin、response 几个包在 v2 里都搬到了模块根目录（比如 sdk/pkg/jwtauth/user 现在是 v2/jwtauth/user）。照抄旧文章或旧代码里的 import 路径会直接编译失败，报"找不到包"而不是运行时错误，容易第一时间怀疑成环境问题。

这些值来自 JWT payload，认证流程见认证与鉴权。典型用法是在写入操作中记录操作人：

func (e SysApi) Update(c *gin.Context) {
    req := dto.SysApiUpdateReq{}
    // ...绑定参数...

    req.SetUpdateBy(user.GetUserId(c))

    // ...执行更新...
    e.OK(req.GetId())
}

WARNING

从哪里获得帮助：

如果你在阅读本教程的过程中有任何疑问，可以前往提交建议。

‌
‌
‌
‌

Runtime

1. 系统配置

用于在运行时读写任意键值，不需要提前声明结构体字段——适合存运营可调整的开关、临时配置，而不是每次改都要发版的场景。

SetConfigValue / GetConfigValue

// 设置默认租户下的配置
sdk.Runtime.SetConfigValue("sys_wechat_webhook", "https://...")

// 读取，返回 interface{}，需要按实际类型断言
url, _ := sdk.Runtime.GetConfigValue("sys_wechat_webhook").(string)

多租户场景使用 SetConfigValueByTenant(tenant, key, value) / GetConfigValueByTenant(tenant, key)。

2. 队列

GetQueuePrefix（推荐）

获取当前配置选中的队列——配置文件里配了 redis 就是 Redis 实现，没配就是内存实现。业务代码应该始终用这个方法，见队列。

// prefix 通常传 c.Request.Host，多租户下用于区分消息归属；单租户传空字符串
queue := sdk.Runtime.GetQueuePrefix("")
queue.Register("log", models.SaveLoginLog)
go queue.Run()

WARNING

Register 之后必须调用 Run()，否则消息只会被 Append 进去，永远不会被消费。

GetMemoryQueue（已弃用）

3. 数据库

GetDb

获取默认租户的数据库连接：

sdk.Runtime.GetDb()
// 返回 *gorm.DB

GetDbByTenant

获取指定租户的数据库连接，多租户场景下按 c.Request.Host 区分：

sdk.Runtime.GetDbByTenant(c.Request.Host)
// 返回 *gorm.DB

GetAllDb

获取全部租户的数据库连接，用于需要遍历所有库的场景（例如定时任务对每个租户各跑一遍）：

sdk.Runtime.GetAllDb()
// 返回 map[string]*gorm.DB

SetDb / SetDbByTenant

sdk.Runtime.SetDb(db)                    // 设置默认租户
sdk.Runtime.SetDbByTenant(tenant, db)    // 设置指定租户

WARNING

4. 用户信息

以下方法均需要 gin.Context，来自包 github.com/go-admin-team/go-admin-core/v2/jwtauth/user：

user.GetUserId(c)     // 用户 ID
user.GetUserName(c)   // 用户名
user.GetRoleId(c)     // 角色 ID
user.GetRoleName(c)   // 角色名称
user.GetDeptId(c)     // 部门 ID
user.GetDeptName(c)   // 部门名称

WARNING

这些值来自 JWT payload，认证流程见认证与鉴权。典型用法是在写入操作中记录操作人：

func (e SysApi) Update(c *gin.Context) {
    req := dto.SysApiUpdateReq{}
    // ...绑定参数...

    req.SetUpdateBy(user.GetUserId(c))

    // ...执行更新...
    e.OK(req.GetId())
}

WARNING

从哪里获得帮助：

如果你在阅读本教程的过程中有任何疑问，可以前往提交建议。

TABLE OF CONTENTS

TABLE OF CONTENTS

Runtime

1. 系统配置

SetConfigValue / GetConfigValue

2. 队列

GetQueuePrefix（推荐）

WARNING

GetMemoryQueue（已弃用）

3. 数据库

GetDb

GetDbByTenant

GetAllDb

SetDb / SetDbByTenant

WARNING

4. 用户信息

WARNING

WARNING

Runtime

1. 系统配置

SetConfigValue / GetConfigValue

2. 队列

GetQueuePrefix（推荐）

WARNING

GetMemoryQueue（已弃用）

3. 数据库

GetDb

GetDbByTenant

GetAllDb

SetDb / SetDbByTenant

WARNING

4. 用户信息

WARNING

WARNING