消息发送拦截
在 MessageSendInterceptionPoint 上注册拦截器,可以在组件提交消息前读取或替换消息和发送选项,也可以终止发送。发送 send 和回复 reply 共用这个拦截点。
注册
下面的拦截器去掉待发送纯文本的首尾空白。其他消息类型按原样交给下游。通过 Application 注册一次,即可覆盖该应用管理的、使用此拦截点的 Bot。Spring Boot 的注册方式见 Spring Boot 集成。
导入 love.forte.simbot.application.interceptors 和 love.forte.simbot.interception.onMessageSend 后,在应用启动后注册。
注册时显式传入优先级。下例中的 Interceptors 位于 love.forte.simbot.interception ,响应式写法使用 Reactor 的 Mono。
读取和替换上下文
拦截器的业务上下文是 MessageSendContext 。普通发送、按 ID 直发和消息扩展发送都使用 MessageSendContext.Send ,回复使用 MessageSendContext.Reply 。需要读取平台特有信息时,可以进一步判断组件提供的上下文类型。
属性或方法 | 含义 |
|---|---|
| 执行这次操作的 Bot。 |
| 发起操作的对象,类型为 |
| 入口已知且读取时无副作用的目标描述,通常包含目标类别与 ID。无法提供描述时为 |
| 按需解析入口确定的目标实体。可能挂起、查询平台、抛出异常或返回 |
| 调用发送或回复入口时的消息。 |
| 当前将交给下游的消息。多层拦截器可以依次替换。 |
|
|
InteractionMessage.valueOf(...) 可包装字符串、 Message 或 MessageContent 。组件也可以用 InteractionMessage.Extension 包装原生请求。调用 withMessage(...) 或 withOptions(...) 后,将返回的上下文传给 chain.proceed(...) 。副本保留具体上下文类型、Bot、来源、原始消息和入口目标信息。 withOptions(...) 会复制传入的集合。
当组件允许替换带有目标字段的原生请求时,实际请求的目标可以变化。 destination 和 target() 仍按入口确定的目标提供信息。只需判断目标类别或 ID 时,优先读取 destination 。Java 可按所用 API 风格调用 targetBlocking()、 targetAsync() 或 targetReactive()。
放行、短路与回执
建议每层至多调用一次
chain.proceed(context)。重复调用会重新执行后续链,可能导致重复发送。在拦截器中再次调用send或reply会开启一条新链,应避免由此递归进入同一拦截器。需要阻止发送时,可以在调用
proceed前抛出业务异常。异常和取消向调用方传播,尚未执行的下游和发送逻辑会被跳过。常规放行直接返回
proceed的结果。短路返回或替换回执时,必须满足当前入口声明的非空回执类型。组件在整条链返回后校验一次最终类型,类型不符会抛出IllegalStateException。若下游已经发送,遇到此异常时应先确认结果再决定是否重试。proceed返回的是下游链的结果,下游也可能短路。要观察实际发送成功,监听MessageSentEvent。
使用发送与回复选项
MessageSendContext.Send 提供发送选项, MessageSendContext.Reply 提供回复选项。可通过 withOptions(...) 传递新列表。若只改其中一项,把要保留的选项一并传入。发送终端按下游收到的列表解析选项,默认引用等组件参数在构造请求时补全。
选项类型、调用示例及标准选项的规则见 发送与回复选项。
适用范围
标准组件实现已将常规发送与回复入口接入拦截链。组件专用方法和原生请求入口的适用范围见对应的组件文档。直接使用通用 API 客户端请求平台接口时会绕过拦截链。
为组件接入消息拦截
在插件配置阶段从 PluginConfigureContext.interceptorManager 取得应用的管理器,并将它作为 InterceptorContainer 传给实际执行发送的对象。通常由 Bot 管理器传给各个 Bot。
针对公开发送或回复入口构造 MessageSendContext.Send 或 Reply 的实现。复制方法应保留组件字段与入口信息,构造和复制时应延迟到需要时再解析目标。每次逻辑发送只在外层调用一次 MessageSendInterceptionPoint.invoke 或 invokeWithReceipt<R> 。入口承诺具体回执类型时使用 invokeWithReceipt<R> 。委托方法、消息拆分后的平台请求和其他内部发送步骤直接执行。
发送终端使用收到的当前消息和选项,在构造平台请求时补全默认引用等组件参数。实际发送取得回执后,由组件在 Bot 作用域异步投递 MessageSentEvent ,携带终端收到的上下文和实际回执。使用自定义拦截点的方式见 通用拦截链。