Merge pull request #896 from simple-robot/optimize-895

优化统一MergedBinder对null结果、失败结果的处理

simbot-cores/simbot-core-spring-boot-starter/src/test/kotlin/love/forte/simbot/spring/test/DefaultBinderTests.kt

@@ -0,0 +1,178 @@
+/*
+ *     Copyright (c) 2024. ForteScarlet.
+ *
+ *     Project    https://github.com/simple-robot/simpler-robot
+ *     Email      [email protected]
+ *
+ *     This file is part of the Simple Robot Library (Alias: simple-robot, simbot, etc.).
+ *
+ *     This program is free software: you can redistribute it and/or modify
+ *     it under the terms of the GNU Lesser General Public License as published by
+ *     the Free Software Foundation, either version 3 of the License, or
+ *     (at your option) any later version.
+ *
+ *     This program is distributed in the hope that it will be useful,
+ *     but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *     Lesser GNU General Public License for more details.
+ *
+ *     You should have received a copy of the Lesser GNU General Public License
+ *     along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ *
+ */
+
+package love.forte.simbot.spring.test
+
+import io.mockk.every
+import io.mockk.mockk
+import kotlinx.coroutines.flow.toList
+import kotlinx.coroutines.runBlocking
+import love.forte.simbot.application.Application
+import love.forte.simbot.event.*
+import love.forte.simbot.quantcat.common.annotations.Filter
+import love.forte.simbot.quantcat.common.annotations.FilterValue
+import love.forte.simbot.quantcat.common.annotations.Listener
+import love.forte.simbot.spring.EnableSimbot
+import org.springframework.beans.factory.annotation.Autowired
+import org.springframework.boot.test.context.SpringBootTest
+import org.springframework.stereotype.Component
+import kotlin.test.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertFails
+import kotlin.test.assertNull
+
+
+/**
+ * 测试来源：https://github.com/simple-robot/simpler-robot/issues/895
+ *
+ * @author ForteScarlet
+ */
+@SpringBootTest(
+    classes = [
+        DefaultBinderTests::class,
+        TestListenerContainer::class,
+    ]
+)
+@EnableSimbot
+open class DefaultBinderTests {
+
+    @Test
+    fun binderTest1(
+        @Autowired application: Application
+    ) {
+        fun Event.push(): List<EventResult> {
+            return runBlocking {
+                application.eventDispatcher.push(this@push)
+                    .throwIfError()
+                    .filterNotInvalid()
+                    .toList()
+            }
+        }
+
+        // test1: 应当得到 page=1, 因为匹配内容 page 实际不存在，使用默认值
+        mockk<MessageEvent>(relaxed = true) {
+            every { messageContent.plainText } returns "test_1 1"
+            assertEquals(1, push().first().content)
+        }
+
+        // test2(1): 符合匹配结果，应当得到 1
+        mockk<MessageEvent>(relaxed = true) {
+            every { messageContent.plainText } returns "test_2 1"
+            assertEquals("1", push().first().content)
+        }
+
+        // test2(2): 不符合匹配结果、不是required=false，理应报错
+        mockk<MessageEvent>(relaxed = true) {
+            every { messageContent.plainText } returns "test_2"
+            assertFails { push() }
+        }
+
+        // test3(1): 不符合匹配结果、不是required=false，但参数是可选的，使用默认值，即得到 null
+        mockk<MessageEvent>(relaxed = true) {
+            every { messageContent.plainText } returns "test_3"
+            assertNull(push().first().content)
+        }
+
+        // test3(2): 符合匹配结果、得到 "1"
+        mockk<MessageEvent>(relaxed = true) {
+            every { messageContent.plainText } returns "test_3 1"
+            assertEquals("1", push().first().content)
+        }
+
+        // test4(1): 不符合匹配结果、是required=false，参数是可选的，使用默认值，即得到 null
+        mockk<MessageEvent>(relaxed = true) {
+            every { messageContent.plainText } returns "test_4"
+            assertNull(push().first().content)
+        }
+
+        // test4(2): 符合匹配结果、得到 1
+        mockk<MessageEvent>(relaxed = true) {
+            every { messageContent.plainText } returns "test_4 1"
+            assertEquals(1, push().first().content)
+        }
+
+        // test5(1): 不符合匹配结果、不是required=false，参数是可选的，使用默认值，即得到 1
+        mockk<MessageEvent>(relaxed = true) {
+            every { messageContent.plainText } returns "test_5"
+            assertEquals(1, push().first().content)
+        }
+
+        // test5(2): 符合匹配结果、得到 2
+        mockk<MessageEvent>(relaxed = true) {
+            every { messageContent.plainText } returns "test_5 2"
+            assertEquals(2, push().first().content)
+        }
+
+        // test6(1): 不符合匹配结果、是required=false，参数是可选的，但是参数是可以为null的，因此会填充 null 而不是默认值
+        mockk<MessageEvent>(relaxed = true) {
+            every { messageContent.plainText } returns "test_6"
+            assertNull(push().first().content)
+        }
+
+        // test6(2): 符合匹配结果、得到 2
+        mockk<MessageEvent>(relaxed = true) {
+            every { messageContent.plainText } returns "test_6 2"
+            assertEquals(2, push().first().content)
+        }
+    }
+
+}
+
+@Component
+class TestListenerContainer {
+    @Listener
+    @Filter("^test_1(\\s+(?<page>\\d+))?")
+    fun MessageEvent.handle1(
+        @FilterValue("page", false) page: Int = 1
+    ): Int = page
+
+    @Listener
+    @Filter("^test_2(\\s+(?<page>\\d+))?")
+    fun MessageEvent.handle2(
+        @FilterValue("page") page: String?
+    ): String? = page
+
+    @Listener
+    @Filter("^test_3(\\s+(?<page>\\d+))?")
+    fun MessageEvent.handle3(
+        @FilterValue("page") page: String? = null
+    ): String? = page
+
+    @Listener
+    @Filter("^test_4(\\s+(?<page>\\d+))?")
+    fun MessageEvent.handle4(
+        @FilterValue("page", false) page: Int? = null
+    ): Int? = page
+
+    @Listener
+    @Filter("^test_5(\\s+(?<page>\\d+))?")
+    fun MessageEvent.handle5(
+        @FilterValue("page") page: Int = 1
+    ): Int = page
+
+    @Listener
+    @Filter("^test_6(\\s+(?<page>\\d+))?")
+    fun MessageEvent.handle6(
+        @FilterValue("page", false) page: Int? = 1
+    ): Int? = page
+}

