# 消息发送拦截

> For the complete documentation index, see [llms.txt](https://simbot.forte.love/llms.txt).

在 `MessageSendInterceptionPoint` 上注册拦截器，可以在组件提交消息前读取或替换消息和发送选项，也可以终止发送。发送 `send` 和回复 `reply` 共用这个拦截点。

## 注册

下面的拦截器去掉待发送纯文本的首尾空白。其他消息类型按原样交给下游。通过 `Application` 注册一次，即可覆盖该应用管理的、使用此拦截点的 Bot。Spring Boot 的注册方式见 [Spring Boot 集成](spring-boot.html#register-application-interceptors)。

Kotlin:

导入 `love.forte.simbot.application.interceptors` 和 `love.forte.simbot.interception.onMessageSend` 后，在应用启动后注册。

```KOTLIN
application.interceptors {
    onMessageSend { _, context, chain ->
        val text = context.message as? InteractionMessage.Text
        val next = if (text == null) context else {
            context.withMessage(InteractionMessage.valueOf(text.text.trim()))
        }
        chain.proceed(next)
    }
}
```

Java:

注册时显式传入优先级。下例中的 `Interceptors` 位于 `love.forte.simbot.interception`，响应式写法使用 Reactor 的 `Mono`。

```JAVA
application.getInterceptorManager().register(
        MessageSendInterceptionPoint.INSTANCE,
        PriorityConstant.DEFAULT,
        Interceptors.blocking((point, context, chain) -> {
            if (context.getMessage() instanceof InteractionMessage.Text) {
                var text = (InteractionMessage.Text) context.getMessage();
                context = context.withMessage(InteractionMessage.valueOf(text.getText().trim()));
            }
            return chain.proceed(context);
        }));
```

```JAVA
application.getInterceptorManager().register(
        MessageSendInterceptionPoint.INSTANCE,
        PriorityConstant.DEFAULT,
        Interceptors.async((point, context, chain) -> {
            if (context.getMessage() instanceof InteractionMessage.Text) {
                var text = (InteractionMessage.Text) context.getMessage();
                context = context.withMessage(InteractionMessage.valueOf(text.getText().trim()));
            }
            return chain.proceed(context);
        }));
```

```JAVA
application.getInterceptorManager().register(
        MessageSendInterceptionPoint.INSTANCE,
        PriorityConstant.DEFAULT,
        Interceptors.reactive((point, context, chain) -> {
            if (context.getMessage() instanceof InteractionMessage.Text) {
                var text = (InteractionMessage.Text) context.getMessage();
                context = context.withMessage(InteractionMessage.valueOf(text.getText().trim()));
            }
            return Mono.from(chain.proceed(context));
        }));
```

## 读取和替换上下文

拦截器的业务上下文是 `MessageSendContext`。普通发送、按 ID 直发和消息扩展发送都使用 `MessageSendContext.Send`，回复使用 `MessageSendContext.Reply`。需要读取平台特有信息时，可以进一步判断组件提供的上下文类型。

| 属性或方法 | 含义 |
| --- | --- |
| `bot` | 执行这次操作的 Bot。 |
| `source` | 发起操作的对象，类型为 `Any`。例如频道对象、消息事件、直发入口的 Bot，或调用扩展函数的消息对象。 |
| `destination` | 入口已知且读取时无副作用的目标描述，通常包含目标类别与 ID。无法提供描述时为 `null`。 |
| `target()` | 按需解析入口确定的目标实体。可能挂起、查询平台、抛出异常或返回 `null`，例如按 ID 直发时可能没有可用实体。 |
| `originalMessage` | 调用发送或回复入口时的消息。 |
| `message` | 当前将交给下游的消息。多层拦截器可以依次替换。 |
| `options` | `Send` 持有 `List<SendOption>`，`Reply` 持有 `List<ReplyOption>`。初始选项按原顺序保留调用方传入的内容。 |

`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](basic-event.html#message-sent-event)。

## 使用发送与回复选项

`MessageSendContext.Send` 提供发送选项，`MessageSendContext.Reply` 提供回复选项。可通过 `withOptions(...)` 传递新列表。若只改其中一项，把要保留的选项一并传入。发送终端按下游收到的列表解析选项，默认引用等组件参数在构造请求时补全。

选项类型、调用示例及标准选项的规则见 [发送与回复选项](basic-messages.html#send-options)。

## 适用范围

标准组件实现已将常规发送与回复入口接入拦截链。组件专用方法和原生请求入口的适用范围见对应的组件文档。直接使用通用 API 客户端请求平台接口时会绕过拦截链。

## 为组件接入消息拦截

在插件配置阶段从 `PluginConfigureContext.interceptorManager` 取得应用的管理器，并将它作为 `InterceptorContainer` 传给实际执行发送的对象。通常由 Bot 管理器传给各个 Bot。

针对公开发送或回复入口构造 `MessageSendContext.Send` 或 `Reply` 的实现。复制方法应保留组件字段与入口信息，构造和复制时应延迟到需要时再解析目标。每次逻辑发送只在外层调用一次 `MessageSendInterceptionPoint.invoke` 或 `invokeWithReceipt<R>`。入口承诺具体回执类型时使用 `invokeWithReceipt<R>`。委托方法、消息拆分后的平台请求和其他内部发送步骤直接执行。

发送终端使用收到的当前消息和选项，在构造平台请求时补全默认引用等组件参数。实际发送取得回执后，由组件在 Bot 作用域异步投递 `MessageSentEvent`，携带终端收到的上下文和实际回执。使用自定义拦截点的方式见 [通用拦截链](advanced-interceptor.html#custom-point)。

