中间件

class ehforwarderbot.Middleware(instance_id=None)

中间件类。

middleware_id

中间件的唯一标识符。ID 的命名规范在打包与发布中有说明。在适当的时候，这个 ID 将被附加实例 ID。

类型

str

middleware_name

人类可以识别的中间件名称。

类型

str

instance_id

实例 ID（若可用）。

类型

str

__init__(instance_id=None)

初始化中间件。继承初始化方法必须（MUST）在最初调用父类的初始化方法。

参数

instance_id (Optional[NewType()(InstanceID, str)]) – 中间件的实例 ID。

get_extra_functions()

获取附加功能列表

返回

被标记为附加功能的方法的字典。这些方法可以通过 get_extra_functions()["methodName"]() 调用。

返回类型

Dict[str, Callable]

process_message(message)

通过中间件处理一条消息

参数

message (Message) – 待处理的消息对象

返回

已处理的消息，如果丢弃消息则为 None。

返回类型

Optional[Message]

process_status(status)

通过中间件处理状态更新

参数

status (Status) – 待处理的消息对象

返回

已处理的消息，如果被丢弃则为 None。

返回类型

Optional[Status]

关于中间件 ID

随着实例 ID 的引入，在程序代码中需要使用中间件 ID 时，如检索配置文件的路径等情况时，需动态调用 self.middleware_id 或其他等效变量，避免任何硬编码或常量 ID。

通过主端接收用户命令

尽管我们没有限制用户与中间件交互的方法，我们仍提供了两种通过主端使用中间件的常用方式。

捕捉消息

对于面向特定会话的操作，您可以捕获匹配特定规则的消息。请确保规则的唯一性来保证您不会意外地捕获到本应发送至会话的消息。

您也可以构造一个虚拟的「系统」会话或会话成员来回应用户。

「附加功能」

如果该操作并非针对某会话，而是应用于系统整体，和从端一样，我们为中间件提供了类命令行的接口。详细内容请参考附加功能。

特定会话内的交互

中间件可以通过捕获消息来与特定的会话进行交互，并通过中间件创建的会话成员回复这些消息。

以下代码是通过捕获消息与用户交互的中间件示例。

当主端发送以 time` 开头的文本消息时，中间件会捕获此消息，并回复会话名称和服务器的当前时间。捕获的消息不会传递到任何后面中间件或从端。

def process_message(self: Middleware, message: Message) -> Optional[Message]:
    if message.deliver_to != coordinator.master and \  # 从主端发送
        text.startswith('time`'):

        # 创建系统会话成员
        # 有关 `make_system_member()` 与 `add_system_member()` 的区别
        # 请参阅上文描述
        author = message.chat.make_system_member(
            uid="__middleware_example_time_reporter__",
            name="报时员",
            middleware=self
        )

        # 构建回复消息
        reply = Message(
            uid=f"__middleware_example_{uuid.uuid4()}__",
            text=f"您好！这里是{message.chat.name}。现在时间是{datetime.now().strftime('%c')}。",
            chat=chat,
            author=author,  # 使用刚刚创建的系统成员
            type=MsgType.Text,
            target=message,  # 引用回复发来的消息
            deliver_to=coordinator.master  # 发送消息给主端
        )
        # 将消息传送回主端。
        coordinator.send_message(reply)

        # 捕获此消息，避免将其传送给后面的中间件或从端
        return None

    # 若没有匹配到上面规则，则继续传递此消息
    return message