使用标准库模块

公告

站点迁移啦~！

为什么迁移?

作为由我们官方维护的组件库，分散在各自的文档站点中的确有好处：它们可以各自维护自己所需的东西、互不干扰。

但是缺点也很明显：太过分散。

组件库与核心库之间的关系是比较紧密的，我们希望你能够在一个站点内就可以查阅或搜索到所有你想要得知的信息。

适用场景

当你不确定自己的应用场景是否应该选择直接使用标准库模块时，这里为你提供了一些参考：

适用

你希望有一个 Bot 实现，它可以支持订阅事件、管理网络连接的生命周期、可以注册事件处理逻辑、替你接收事件，并进行处理/调度。
你不需要太多额外的功能，例如处理事件时，如果你想要发消息，那么自行构建 API 模块中提供的实现。
你不需要多组件协同。
你不需要 Simple Robot 标准库提供的任何功能。

不适用

你希望使用 Simple Robot 标准库提供的功能。
你希望使用一个有更多高级功能封装的库，而不是一个仅有基础功能的库。例如处理事件时，你只需要组装好消息文本或封装好的消息元素对象，并简单的调用 send 即可发送，不需要自行构建 API、自行发送请求。
你希望能够支持多组件协同。
你希望使用支持 Spring Boot 的库。

安装

implementation("love.forte.simbot.component:simbot-component-qq-guild-stdlib:4.0.0-beta5")

implementation 'love.forte.simbot.component:simbot-component-qq-guild-stdlib:4.0.0-beta5'

<dependency>
    <groupId>love.forte.simbot.component</groupId>
    <!-- Maven 需要添加 `-jvm` 后缀来选择使用 JVM 平台 -->
    <artifactId>simbot-component-qq-guild-stdlib-jvm</artifactId>
    <version>4.0.0-beta5</version>
</dependency>

引擎选择

Ktor引擎: 你可以前往 Ktor文档处选择一个对应所用平台下合适的 Client Engine。这里会根据不同平台提供几个示例，你可以选择其他可用目标。

CIO 是一个比较通用的引擎。在不知道选什么的情况下，可以考虑使用它。
runtimeOnly("io.ktor:ktor-client-cio-jvm:$ktor_version")
runtimeOnly 'io.ktor:ktor-client-cio-jvm:$ktor_version'
<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-client-cio-jvm</artifactId> <version>${ktor_version}</version> <scope>runtime</scope> </dependency>

如果你打算使用 Java11+，也可以选择 Java 引擎。

runtimeOnly("io.ktor:ktor-client-java:$ktor_version")

如果你想要显式配置引擎，那么就不能使用 runtimeOnly 了。
runtimeOnly 'io.ktor:ktor-client-java:$ktor_version'

如果你想要显式配置引擎，那么就不能使用 runtimeOnly 了。
<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-client-java-jvm</artifactId> <version>${ktor_version}</version> <scope>runtime</scope> </dependency>

如果你想要显式配置引擎，那么就不能使用 runtime scope 了。

JavaScript 平台下可以选择 Js 引擎。
implementation("io.ktor:ktor-client-js:$ktor_version")
implementation 'io.ktor:ktor-client-js:$ktor_version'

native 平台目标下，可能需要根据不同的平台类型选择不同的引擎。

可以选择 WinHttp 引擎。
implementation("io.ktor:ktor-client-winhttp:$ktor_version")
implementation 'io.ktor:ktor-client-winhttp:$ktor_version'

Linux 下依旧可以选择 CIO 引擎。
implementation("io.ktor:ktor-client-cio:$ktor_version")
implementation 'io.ktor:ktor-client-cio:$ktor_version'

可以选择 Darwin 引擎。
implementation("io.ktor:ktor-client-darwin:$ktor_version")
implementation 'io.ktor:ktor-client-darwin:$ktor_version'

使用

QQ频道组件的标准库模块在 API模块的基础之上提供了构建 Bot、订阅并处理事件的能力。

    // 准备 bot 的必要信息
val botId = "xxxx"
val botSecret = "" // secret 如果用不到可使用空字符串
val botToken = "xxxx"
// 用于注册 bot 的 “票据” 信息。
val ticket = Bot.Ticket(botId, botSecret, botToken)

// 构建一个 Bot，并可选的进行一些配置。
val bot = BotFactory.create(ticket) {
    // 各种配置...
    // 比如切换服务地址为沙箱频道的服务地址
    useSandboxServerUrl()

    // 指定需要订阅的事件的 intents，默认会订阅：
    // - 频道相关事件
    // - 频道成员相关事件
    // - 公域消息相关事件
    intents // = xxx

    // 自定义一个 shard，默认是 Shard.FULL
    shard = Shard.FULL

    // 其他各种配置...
}

// 注册事件有一些不同但类似的方式
// 1️⃣ 通过 subscribe 注册一个普通的事件处理器，此处理器会接收并处理所有类型的事件
//     subscribe 是最基本的注册方式，也是其他方式的最终汇集点
bot.subscribe { raw ->
    // raw 代表事件的原始JSON字符串
    // this: Signal.Dispatch, 也就是解析出来的事件结构体
    println("event: $this")
    println("event.data: $data")
    println("raw: $raw")
}

