Mirai Console 权限系统。
优先使用 Mirai Console 权限系统管理权限是最好的选择
每个权限都由 Permission
对象表示。
一个 Permission
拥有这些信息:
interface Permission {
val id: PermissionId // 唯一识别 ID
val description: String // 描述信息
val parent: Permission // 父权限
}
「权限」表示的意义是 “做一项工作的能力”。如 “执行指令 /stop”,“操作数据库” 都能叫作权限。
Permission
对象由 Console 内置或者由特定权限插件实现。其他插件不能实现 Permission
接口,只能从 PermissionService
注册并获取。
data class PermissionId(
val namespace: String, // 命名空间
val name: String, // 名称
)
PermissionId
是 Permission
的唯一标识符。知道 PermissionId
就可以获取到对应的 Permission
。
字符串表示为 $namespace:$name
,如 console:command.stop
, *:*
一般情况下使用位于插件对象(
JvmPlugin
) 的permissionId
为插件分配一个PermissionId
命名空间(namespace
)用于限定权限的创建者,避免冲突。
一些常见命名空间:
用途 | 命名空间 |
---|---|
根权限 | "*" |
Console 内置 | "console" |
ID 为 A 的插件 | "A" |
名称则表示特定的含义。如一个指令,某一项操作等。
一些常见名称:
用途 | 名称 |
---|---|
根权限 | "*" |
Console 内置的名为 A 的指令 | "command.A" |
ID 为 A 的插件的名为 B 的指令 | "command.B" |
RootPermission
是所有权限的父权限。其 ID 为 *:*
interface Permittee {
val permitteeId: PermitteeId
}
Permittee
表示一个可被赋予权限的对象,即 '被许可人'。
被许可人自身不持有拥有的权限列表,而是拥有 PermitteeId
,标识自己的身份,供 权限服务 处理。
注意:请不要自主实现 Permittee
。
interface PermitteeId {
val directParents: Array<out PermitteeId> // 直接父对象
fun asString(): String // 转换为字符串表示
}
PermitteeId
是被许可人的标识符。
一个这样的标识符既可代表特定的单个 Permittee
, 也可以表示多个同类 Permittee
.
PermitteeId
允许拥有多个父对象。在检查权限时会首先检查自己, 再递归检查父类。
PermitteeId
的实现通常是 AbstractPermitteeId
在 AbstractPermitteeId
查看其子类。
注意: 对应 权限服务 没明确说明可以自行实现时, 不要轻易实现 PermitteeId
当使用 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( )
。
也可以直接构造 AbstractPermitteeId
的子类。或者在 Kotlin 使用扩展 User.permitteeId
。
PermissionService
承载权限的授权和管理。 Console 的权限系统完全由 PermissionService
提供支持。
权限服务可以由插件提供(见 扩展)。
在没有任何提供权限服务的插件时会使用 Console 内置实现。
在整个运行时 Console 只会使用同一个权限服务,如果安装多个提供权限服务的插件很有可能导致崩溃。
如果运行于 JVM 平台, 可以使用 Karlatemp/LuckPerms-Mirai 以得到更好的使用体验 (支持权限组, 权限检查状态详细输出等)
在 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,请查看 PermissionService
中的伴生对象。
每一条指令都会默认自动创建一个权限。
如果希望手动注册一个其他用途的权限,使用 PermissionService.register
。
注意:
- 权限只能在插件 启用 之后才能注册。否则会得到一个异常。
- 使用
PermissionService.register
时对于同一个PermissionId
只能注册一次, 如果多次注册会得到一个异常
指令: "/permission", "/perm", "/权限"
使用指令而不带参数可以获取如下用法:
/permission cancel <被许可人 ID> <权限 ID> 取消授权一个权限
/permission cancelall <被许可人 ID> <权限 ID> 取消授权一个权限及其所有子权限
/permission listpermissions 查看所有权限列表
/permission permit <被许可人 ID> <权限 ID> 授权一个权限
/permission permittedpermissions <被许可人 ID> 查看被授权权限列表
其中, 被许可人 ID 使用 字符串表示, 权限 ID 参见 权限 ID
这是文档的最后一个章节。
返回 开发文档索引