Merge pull request #61 from simple-robot/dev/main

Release: v0.9.0
simple-robot · Jun 21, 2024 · 77c75dd · 77c75dd
2 parents 51d0e29 + dfd5cc4
commit 77c75dd
Show file tree

Hide file tree

Showing 17 changed files with 567 additions and 117 deletions.
diff --git a/.changelog/v0.9.0.md b/.changelog/v0.9.0.md
@@ -0,0 +1,7 @@
+> 对应核心版本: [**v4.0.1**](https://github.com/simple-robot/simpler-robot/releases/tag/v4.0.1)
+
+
+我们欢迎并期望着您的的[反馈](https://github.com/simple-robot/simbot-component-onebot/issues)或[协助](https://github.com/simple-robot/simbot-component-onebot/pulls)，
+感谢您的贡献与支持！
+
+也欢迎您为我们献上一颗 `star`，这是对我们最大的鼓励与认可！
diff --git a/Writerside/ob.tree b/Writerside/ob.tree
@@ -13,11 +13,12 @@
             <toc-element topic="onebot11-quick-start.md">
                 <toc-element topic="use-onebot11.md"/>
             </toc-element>
-            <toc-element topic="onebot11-bot-config.md"/>
             <toc-element topic="onebot11-event.md">
             </toc-element>
             <toc-element topic="onebot11-message.md"/>
-            <toc-element topic="onebot11-OneBotBot.md"/>
+            <toc-element topic="onebot11-OneBotBot.md">
+            </toc-element>
+            <toc-element topic="onebot11-bot-config.md"/>
             <toc-element topic="onebot11-actors.md">
                 <toc-element topic="onebot11-OneBotGroup.md"/>
                 <toc-element topic="onebot11-OneBotMember.md"/>

diff --git a/Writerside/topics/OneBot11.md b/Writerside/topics/OneBot11.md
@@ -13,3 +13,10 @@ OneBot组件选择使用
 作为事件订阅的方式。
 
 简单来说，就是不论是API交互还是事件订阅，都由OneBot组件作为**主动方**：主动发起HTTP请求、主动发起WebSocket连接。
+
+### 反向？
+
+如果你真的想要通过反向HTTP来接收事件推送，那么你需要自行搭建 HTTP 服务端，然后使用 `OneBotBot.push` 手动推送原始事件的JSON字符串。
+你可以前往参考 
+`OneBotBot` 的
+<a href="onebot11-OneBotBot.md#外部事件" /> 。
diff --git a/Writerside/topics/onebot11-OneBotBot.md b/Writerside/topics/onebot11-OneBotBot.md
@@ -68,8 +68,11 @@ Bot进行API请求时使用的HttpClient。
 <def id="prop-apiHost" title="apiHost">
 Bot进行API请求时使用的服务地址的host，来自配置信息。
 </def>
-<def id="prop-accessToken" title="accessToken">
-Bot进行API请求时使用的accessToken，来自配置信息。
+<def id="prop-apiAccessToken" title="apiAccessToken">
+Bot进行API请求时使用的 accessToken，来自配置信息。
+</def>
+<def id="prop-eventAccessToken" title="eventAccessToken">
+Bot进行事件订阅的ws连接请求时使用的 accessToken，来自配置信息。
 </def>
 <def id="prop-userId" title="userId">
 
@@ -469,3 +472,264 @@ public class MyComponent {
 有关事件的更多内容参考 
 <a href="onebot11-event.md" /> 。
 </warning>
+
+
+## 外部事件
+
+`OneBotBot` 提供了 `push(String)` 来允许直接从外部推送一个原始的事件字符串。
+
+<tabs group="code">
+<tab title="Kotlin" group-key="Kotlin">
+
+```Kotlin
+val json = """
+{
+    "time": 1515204254,
+    "self_id": 10001000,
+    "post_type": "message",
+    "message_type": "private",
+    "sub_type": "friend",
+    "message_id": 12,
+    "user_id": 12345678,
+    "message": "你好～",
+    "raw_message": "你好～",
+    "font": 456,
+    "sender": {
+        "nickname": "小不点",
+        "sex": "male",
+        "age": 18
+    }
+}
+"""
+
+bot.push(json).collect()
+```
+
+</tab>
+<tab title="Java" group-key="Java">
+
+```Java
+var json = """
+    {
+        "time": 1515204254,
+        "self_id": 10001000,
+        "post_type": "message",
+        "message_type": "private",
+        "sub_type": "friend",
+        "message_id": 12,
+        "user_id": 12345678,
+        "message": "你好～",
+        "raw_message": "你好～",
+        "font": 456,
+        "sender": {
+            "nickname": "小不点",
+            "sex": "male",
+            "age": 18
+        }
+    }
+    """
+
+// 推送并在异步中处理
+bot.pushAndLaunch(json);
+```
+
+由于 `bot.push` 返回的结果是 `Flow`, 因此 Java 中想要直接使用它会比较困难。
+你可以先通过 `Collectables.valueOf(flow)` 将其转化为 `Collectable` (与关系对象相关API的结果类型一样)，
+然后再做进一步操作。
+
+
+```java
+var collectable = Collectables.valueOf(flow);
+// 使用 collectAsync 异步遍历
+// 或者 Collectables 中提供的各种辅助API
+// 或者 transform 转化为其他的类型，比如响应式的 Flux
+```
+
+</tab>
+</tabs>
+
+> 示例JSON来自 
+> https://github.com/botuniverse/onebot-11/blob/master/communication/http-post.md 。
+
+这可以让你能够使用**反向事件推送**来接收事件，比如通过接收来自 HTTP 的事件推送请求。
+
+简单示例：
+
+<tabs>
+<tab title="Ktor">
+
+```kotlin
+suspend fun main() {
+    val application = launchSimpleApplication {
+        useOneBot11()
+    }
+    // 注册事件省略...
+
+    // 注册bot并启动
+    val bot = application.oneBot11Bots {
+        register {
+            // 内容省略
+        }.apply { start() }
+    }
+
+    // 启动一个Ktor Server
+    embeddedServer(Netty, port = 5959, module = { serverModule(bot) })
+        .start(wait = true)
+}
+
+fun io.ktor.server.application.Application.serverModule(bot: OneBotBot) {
+    routing {
+        post("/event") {
+            // 收到事件，推送并在异步中处理
+            // 你也可以选择直接 push(body).collect(), 
+            // 直到事件被完全处理后在返回
+            val body = call.receiveText()
+            bot.pushAndLaunch(body)
+
+            // 响应一个默认的空JSON结果
+            call.response.header(HttpHeaders.ContentType, "application/json")
+            call.respond("{}")
+        }
+    }
+}
+```
+
+</tab>
+<tab title="Spring Boot Web">
+
+```java
+@RestController
+public class MyController {
+    private final Application application;
+
+    // 一个简单的返回值类型，假设始终返回空JSON {}
+    public record Result() {
+    }
+
+    private static final Result OK = new Result();
+
+    public MyController(Application application) {
+        this.application = application;
+    }
+
+    /**
+     * 通过 /xxx/event 接收事件，
+     * xxx 为你bot配置的 uniqueBotId
+     */
+    @PostMapping("/{botId}/event")
+    public Result onEvent(@PathVariable String botId, @RequestBody String body) {
+        for (var botManager : application.getBotManagers()) {
+            if (botManager instanceof OneBotBotManager obManager) {
+                // 找到这个bot
+                var bot = obManager.find(Identifies.of(botId));
+                // 如果有就推送这个事件并退出寻找
+                if (bot != null) {
+                    // 推送事件并在异步中处理
+                    // 你也可以参考上面有关 Flux 和 Collectable 的说明
+                    // 来阻塞地等待事件处理完成后再返回
+                    bot.pushAndLaunch(body);
+                    break;
+                }
+            }
+        }
+
+        return OK;
+    }
+}
+```
+
+</tab>
+<tab title="Spring Boot WebFlux">
+
+<tabs>
+<tab title="异步处理">
+
+如果选择直接异步处理，那么其实跟 Spring Boot Web 的情况下没什么太大区别。
+
+```java
+@RestController
+public class MyController {
+    private final Application application;
+
+    public record Result() {
+    }
+
+    private static final Result OK = new Result();
+
+    public MyController(Application application) {
+        this.application = application;
+    }
+
+    /**
+     * 通过 /xxx/event 接收事件，
+     * xxx 为你bot配置的 uniqueBotId
+     */
+    @PostMapping("/{botId}/event")
+    public Mono<Result> onEvent(@PathVariable String botId, @RequestBody String body) {
+        for (var botManager : application.getBotManagers()) {
+            if (botManager instanceof OneBotBotManager obManager) {
+                // 找到这个bot
+                var bot = obManager.find(Identifies.of(botId));
+                // 如果有就推送这个事件并退出寻找
+                if (bot != null) {
+                    bot.pushAndLaunch(body);
+                    break;
+                }
+            }
+        }
+
+        return Mono.just(OK);
+    }
+}
+```
+
+</tab>
+<tab title="顺序响应式处理">
+
+```java
+@RestController
+public class MyController {
+    private final Application application;
+
+    public record Result() {
+    }
+
+    private static final Result OK = new Result();
+
+    public MyController(Application application) {
+        this.application = application;
+    }
+
+    /**
+     * 通过 /xxx/event 接收事件，
+     * xxx 为你bot配置的 uniqueBotId
+     */
+    @PostMapping("/{botId}/event")
+    public Mono<Result> onEvent(@PathVariable String botId, @RequestBody String body) {
+        for (var botManager : application.getBotManagers()) {
+            if (botManager instanceof OneBotBotManager obManager) {
+                // 找到这个bot
+                var bot = obManager.find(Identifies.of(botId));
+                // 如果有就推送这个事件并退出寻找
+                if (bot != null) {
+                    final var flow = bot.push(body);
+                    // 将 flow 转为 reactor 的 Flux
+                    // 需要添加依赖 [[[kotlinx-coroutines-reactor|https://github.com/Kotlin/kotlinx.coroutines/tree/master/reactive]]]
+                    return ReactorFlowKt
+                            .asFlux(flow)
+                            .then(Mono.just(OK));
+                }
+            }
+        }
+
+        // 没找到，直接返回
+        return Mono.just(OK);
+    }
+}
+```
+
+</tab>
+</tabs>
+
+</tab>
+</tabs>
diff --git a/Writerside/topics/onebot11-bot-config.md b/Writerside/topics/onebot11-bot-config.md
@@ -24,10 +24,15 @@ Bot配置文件通常情况下是配合Spring Boot starter的时候用的。
         "botUniqueId": "123456",
         // api地址，是个http/https服务器的路径，默认localhost:3000
         "apiServerHost": "http://localhost:3000",
-        // 订阅事件的服务器地址，是个ws/wss路径，默认localhost:3001
+        // 订阅事件的服务器地址，是个ws/wss路径，默认 `null`
+        // 如果为 `null` 则不会连接 ws 和订阅事件
         "eventServerHost": "ws://localhost:3001",
-        // 配置的 token，可以是null
-        "accessToken": null
+        // 配置的 token，可以是null, 代表同时配置 apiAccessToken 和 eventAccessToken
+        "accessToken": null,
+        // 用于API请求时用的 token，默认 null
+        "apiAccessToken": null,
+        // 用于连接事件订阅ws时用的 token，默认 null
+        "eventAccessToken": null
     },
     // 额外的可选配置
     // config本身以及其内的各项属性绝大多数都可省略或null

diff --git a/Writerside/topics/use-onebot11.md b/Writerside/topics/use-onebot11.md
@@ -7,8 +7,7 @@ switcher-label: JavaAPI风格
 ## 前期准备
 
 参考
-<a href="onebot11-quick-start.md"/>
-。
+<a href="onebot11-quick-start.md"/> 。
 
 ## 安装
 ### 安装组件库
@@ -420,7 +419,10 @@ public static void configure(Application application) {
     botConfiguration.setEventServerHost(URLUtilsKt.Url("ws://localhost:3001"));
     // 其他配置, 一般都是可选属性
     /// token
-    botConfiguration.setAccessToken(null);
+    botConfiguration.accessToken(null);
+    // 或
+    botConfiguration.setApiAccessToken(null);
+    botConfiguration.setEventAccessToken(null);
     /// ...
 
     // 注册
@@ -482,7 +484,10 @@ public static void configure(Application application) {
     botConfiguration.setEventServerHost(URLUtilsKt.Url("ws://localhost:3001"));
     // 其他配置, 一般都是可选属性
     /// token
-    botConfiguration.setAccessToken(null);
+    botConfiguration.accessToken(null);
+    // 或
+    botConfiguration.setApiAccessToken(null);
+    botConfiguration.setEventAccessToken(null);
     /// ...
 
     // 注册
@@ -545,7 +550,10 @@ public static void configure(Application application) {
     botConfiguration.setEventServerHost(URLUtilsKt.Url("ws://localhost:3001"));
     // 其他配置, 一般都是可选属性
     /// token
-    botConfiguration.setAccessToken(null);
+    botConfiguration.accessToken(null);
+    // 或
+    botConfiguration.setApiAccessToken(null);
+    botConfiguration.setEventAccessToken(null);
     /// ...
 
     // 注册

diff --git a/Writerside/v.list b/Writerside/v.list
@@ -7,7 +7,7 @@
     <var name="jb" value="阻塞"/>
     <var name="ja" value="异步"/>
     <var name="jr" value="响应式"/>
-    <var name="version" value="0.8.0"/>
+    <var name="version" value="0.9.0"/>
     <var name="d-group" value="love.forte.simbot.component"/>
     <var name="d-ob11-id" value="simbot-component-onebot-v11"/>
     <var name="minimum-core-version" value="4.0.1"/>

diff --git a/buildSrc/src/main/kotlin/P.kt b/buildSrc/src/main/kotlin/P.kt
@@ -41,7 +41,7 @@ object P {
         override val homepage: String get() = HOMEPAGE
 
 
-        private val baseVersion = v(0, 8, 0)
+        private val baseVersion = v(0, 9, 0)
 
         val snapshotVersion = baseVersion - Version.SNAPSHOT
         override val version = if (isSnapshot()) snapshotVersion else baseVersion