使用 Spring Boot

公告

站点迁移啦~！

为什么迁移?

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

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

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

准备

Java 17

simbot4 的 Spring Boot starter 基于 Spring Boot 3，因此 Java 的版本至少为 Java17。

创建 Spring Boot 3 项目

首先你得有个 Spring Boot 3 项目, 你可以前往 Spring Initializr 或者借助 IDE (比如 IDEA) 的相关功能创建一个 Spring Boot 3 的项目。你可以自由选择需要添加的任何其他 Spring Boot 组件，比如 spring-boot-starter-web 之类的。

安装

// simbot4核心库
implementation("love.forte.simbot:simbot-core-spring-boot-starter:4.1.0")
// QQ频道组件库
implementation("love.forte.simbot.component:simbot-component-qq-guild-core:4.0.0-beta5")

// simbot4核心库
implementation 'love.forte.simbot:simbot-core-spring-boot-starter:4.1.0'
// QQ频道组件库
implementation 'love.forte.simbot.component:simbot-component-qq-guild-core:4.0.0-beta5'

<!-- simbot4核心库 -->
<dependency>
    <groupId>love.forte.simbot</groupId>
    <artifactId>simbot-core-spring-boot-starter</artifactId>
    <version>4.1.0</version>
</dependency>
<!-- QQ频道组件库 -->
<dependency>
    <groupId>love.forte.simbot.component</groupId>
    <artifactId>simbot-component-qq-guild-core-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'

Bot 配置

在你的资源目录中: resources/simbot-bots/ 中创建任意的一个或多个bot配置文件，并以 .bot.json 作为扩展名，例如 mybot.bot.json。

配置文件的内容可前往参考 Bot配置文件章节。

使用

添加启动注解

在你的启动类上添加 @EnableSimbot 注解来启用 simbot。

@EnableSimbot // 启用 simbot
@SpringBootApplication
class MyApplication

fun main(args: Array<String>) {
    runApplicarion<MyApplication>(*args)
}

@EnableSimbot // 启用 simbot
@SpringBootApplication
public class MyApplication {
    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }
}

QQ频道组件支持使用 SPI 自动加载组件和插件。添加依赖到项目环境中、编写完 Bot 配置文件后，可前往 simbot手册: 使用 Spring Boot 3 了解更多 simbot4 Spring Boot starter 的可配置内容以及启动注解等信息。

简单示例

几个简单的事件监听示例。

@EnableSimbot // 启用 simbot
@SpringBootApplication
class MyApplication

fun main(args: Array<String>) {
    runApplicarion<MyApplication>(*args)
}

private val logger = LoggerFactory.getLogger(MyHandlers::class.java)

@Component // 需要交给Spring管理
class MyHandlers {
    @Listener // 标记事件处理函数
    suspend fun handle(event: Event) {
        logger.info("Event: {}", event)
    }
}

@EnableSimbot // 启用 simbot
@SpringBootApplication
public class MyApplication {
    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }

    @Component // 需要交给Spring管理
    public static class MyHandlers {
        private static final Logger logger = Logger.getLogger(MyHandlers.class);
      
        @Listener // 标记事件处理函数
        public void handle(Event event) {
            logger.info("Event: {}", event)
        }
    }
}

此处以 "子频道消息事件" 为例，此事件类型为 ChatChannelMessageEvent。

事件逻辑：当收到文本内包含"你好" 的消息，回复"你也好"。

@EnableSimbot // 启用 simbot
@SpringBootApplication
class MyApplication

fun main(args: Array<String>) {
    runApplicarion<MyApplication>(*args)
}

@Component // 需要交给Spring管理
class MyHandlers {
    @Listener // 标记事件处理函数
    @Filter(  // 简单的事件过滤注解
        value = "你好", // 需要包含的文字
        matchType = MatchType.TEXT_CONENT // 调整匹配模式为 "文本包含"
    )
    // 如果需要，添加此注解来去除匹配用的文本前后的空白字符。
    // 由于 QQ 频道的公域 bot 都是需要被 at 的，
    // 而被 at 时，文本消息很有可能存在一些前后空格，所以会比较有用
    @ContentTrim 
    suspend fun handle(event: ChatChannelMessageEvent) {
        event.reply("你也好")
    }
}