simbot-quantcat/simbot-quantcat-common/src/commonMain/kotlin/love/forte/simbot/quantcat/common/annotations/FilterValue.kt

@@ -4,7 +4,7 @@
  *     Project    https://github.com/simple-robot/simpler-robot
  *     Email      [email protected]
  *
- *     This file is part of the Simple Robot Library.
+ *     This file is part of the Simple Robot Library (Alias: simple-robot, simbot, etc.).
  *
  *     This program is free software: you can redistribute it and/or modify
  *     it under the terms of the GNU Lesser General Public License as published by
@@ -26,14 +26,17 @@ package love.forte.simbot.quantcat.common.annotations
 import love.forte.simbot.quantcat.common.filter.FilterValueProperties
 
 /**
- * 指定一个参数，此参数为通过 [love.forte.simbot.quantcat.annotations.Filter]
+ * 指定一个参数，此参数为通过 [love.forte.simbot.quantcat.common.annotations.Filter]
  * 解析而得到的动态参数提取器中的内容。
  *
  * 参数提取格式基于正则匹配模式，参考 [Filter.value] 中的相关说明。
  *
  * @param value 所需动态参数的key。
  * @param required 对于参数绑定器来讲其是否为必须的。
- *  如果不是必须的，则在无法获取参数后传递null作为结果，否则将会抛出异常并交由后续绑定器处理。
+ * 如果不是必须的，则在无法获取参数后传递 `null` 作为结果
+ * (此结果被视为正确结果。换言之如果参数为 `nullable`，
+ * 但是存在一个不是 `null` 的默认值，则最终的参数值依然为 `null`)，
+ * 否则将会抛出异常并交由后续绑定器处理。
  */
 @Target(AnnotationTarget.VALUE_PARAMETER)
 public annotation class FilterValue(val value: String, val required: Boolean = true)

