2022年第19周周报

2022年5月13日 · 阅读需 5 分钟

Simple Robot 首席吉祥物

2022年第19周周报喵。

🏗 重构

v3.0.0.preview.10.x 版本（也就是v3的第十个预览版本）的核心模块中的主要重构工作已经基本接近尾声。如果不出意外的话，本周内将会首先发布一个过渡性版本 v3.0.0.preview.9.x （也就是第九个预览版本）来进行一次过渡升级与问题收集。

第九预览

在第九预览版本中，将会更新在第十预览版本计划重构中的主要部分：有关"应用程序"、"组件"和启动的整体重构。在本次重构后，应用各模块（核心模块、Boot模块、SpringBoot模块）的应用程序将会有如下效果：

Simple
Boot
SpringBoot

最简示例
完整示例
扩展示例

launcher
create

App.kt
suspend fun main() {
    val launcher: ApplicationLauncher<SimpleApplication> = simbotApplication(Simple)
    val app: SimpleApplication = launcher.launch() 
    app.join()
}

App.kt
suspend fun main() {
    simbotApplication(Simple).launch().join()
}

App.kt
suspend fun main() {
    val app: SimpleApplication = createSimbotApplication(Simple)
    app.join()
}

App.kt
suspend fun main() {
    createSimbotApplication(Simple).join()
}

launcher
create
builder

App.kt
suspend fun main() {
    val launcher: ApplicationLauncher<SimpleApplication> = simbotApplication(
        factory = Simple,
        configurator = { // this: SimpleApplicationConfiguration
            logger = ...
            coroutineContext = ...
        }
    ) { // this: SimpleApplicationBuilder, it: SimpleApplicationConfiguration
        
        // 组件注册
        installAllComponents()
        // 事件提供者注册
        // BotManager也属于EventProvider
        installAllEventProviders()
        // 带配置的注册
        install(FooComponent) {
            // config for it
        }
        
        install(FooBotManager) // or ignore config
        
        // 全局通用的bot注册相关
        bots {
            val bot = register(...)
            register(...)?.start()
        }
        
        // 内置事件处理器配置
        eventProcessor {
            // 配置监听函数
            listeners {
                listener(myListener)
                listener(MessageEvent) {
                    isAsync = true | false
                    blockNext = true | false
                    logger = ...
                    handle { context, event ->
                        // ...
                    }
                }
                val myListener: EventListener = ...
                // plus listener
                +myListener
            }
            
            // 配置拦截器
            interceptors {
                // 监听函数拦截器
                listenerIntercept {
                    // ...
                }
                // 事件流程拦截器
                processingIntercept {
                    // ...
                }
            }
        }
        
        // 额外的扩展允许直接在此处定义监听函数
        listeners {
            listener(myListener)
            listener(MessageEvent) {
                handle { context, messageEvent ->
                    // ...
                }
            }
        }
        
        // 完成时的回调函数
        onCompletion {
            // ...
        }
    }
    
    val app: SimpleApplication = launcher.launch()
    app.join()
}

App.kt
suspend fun main() {
    val app: SimpleApplication = createSimbotApplication(
        factory = Simple,
        configurator = { // this: SimpleApplicationConfiguration
        
            // config block
            
        }
    ) { // this: SimpleApplicationBuilder, it: SimpleApplicationConfiguration
    
        // build block
        
    }
    
    app.join()
}

App.kt
suspend fun main() {
    val app: SimpleApplication = buildSimbotApplication(Simple) { 
            config { // this: SimpleApplicationConfiguration
            
                // config block
                
            }
            
            build { // this: SimpleApplicationBuilder, it: SimpleApplicationConfiguration
            
                // build block
                
            }
            
        }
    
    app.join()
}

launcher
create

App.kt
suspend fun main() {
    val launcher: ApplicationLauncher<SimpleApplication> = simpleApplication({
        // config block
    }) {
        // build block
    }
    
    val app: SimpleApplication = launcher.launch()
    app.join()
}

App.kt
suspend fun main() {
    val launcher = simpleApplication()
    val app = launcher.launch()
    app.join()
}

App.kt
suspend fun main() {
    simpleApplication().launch().join()
}

App.kt
suspend fun main() {
    val app: SimpleApplication = createSimpleApplication({
        // config block
    }) {
        // build block
    }
    
    app.join()
}

App.kt
suspend fun main() {
    val app = createSimpleApplication()
    app.join()
}

App.kt
suspend fun main() {
    createSimpleApplication().join()
}

最简示例
完整示例
扩展示例
快速启动示例

launcher
create

com/example/App.kt
suspend fun main() {
    val launcher: ApplicationLauncher<BootApplication> = simbotApplication(Boot)
    val launch: BootApplication = launcher.launch()
    launch.join()
}

