# Mirai Console Backend - Permissions

Mirai Console 权限系统。

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

# 权限

每个权限都由 Permission (opens new window) 对象表示。

一个 Permission (opens new window) 拥有这些信息:

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

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

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

# 权限 ID

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

PermissionId (opens new window)Permission (opens new window) 的唯一标识符。知道 PermissionId (opens new window) 就可以获取到对应的 Permission (opens new window)

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

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

# 命名空间

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

一些常见命名空间:

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

# 名称

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

一些常见名称:

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

# 根权限

RootPermission (opens new window) 是所有权限的父权限。其 ID 为 *:*

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

# 被许可人

interface Permittee {
    val permitteeId: PermitteeId
}
1
2
3

Permittee (opens new window) 表示一个可被赋予权限的对象,即 '被许可人'。

CommandSender (opens new window) 实现 Permittee (opens new window)

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

注意:请不要自主实现 Permittee (opens new window)

# 被许可人 ID

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

PermitteeId (opens new window) 是被许可人的标识符。

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

# directParents

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

# 衍生类型

PermitteeId (opens new window) 的实现通常是 AbstractPermitteeId (opens new window)

AbstractPermitteeId (opens new window) 查看其子类。

注意: 对应 权限服务 (opens new window) 没明确说明可以自行实现时, 不要轻易实现 PermitteeId (opens 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( )
也可以直接构造 AbstractPermitteeId (opens new window) 的子类。或者在 Kotlin 使用扩展 User.permitteeId

# 权限服务

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

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

如果运行于 JVM 平台, 可以使用 Karlatemp/LuckPerms-Mirai (opens 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
// ... 
1
2
3
4
5
6
7

在 Java,请查看 PermissionService (opens new window) 中的伴生对象。

查看使用示例: Him188/mirai-console-example-plugin (opens new window)

# 注册权限

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

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

注意

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

# 使用内置权限服务指令

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

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

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

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


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

返回 开发文档索引