Mirai Console Backend - Permissions

Mirai Console 权限系统。

优先使用 Mirai Console 权限系统管理权限是最好的选择

权限

每个权限都由 Permissionopen in new window 对象表示。

一个 Permissionopen in new window 拥有这些信息:

interface Permission {
    val id: PermissionId // 唯一识别 ID
    val description: String // 描述信息
    val parent: Permission // 父权限
}

「权限」表示的意义是 “做一项工作的能力”。如 “执行指令 /stop”,“操作数据库” 都能叫作权限。

Permissionopen in new window 对象由 Console 内置或者由特定权限插件实现。其他插件不能实现 Permissionopen in new window 接口,只能从 PermissionService 注册并获取。

权限 ID

data class PermissionId(
    val namespace: String, // 命名空间
    val name: String, // 名称
)

PermissionIdopen in new windowPermissionopen in new window 的唯一标识符。知道 PermissionIdopen in new window 就可以获取到对应的 Permissionopen in new window

字符串表示为 $namespace:$name,如 console:command.stop, *:*

一般情况下使用位于插件对象(JvmPlugin) 的 permissionId 为插件分配一个 PermissionIdopen in new window

命名空间

命名空间(namespace)用于限定权限的创建者,避免冲突。

一些常见命名空间:

用途命名空间
根权限"*"
Console 内置"console"
ID 为 A 的插件"A"

名称

名称则表示特定的含义。如一个指令,某一项操作等。

一些常见名称:

用途名称
根权限"*"
Console 内置的名为 A 的指令"command.A"
ID 为 A 的插件的名为 B 的指令"command.B"

根权限

RootPermissionopen in new window 是所有权限的父权限。其 ID 为 *:*

如果 Permitteeopen in new window (见下文) 拥有根权限, 相当于 Permitteeopen in new window 拥有全部权限 (内置实现)

被许可人

interface Permittee {
    val permitteeId: PermitteeId
}

Permitteeopen in new window 表示一个可被赋予权限的对象,即 '被许可人'。

CommandSenderopen in new window 实现 Permitteeopen in new window

被许可人自身不持有拥有的权限列表,而是拥有 PermitteeIdopen in new window,标识自己的身份,供 权限服务open in new window 处理。

注意:请不要自主实现 Permitteeopen in new window

被许可人 ID

interface PermitteeId {
    val directParents: Array<out PermitteeId> // 直接父对象
    fun asString(): String // 转换为字符串表示
}

PermitteeIdopen in new window 是被许可人的标识符。

一个这样的标识符既可代表特定的单个 Permitteeopen in new window, 也可以表示多个同类 Permitteeopen in new window.

directParents

PermitteeIdopen in new window 允许拥有多个父对象。在检查权限时会首先检查自己, 再递归检查父类。

衍生类型

PermitteeIdopen in new window 的实现通常是 AbstractPermitteeIdopen in new window

AbstractPermitteeIdopen in new window 查看其子类。

注意: 对应 权限服务open in new window 没明确说明可以自行实现时, 不要轻易实现 PermitteeIdopen in new window

字符串表示

当使用 PermitteeId.asString 时, 不同的类型的返回值如下表所示. 这些格式也适用于 权限指令.
(不区分大小写. 不区分 Bot).

被许可人类型字符串表示示例备注
控制台console
任意其他客户端client*即 Bot 自己发消息给自己
精确群g123456表示群, 而不表示群成员, 不表示群成员
精确好友f123456必须通过好友消息
精确群临时会话t123456.789群 123456 内的成员 789. 必须通过临时会话
精确群成员m123456.789群 123456 内的成员 789. 同时包含临时会话
精确用户u123456同时包含群成员, 好友, 临时会话
任意群g*g 意为 group, 不表示群成员
任意群的任意群员m*m 意为 member
精确群的任意群员m123456.*群 123456 内的任意成员. 同时包含临时会话
任意临时会话t*t 意为 temp. 必须通过临时会话
精确群的任意临时会话t123456.*群 123456 内的任意成员. 必须通过临时会话
任意好友f*f 意为 friend
任意用户u*u 意为 user. 任何人在任何环境
任意陌生人s*s 意为 stranger. 任何人在任何环境
任意联系对象*即任何人, 任何群. 不包括控制台

获取被许可人

在 Kotlin 通常使用 CommandSender.permitteeId,在 Java 使用 CommandSender.getPermitteeId( )
也可以直接构造 AbstractPermitteeIdopen in new window 的子类。或者在 Kotlin 使用扩展 User.permitteeId

权限服务

PermissionServiceopen in new window 承载权限的授权和管理。 Console 的权限系统完全由 PermissionServiceopen in new window 提供支持。 权限服务可以由插件提供(见 扩展)。 在没有任何提供权限服务的插件时会使用 Console 内置实现。

在整个运行时 Console 只会使用同一个权限服务,如果安装多个提供权限服务的插件很有可能导致崩溃。

如果运行于 JVM 平台, 可以使用 Karlatemp/LuckPerms-Miraiopen in new window 以得到更好的使用体验 (支持权限组, 权限检查状态详细输出等)

判断权限

在 Kotlin,在该有扩展的对象上 Console 都为它们实现了扩展。可以使用:

fun Permittee.hasPermission(Permission): Boolean
fun Permission.testPermission(Permittee): Boolean
fun PermitteeId.hasPermission(Permission): Boolean
fun PermissionId.testPermission(Permittee): Boolean
fun Permittee.hasPermission(PermissionId): Boolean
fun Permission.testPermission(PermitteeId): Boolean
// ... 

在 Java,请查看 PermissionServiceopen in new window 中的伴生对象。

查看使用示例:

注册权限

每一条指令都会默认自动创建一个权限。

如果希望手动注册一个其他用途的权限,使用 PermissionService.register

注意

  • 权限只能在插件 启用 之后才能注册。否则会得到一个异常。
  • 使用 PermissionService.register 时对于同一个 PermissionIdopen in new window 只能注册一次, 如果多次注册会得到一个异常

使用内置权限服务指令

指令: "/permission", "/perm", "/权限"

使用指令而不带参数可以获取如下用法:

/permission cancel <被许可人 ID> <权限 ID>   取消授权一个权限
/permission cancelall <被许可人 ID> <权限 ID>   取消授权一个权限及其所有子权限
/permission listpermissions    查看所有权限列表
/permission permit <被许可人 ID> <权限 ID>   授权一个权限
/permission permittedpermissions <被许可人 ID>   查看被授权权限列表

其中, 被许可人 ID 使用 字符串表示, 权限 ID 参见 权限 ID


这是文档的最后一个章节。

返回 开发文档索引