Golang高性能消息事件过滤与模式匹配插件Quamina的使用

Quamina简介

Quamina是一个高性能的模式匹配库，实现了以下功能：

• 创建实例并添加多个模式(Patterns)
• 查询数据对象(Events)以发现哪些模式匹配事件中的字段
• 在典型情况下，即使添加了许多模式，Quamina也能每秒匹配数百万个事件
• 无运行时依赖，仅使用Go内置库

基本概念

模式(Patterns)

模式是用来匹配事件的JSON结构。例如对于以下JSON事件：

{
  "Image": {
    "Width":  800,
    "Height": 600,
    "Title":  "View from 15th Floor",
    "Thumbnail": {
      "Url":    "http://www.example.com/image/481989943",
      "Height": 125,
      "Width":  100
    },
    "Animated" : false,
    "IDs": [116, 943, 234, 38793]
  }
}

以下模式都能匹配它：

{"Image": {"Width": [800]}}
{"Image": {"Title": [ { "exists": true } ] } }
{"Image": {"Thumbnail": { "Url": [ { "wildcard": "*9943" } ] } }}

模式语法规则

1. 模式的结构(字段名和嵌套)必须与要匹配的事件结构相同
2. 字段值总是以数组形式给出
3. 如果事件中的字段是数组值，当数组交集非空时匹配成功
4. 模式中未提及的字段默认匹配，但所有提到的字段必须匹配

使用示例

基本用法

package main

import (
	"fmt"
	"log"
	
	"github.com/timbray/quamina"
)

func main() {
	// 1. 创建Quamina实例
	q, err := quamina.New()
	if err != nil {
		log.Fatal(err)
	}

	// 2. 添加模式
	// 模式1: 匹配Image.Width为800的事件
	err = q.AddPattern("pattern1", `{"Image": {"Width": [800]}}`)
	if err != nil {
		log.Fatal(err)
	}
	
	// 模式2: 匹配Image.Title存在的事件
	err = q.AddPattern("pattern2", `{"Image": {"Title": [{"exists": true}]}}`)
	if err != nil {
		log.Fatal(err)
	}

	// 3. 定义要匹配的事件
	event := `{
		"Image": {
			"Width": 800,
			"Height": 600,
			"Title": "View from 15th Floor",
			"Thumbnail": {
				"Url": "http://www.example.com/image/481989943",
				"Height": 125,
				"Width": 100
			},
			"Animated": false,
			"IDs": [116, 943, 234, 38793]
		}
	}`

	// 4. 匹配事件
	matches, err := q.MatchesForEvent([]byte(event))
	if err != nil {
		log.Fatal(err)
	}

	// 5. 输出匹配结果
	fmt.Println("匹配的模式ID:")
	for _, match := range matches {
		fmt.Println(match)
	}
}

高级用法

package main

import (
	"fmt"
	"log"
	
	"github.com/timbray/quamina"
)

func main() {
	// 1. 创建Quamina实例，支持模式删除
	q, err := quamina.New(quamina.WithPatternDeletion(true))
	if err != nil {
		log.Fatal(err)
	}

	// 2. 添加多个模式
	patterns := map[string]string{
		"width800":  `{"Image": {"Width": [800]}}`,
		"height600": `{"Image": {"Height": [600]}}`,
		"titleExists": `{"Image": {"Title": [{"exists": true}]}}`,
		"urlWildcard": `{"Image": {"Thumbnail": {"Url": [{"wildcard": "*example.com*"}]}}}`,
	}

	for id, pattern := range patterns {
		err = q.AddPattern(id, pattern)
		if err != nil {
			log.Fatal(err)
		}
	}

	// 3. 测试事件
	events := []string{
		`{"Image": {"Width": 800}}`,
		`{"Image": {"Height": 600, "Title": "Test"}}`,
		`{"Image": {"Thumbnail": {"Url": "http://www.example.com/image"}}}`,
		`{"Image": {"Width": 100}}`,
	}

	// 4. 匹配每个事件
	for i, event := range events {
		fmt.Printf("\n事件 %d: %s\n", i+1, event)
		matches, err := q.MatchesForEvent([]byte(event))
		if err != nil {
			log.Fatal(err)
		}
		
		fmt.Println("匹配的模式:")
		for _, match := range matches {
			fmt.Println("-", match)
		}
	}

	// 5. 删除一个模式
	fmt.Println("\n删除'width800'模式...")
	err = q.DeletePatterns("width800")
	if err != nil {
		log.Fatal(err)
	}

	// 6. 再次测试第一个事件
	fmt.Println("\n再次测试第一个事件...")
	matches, err := q.MatchesForEvent([]byte(events[0]))
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("匹配的模式:", matches)
}

性能特点

1. 模式添加性能：每秒可添加数万个模式到Quamina实例
2. 事件匹配性能：
   • 性能与模式数量基本无关(O(1))
   • 主要取决于事件中需要检查的字段数量
   • 典型情况下可达每秒数百万次匹配
3. 通配符模式：大量使用wildcard模式会影响性能

并发使用

单个Quamina实例不能安全地被多个goroutine同时使用，但可以使用Copy()方法创建副本：

// 创建副本
qCopy := q.Copy()

// 在另一个goroutine中使用副本
go func() {
    matches, err := qCopy.MatchesForEvent(eventData)
    // 处理结果...
}()

模式匹配类型

Quamina支持多种匹配类型：

1. 精确匹配：

   {"Image": {"Width": [800]}}
   

2. 存在性检查：

   {"Image": {"Title": [{"exists": true}]}}
   

3. 通配符匹配：

   {"Image": {"Thumbnail": {"Url": [{"wildcard": "*example.com*"}]}}}
   

4. 正则表达式：

   {"Image": {"Title": [{"regexp": "View from [0-9]+.. Floor"}]}}
   

5. 前缀匹配：

   {"Image": {"Thumbnail": {"Url": [{"prefix": "https:"}]}}}
   

6. 排除匹配：

   {"Image": {"Title": [{"anything-but": ["Pikachu", "Eevee"]}]}}
   

最佳实践

1. 尽可能重用Quamina实例，因为初始几次匹配性能会稍低
2. 避免在单个实例中使用大量wildcard模式
3. 对于高并发场景，使用Copy()创建多个实例
4. 只添加必要的模式字段，未提及的字段不会影响性能

Quamina是一个功能强大且高性能的模式匹配库，特别适合处理大量JSON事件和复杂匹配规则的场景。