simbot-quantcat/simbot-quantcat-common/src/commonMain/kotlin/love/forte/simbot/quantcat/common/binder/ParameterBinder.kt

@@ -4,7 +4,7 @@
  *     Project    https://github.com/simple-robot/simpler-robot
  *     Email      [email protected]
  *
- *     This file is part of the Simple Robot Library.
+ *     This file is part of the Simple Robot Library (Alias: simple-robot, simbot, etc.).
  *
  *     This program is free software: you can redistribute it and/or modify
  *     it under the terms of the GNU Lesser General Public License as published by
@@ -30,6 +30,10 @@ import love.forte.simbot.event.EventListenerContext
  *
  * 对于一个可执行函数的参数 `KParameter` 所需的结果获取器。
  *
+ * 没有任何绑定器时，
+ * 通常会使用 [EmptyBinder][love.forte.simbot.quantcat.common.binder.impl.EmptyBinder]，
+ * 当存在多个绑定器时，通常会使用 [MergedBinder][love.forte.simbot.quantcat.common.binder.impl.MergedBinder]。
+ *
  */
 public interface ParameterBinder {
     /**

simbot-quantcat/simbot-quantcat-common/src/jvmMain/kotlin/love/forte/simbot/quantcat/common/binder/impl/DefaultBinders.kt

@@ -32,7 +32,11 @@ import kotlin.reflect.KParameter
 
 
 /**
- * 将会直接抛出错误的binder。
+ * 默认的空内容绑定器。
+ *
+ * - 当参数可选时，使用 [ParameterBinder.Ignore] 标记其直接使用默认值。
+ * - 当参数标记为 nullable 时，直接提供 `null`。
+ * - 否则，[arg] 将会返回一个 [BindException] 的 [Result.failure] 表示失败。
  */
 public class EmptyBinder(
     private val parameter: KParameter,
@@ -63,6 +67,11 @@ public class EmptyBinder(
 
 /**
  * 组合多个binder的 [ParameterBinder].
+ *
+ * 在聚合绑定器中，会依次对所有的 [binders] 和 [spare] 使用 [ParameterBinder.arg] 来评估本次应绑定的参数，
+ * 知道遇到第一个返回为 [Result.isSuccess] 的结果后终止评估并使用此结果。
+ *
+ * 评估过程的详细描述参考 [arg] 文档说明。
  */
 public class MergedBinder(
     private val binders: List<ParameterBinder>, // not be empty
@@ -81,7 +90,24 @@ public class MergedBinder(
         require(binders.isNotEmpty()) { "'binders' must not be empty" }
     }
 
-
+    /**
+     *
+     * 使用内部所有的聚合 binder 对 [context] 进行评估并选出一个最先出现的可用值。
+     *
+     * 评估过程中：
+     *
+     * - 如果参数不可为 `null`、评估结果为成功但是内容为 `null`、同时参数是可选的，
+     * 则会忽略此结果，视为无结果。
+     * - 如果评估结果为失败，则暂记此异常，并视为无结果。
+     *
+     * 期间，遇到任何成功的、不符合上述会造成“无结果”条件的，
+     * 直接返回此评估结果，不再继续评估。
+     *
+     * 当所有binder评估完成，但没有遇到任何结果：
+     *
+     * - 如果参数为可选，输出debug日志并使用 [ParameterBinder.Ignore] 标记直接使用默认值。
+     * - 否则，返回 [Result.failure] 错误结果，并追加之前暂记的所有异常堆栈。
+     */
     @Suppress("ReturnCount")
     override fun arg(context: EventListenerContext): Result<Any?> {
         var err: Throwable? = null
@@ -91,7 +117,17 @@ public class MergedBinder(
             val result = arg(context)
             if (result.isSuccess) {
                 // if success, return.
-                return result
+                // 如果参数不可为 null、结果成功但是为 null、同时参数是可选的，
+                // 则返回 `null` 以忽略此参数。
+                return if (
+                    result.getOrNull() == null &&
+                    !parameter.type.isMarkedNullable &&
+                    parameter.isOptional
+                ) {
+                    null
+                } else {
+                    result
+                }
             }
             // failure
             val resultErr = result.exceptionOrNull()!!