@EnableSimbot // 启用 simbot
@SpringBootApplication
public class MyApplication {
  public static void main(String[] args) {
    SpringApplication.run(MyApplication.class, args);
  }

  @Component // 需要交给Spring管理
  public static class MyHandlers {
    @Listener // 标记事件处理函数
    @Filter(  // 简单的事件过滤注解
            value = "你好", // 需要包含的文字
            matchType = MatchType.TEXT_CONENT // 调整匹配模式为 "文本包含"
    )
    // 如果需要，添加此注解来去除匹配用的文本前后的空白字符。
    // 由于 QQ 频道的公域 bot 都是需要被 at 的，
    // 而被 at 时，文本消息很有可能存在一些前后空格，所以会比较有用
    @ContentTrim
    public CompletableFuture<?> handle(ChatChannelMessageEvent event) {
      return event.replyAsync("你也好");
              // 当使用异步API (CompletableFuture) 时，
              // 你需要格外注意异常处理问题。
              // 如果你不 return，
              // 那么你就要处理异常，否则你无法感知到异步任务中出现的错误。
              // 比如：
              // .whenComplete((value, e) -> {
              //   if (e != null) {
              //     // 比如输出错误日志
              //   }
              // })
    }
  }
}

@EnableSimbot // 启用 simbot
@SpringBootApplication
public class MyApplication {
    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }

    @Component // 需要交给Spring管理
    public static class MyHandlers {
        @Listener // 标记事件处理函数
        @Filter(  // 简单的事件过滤注解
                value = "你好", // 需要包含的文字
                matchType = MatchType.TEXT_CONENT // 调整匹配模式为 "文本包含"
        )
        // 如果需要，添加此注解来去除匹配用的文本前后的空白字符。
        // 由于 QQ 频道的公域 bot 都是需要被 at 的，
        // 而被 at 时，文本消息很有可能存在一些前后空格，所以会比较有用
        @ContentTrim
        public void handle(ChatChannelMessageEvent event) {
            event.replyBlocking("你也好");
        }
    }
}

@EnableSimbot // 启用 simbot
@SpringBootApplication
public class MyApplication {
    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }

    @Component // 需要交给Spring管理
    public static class MyHandlers {
        @Listener // 标记事件处理函数
        @Filter(  // 简单的事件过滤注解
                value = "你好", // 需要包含的文字
                matchType = MatchType.TEXT_CONENT // 调整匹配模式为 "文本包含"
        )
        // 如果需要，添加此注解来去除匹配用的文本前后的空白字符。
        // 由于 QQ 频道的公域 bot 都是需要被 at 的，
        // 而被 at 时，文本消息很有可能存在一些前后空格，所以会比较有用
        @ContentTrim
        public Mono<?> handle(ChatChannelMessageEvent event) {
            return event.replyReserve("你也好")
                    // 使用此转化器需要确保运行时环境中存在 
                    // [[[kotlinx-coroutines-reactor|https://github.com/Kotlin/kotlinx.coroutines/tree/master/reactive]]] 的相关依赖。
                    .transform(SuspendReserves.mono());
                    // 当使用异步API (比如此处的 Mono) 时，
                    // 你需要格外注意异常处理问题。
                    // 如果你不 return，
                    // 那么你就要处理异常，否则你无法感知到异步任务中出现的错误。
                    // 比如：
                    // .doOnError(err -> {
                    //     // 比如输出错误日志
                    // });
        }
    }
}

此处以 "QQ频道的公域子频道At消息事件" 为例，此事件类型为 QGAtMessageCreateEvent。

这个事件是QQ频道组件里实现的专有事件类型，它继承 ChatChannelMessageEvent。