// 2️⃣ 通过 processEvent<DispatchType> 注册一个针对具体 Signal.Dispatch 事件类型的事件处理器，
//     它只有在接收到的 Signal.Dispatch 与目标类型一致时才会处理。
//     此示例展示处理 AtMessageCreate 也就公域是消息事件，并在对方发送了包含 'stop' 的文本时终止 bot。
bot.process<AtMessageCreate> {
    println("event message: $data")

    if ("stop" in data.content) {
        // 终止 bot
        bot.cancel()
    }
}

// 启动 bot, 此时会开始获取ws、连接并接收消息。
bot.start()

// 挂起 bot，直到它结束（被终止）
bot.join()

// 准备 bot 的必要信息
var botId = "xxxx";
var botSecret = ""; // secret 如果用不到可使用空字符串
var botToken = "xxxx";
// 用于注册 bot 的 “票据” 信息。
var ticket = new Bot.Ticket(botId, botSecret, botToken);

// 构建一个 Bot，并可选的进行一些配置。
Bot bot = BotFactory.create(ticket, config -> {
    // 各种配置...
    // 比如切换服务地址为沙箱频道的服务地址
    config.useSandboxServerUrl();

    // 指定需要订阅的事件的 intents，默认会订阅：
    // - 频道相关事件
    // - 频道成员相关事件
    // - 公域消息相关事件
    // config.setIntentsValue(...);

    // 自定义一个 shard，默认是 Shard.FULL
    config.setShard(Shard.FULL);

    // 其他各种配置...
});

// 通过 subscribe 注册一个普通的事件处理器，
// 此处理器会接收并处理所有类型的事件
bot.subscribe(EventProcessors.async((event, raw) -> {
    // raw 代表事件的原始JSON字符串
    // event: Signal.Dispatch, 也就是解析出来的事件结构体
    System.out.println("event: " + event);
    System.out.println("event.data: " + event.getData());
    System.out.println("raw: " + raw);

    // 异步处理器必须返回 CompletableFuture
    return CompletableFuture.completedFuture(null);
}));

// 通过 subscribe 注册一个普通的事件处理器，
// 此处理器会接收并处理指定的类型 AtMessageCreate 的事件
// 此示例展示处理 AtMessageCreate 也就公域是消息事件，并在对方发送了包含 'stop' 的文本时终止 bot。
bot.subscribe(EventProcessors.async(AtMessageCreate.class, (event, raw) -> {
    System.out.println("event message: $data");

    if (event.getData().getContent().contains("stop")) {
        // 终止 bot
        bot.cancel();
    }

    // 异步处理器必须返回 CompletableFuture
    return CompletableFuture.completedFuture(null);
}));

// 异步地启动bot，并在 bot 启动完成后，
// 将 bot 转化为 future，这个 future 会在 bot 被终止时完成
// 其实也可以把 startAsync 和 asFuture 拆开写，效果相同。
var future = bot.startAsync()
        .thenCompose(unit -> bot.asFuture());

// 阻塞当前线程，直到 bot 被终止。
future.join();

// 准备 bot 的必要信息
var botId = "xxxx";
var botSecret = ""; // secret 如果用不到可使用空字符串
var botToken = "xxxx";
// 用于注册 bot 的 “票据” 信息。
var ticket = new Bot.Ticket(botId, botSecret, botToken);

// 构建一个 Bot，并可选的进行一些配置。
Bot bot = BotFactory.create(ticket, config -> {
    // 各种配置...
    // 比如切换服务地址为沙箱频道的服务地址
    config.useSandboxServerUrl();

    // 指定需要订阅的事件的 intents，默认会订阅：
    // - 频道相关事件
    // - 频道成员相关事件
    // - 公域消息相关事件
    // config.setIntentsValue(...);

    // 自定义一个 shard，默认是 Shard.FULL
    config.setShard(Shard.FULL);

    // 其他各种配置...
});

// 通过 subscribe 注册一个普通的事件处理器，
// 此处理器会接收并处理所有类型的事件
bot.subscribe(EventProcessors.block((event, raw) -> {
    // raw 代表事件的原始JSON字符串
    // event: Signal.Dispatch, 也就是解析出来的事件结构体
    System.out.println("event: " + event);
    System.out.println("event.data: " + event.getData());
    System.out.println("raw: " + raw);
}));

// 通过 subscribe 注册一个普通的事件处理器，
// 此处理器会接收并处理指定的类型 AtMessageCreate 的事件
// 此示例展示处理 AtMessageCreate 也就公域是消息事件，并在对方发送了包含 'stop' 的文本时终止 bot。
bot.subscribe(EventProcessors.block(AtMessageCreate.class, (event, raw) -> {
    System.out.println("event message: $data");

    if (event.getData().getContent().contains("stop")) {
        // 终止 bot
        bot.cancel();
    }
}));

// 启动bot
bot.startBlocking();

// 阻塞当前线程，直到 bot 被终止。
bot.joinBlocking();

Last modified: 15 July 2024