com/example/App.kt
suspend fun main() {
    simbotApplication(Boot).launch().join()
}

com/example/App.kt
suspend fun main() {
    val app: BootApplication = createSimbotApplication(Boot)
    app.join()
}

com/example/App.kt
suspend fun main() {
    createSimbotApplication(Boot).join()
}

launcher
create
builder

com/example/App.kt
suspend fun main() {
    suspend fun main() {
    val launcher: ApplicationLauncher<BootApplication> = simbotApplication(
        factory = Boot,
        configurator = { // this: BootApplicationConfiguration
            logger = ...
            coroutineContext = ...
            
            // 用于各种资源扫描的类加载器
            classLoader = ...
            // 依赖类扫描包路径
            classesScanPackage = listOf("com.example")
            // 顶层函数形式的监听函数扫描
            topLevelListenerScanPackage = listOf("com.example")
            // 顶层函数的binder函数扫描
            topLevelBinderScanPackage = listOf("com.example")
            args = listOf("-foo", "-bar")
            // *.bot 资源文件扫描路径
            botConfigurationResources = listOf("simbot-bots/*.bot*")
            // 额外配置的*.bot 资源
            botConfigurations = listOf(File("xxx/fooBot.bot").toResource())
            // 是否自动启动扫描注册的bot
            isAutoStartBots = true
        }
    ) { // this: BootApplicationBuilder, it: BootApplicationConfiguration
        
        // 组件注册
        installAllComponents()
        
        // 事件提供者注册
        // BotManager也属于EventProvider
        installAllEventProviders()
        
        // 带配置的注册
        install(FooComponent) {
            // config for it
        }
        
        install(FooBotManager) // or ignore config
        
        // 对依赖注入内容的**额外**配置
        beans {
            bean("foo", Foo())
            bean("bar", Bar::class) { Bar() }
            scan("foo.example", "bar.example")
        }
        
        // 配置额外的binders
        binders {
            binder("foo-binder", FooBinderFactory)
            binder(BarBinderFactory)
        }
        
        
        // 全局通用的bot注册，与 Simple 几乎一致。只不过此处为配置文件扫描以外的内容。
        bots {
            // ...
        }
        
        // 事件处理器与 Simple 几乎一致。只不过此处配置的为bean扫描以外的内容。
        // 依赖管理功能会尝试自动扫描并注册相关的监听函数。
        eventProcessor {
            // ...
        }
        
        
        // 完成时的回调函数
        onCompletion {
            // ...
        }
    }
    
    val app: BootApplication = launcher.launch()
    app.join()
}

com/example/App.kt
suspend fun main() {
    val app: BootApplication = createSimbotApplication(
        factory = Boot,
        configurator = { // this: BootApplicationConfiguration
            // config block
        }
    ) { // this: BootApplicationBuilder, it: BootApplicationConfiguration
        // build block
    }
    
    app.join()
}

com/example/App.kt
suspend fun main() {
    val app: BootApplication = buildSimbotApplication(Boot) {
        config { // this: BootApplicationConfiguration
            // config block
        }
        build { // this: BootApplicationBuilder, it: BootApplicationConfiguration
            // build block
        }
    }
    
    app.join()
}

launcher
create

com/example/App.kt
suspend fun main() {
    val launcher: ApplicationLauncher<BootApplication> = bootApplication({
        // config block
    }) {
        // build block
    }
    
    val launch: BootApplication = launcher.launch()
    launch.join()
}

com/example/App.kt
suspend fun main() {
    val launcher = bootApplication()
    val launch = launcher.launch()
    launch.join()
}

com/example/App.kt
suspend fun main() {
    bootApplication().launch().join()
}

com/example/App.kt
suspend fun main() {
    val app: BootApplication = createBootApplication({
        // config block
    }) {
        // build block
    }
    
    app.join()
}

com/example/App.kt
suspend fun main() {
    val app = createBootApplication()
    app.join()
}

com/example/App.kt
suspend fun main() {
    createBootApplication().join()
}

Kotlin
Java

com/example/App.kt
import love.forte.simboot.core.SimbootApp
import love.forte.simboot.core.SimbootApplication

@SimbootApplication
class App

suspend fun main(vararg args: String) {
    val app = SimbootApp.run(App::class, args = args)
    app.join()
}

com/example/App.kt
import love.forte.simboot.core.SimbootApp
import love.forte.simboot.core.SimbootApplication
import love.forte.simboot.core.invoke

@SimbootApplication
class App

suspend fun main(vararg args: String) {
    val app = SimbootApp<App>(args = args)
    app.join()
}

com/example/App.kt
import love.forte.simboot.core.SimbootApp
import love.forte.simboot.core.SimbootApplication
import love.forte.simboot.core.invoke

@SimbootApplication
class App

suspend fun main(vararg args: String) {
    SimbootApp<App>(args = args).join()
}

com/example/App.kt
package com.example

import love.forte.simboot.core.SimbootApp


suspend fun main(vararg args: String) {
    SimbootApp.run(args = args).join()
}

com/example/App.java
@SimbootApplication
public class App {
    public static void main(String[] args) {
        final ApplicationLauncher<BootApplication> launcher = SimbootApp.run(App.class, args);
        final BootApplication application = launcher.launchBlocking();
        application.joinBlocking();
    }
}

com/example/App.java
public class App {
    public static void main(String[] args) {
        final ApplicationLauncher<BootApplication> launcher = SimbootApp.run(args);
        final BootApplication application = launcher.launchBlocking();
        application.joinBlocking();
    }
}

com/example/App.java
@SimbootApplication
public class App {
    public static void main(String[] args) {
        SimbootApp.run(App.class, args)
                .launchBlocking()
                .joinBlocking();
    }
}

com/example/App.java
public class App {
    public static void main(String[] args) {
        SimbootApp.run(args)
                .launchBlocking()
                .joinBlocking();
    }
}

备注

Spring Boot模块下不太建议通过前述的 simbotApplication { ... } 的方式来使用 ———— 这些行为将会由内部的Spring Boot配置来完成。

因此此处只提供快速开始示例。

快速开始示例

Kotlin
Java

com/example/SpringBootApp.kt
@EnableSimbot
@SpringBootApplication
class SpringBootApp


fun main(vararg args: String) {
    runApplication<SpringBootApp>(*args)
}

com/example/SpringBootApp.java
@EnableSimbot
@SpringBootApplication
public class SpringBootApp {
    public static void main(String[] args) {
        SpringApplication.run(SpringBootApp.class, args);
    }
}

其中，上述提到的 Simple、Boot、SpringBoot 都是 "应用程序工厂（ApplicationFactory）" 的一种实现，它们三个分别代表了原来的 核心模块 、 Boot模块 和 Spring Boot Starter模块。

而这其中的 "应用程序（ Application ）" 则是本次重构后所引入的新概念，也将会是后续作为simbot程序入口点的概念代理。

除了有关应用程序概念的产生之外，伴随着它的实现，Boot 模块和 Spring Boot Starter 模块的内部也产生了大量变化，以及还有一些伴随产生的新东西、被移除的旧东西等。有关这些内容，会在版本发布的时候详细列于更新日志中。

第十预览

第十预览中应该完成本次重构计划，而最终的重构计划中，除了在第九预览中所更新的"应用程序"以外，最主要的则是对 "持续会话" API的翻新。

这还是我们尚在议论的重构内容，还请稍作等待。

后续

在 v3.0.0.preview.10.x 重构、发布完成后，在后续一段时间内将会对目前的预览版本进行简单的测试与反馈收集，并继续向着更为完善的api定义继续更新。尚未列入上述重构计划内的待办事项中，还有：

针对于 权限与角色（Role） 相关API
Bot的 联系人 相关API
数据流返回值（Flow 、 Sequence 、Stream）兼容问题
其他未考虑到的问题

如此几项内容需要进行考虑与完善。

当上述问题都得到了较为妥善的答案之后，便会考虑停止当前的预览(preview)阶段，转而进入BETA阶段。

在BETA阶段，将会主要以优化、bugfix和仓库、文档完善为主，尽可能不再考虑大面积的重构作业。

🚀 版本更新

本周内没有什么主要的版本更新，但是预计会在本周内或下周初发布 v3.0.0.preview.9.0。不过在本周之前的5月8号， Mirai组件发布了一个上周周报未提及的版本 v3.0.0.0.preview.2.3，有兴趣的小伙伴可以去看看。

📖 文档更新

也许有些朋友可能会问："你们怎么还不完善文档🙏"，有关文档的完善问题，目前在 预览版本 阶段，api的定义可能会经常性的发生变化，文档内容准确性难以得到保证。并且文档的编撰需要消耗大量的精力来做，而目前团队的主要工作是尽快完成api的确定来为未来做保障。因此对于文档完善的优先级在预览阶段结束前都不会被提前。

对于文档内容的编写，预计会在beta版本或者正式版本发布后开始逐步提上日程。

尽管如此，在这周里，当前网站内依旧发生了一些变化——与文档和代码示例有关的变化。不知道细心的你有没有发现呢？

🏗 重构​

第九预览​

第十预览​

后续​

🚀 版本更新​

📖 文档更新​

🏗 重构

第九预览

第十预览

后续

🚀 版本更新

📖 文档更新