CoolQ HTTP API 事件过滤器深度解析与应用指南

CoolQ HTTP API 事件过滤器深度解析与应用指南

什么是事件过滤器

CoolQ HTTP API 的事件过滤器是一种强大的消息筛选机制，它允许开发者通过定义规则来精确控制哪些事件需要上报到业务系统。通过事件过滤器，可以显著减少不必要的网络传输和业务处理，提高系统效率。

为什么需要事件过滤器

在实际应用中，机器人可能会接收到大量不同类型的事件消息，但业务系统往往只需要处理其中的一部分。例如：

• 只需要处理特定群组的消息
• 只需要处理特定格式的指令
• 需要排除某些用户的消息
• 需要组合多种条件进行筛选

事件过滤器正是为解决这些问题而设计的，它可以在消息上报前进行过滤，只让符合条件的事件进入业务处理流程。

过滤器配置基础

要启用事件过滤器，需要在配置文件中进行简单设置：

event_filter = filter.json

这个配置指定了过滤规则文件的路径，文件必须使用 JSON 格式编写。如果文件不存在或格式错误，插件将暂停所有事件上报。

过滤器语法详解

基本匹配规则

过滤规则的核心是一个 JSON 对象，每个键值对代表一个匹配条件：

• 普通键：直接匹配事件对象的对应字段
• 点号开头的键：表示运算符，用于特殊匹配逻辑

常用运算符解析

1. 逻辑运算符

   • .not：逻辑非
   • .and：逻辑与
   • .or：逻辑或（参数为数组）

2. 比较运算符

   • .eq：等于
   • .neq：不等于
   • .in：包含于（参数可以是字符串或数组）

3. 字符串运算符

   • .contains：包含子串
   • .regex：正则表达式匹配

运算符适用性

| 运算符 | 参数类型 | 适用数据类型 | |------------|---------------|-------------------| | .not | 对象 | 任意类型 | | .and | 对象 | 对象或全运算符 | | .or | 对象数组 | 任意类型 | | .eq | 任意 | 任意类型 | | .neq | 任意 | 任意类型 | | .in | 字符串/数组 | 字符串/任意类型 | | .contains| 字符串 | 字符串 | | .regex | 字符串 | 字符串 |

实用案例解析

案例1：指令消息过滤

{
    "raw_message": {
        ".regex": "^!!"
    }
}

这个规则只匹配以"!!"开头的消息，非常适合用于指令式机器人，可以过滤掉普通聊天内容。

案例2：群组消息精准控制

{
    "message_type": "group",
    "group_id": {
        ".in": [123456, 789012]
    },
    "user_id": {
        ".neq": 999999
    }
}

这个规则实现了：

1. 只处理群组消息
2. 只处理指定群组(123456和789012)
3. 排除用户999999的消息

案例3：复杂逻辑组合

{
    ".or": [
        {
            "message_type": "private",
            "user_id": {
                ".not": {
                    ".in": [11111, 22222]
                }
            }
        },
        {
            "message_type": "group",
            "raw_message": {
                ".contains": "紧急"
            }
        }
    ]
}

这个规则实现了：

1. 接收所有私聊消息，除了用户11111和22222
2. 接收所有群组中包含"紧急"字样的消息

高级技巧与注意事项

1. 性能优化：

   • 将最可能过滤掉大量消息的条件放在前面
   • 避免过于复杂的嵌套逻辑

2. 调试建议：

   • 先使用宽松的规则，逐步收紧
   • 可以通过日志验证过滤效果

3. 特殊字段说明：

   • raw_message 包含原始CQ码格式的消息
   • message 字段始终是消息段数组形式
   • 匿名消息相关字段需要特殊处理

4. 错误处理：

   • 语法错误会导致所有上报暂停
   • 类型不匹配会导致条件不通过

总结

CoolQ HTTP API 的事件过滤器是一个功能强大且灵活的工具，通过合理配置可以显著提高机器人系统的效率。掌握过滤器的使用技巧，能够帮助开发者构建更加精准、高效的消息处理系统。建议从简单规则开始，逐步构建复杂的过滤逻辑，并在实际使用中不断优化调整。