Segment Matcher：高性能的消息段模式匹配库

项目简介

Segment Matcher 是一个专为消息段处理设计的高性能模式匹配库。它提供了类型安全的消息段匹配能力，支持复杂的参数提取、智能空格处理和丰富的类型系统，是开发聊天机器人和消息处理应用的理想选择。

核心亮点

🎯 精确匹配: 支持字面量、类型化字面量、参数等复杂模式
⚡ 高性能: 优化的匹配算法、智能缓存系统、大小数组优化策略
🛡️ 类型安全: 完整的 TypeScript 类型定义和运行时类型检查
🔧 灵活配置: 自定义字段映射、多字段优先级、动态字段提取
📦 双格式支持: 同时支持 ESM 和 CommonJS
🧪 测试完善: 91%+ 测试覆盖率

技术特性

丰富的类型系统

Segment Matcher 提供了完整的类型系统来满足不同场景的需求：

number: 整数或浮点数
integer: 仅整数
float: 必须带小数点的浮点数
boolean: true/false 布尔值
word: 非空格字符序列（新增）
text: 支持引号包裹的文本（增强）

灵活的参数系统

支持多种参数定义方式：

必需参数:
text
```
<param:type>
```
可选参数:
text
```
[param:type]
```
带默认值的参数:
text
```
[param:type=default]
```
剩余参数:
text
```
[...rest:type]
```

智能空格处理

参数间的单个空格自动处理
多个连续空格视为字面量精确匹配
支持单个文本段自动提取多个参数

引号支持

支持单引号和双引号
支持嵌套不同类型的引号
为多个 text 参数提供明确的边界

安装使用

安装

使用 npm 安装：

bash
npm install segment-matcher

或使用 yarn：

bash
yarn add segment-matcher

或使用 pnpm：

bash
pnpm add segment-matcher

基础用法

typescript
import { SegmentMatcher } from 'segment-matcher';

// 创建消息段匹配器
const matcher = new SegmentMatcher('hello <name:text>');

// 匹配消息段
const segments = [
  { type: 'text', data: { text: 'hello Alice' } }
];

const result = matcher.match(segments);
if (result) {
  console.log('匹配的消息段:', result.matched);
  console.log('提取的参数:', result.params);  // { name: 'Alice' }
  console.log('剩余的消息段:', result.remaining);
}

核心功能详解

1. 单个文本段多参数提取

从单个连续文本段中自动提取多个参数：

typescript
const matcher = new SegmentMatcher('move [x:number=0] [y:number=0]');

// 自动从单个文本段提取参数
const result = matcher.match([
  { type: 'text', data: { text: 'move 10 20' } }
]);

console.log(result.params); // { x: 10, y: 20 }

2. word 类型 - 非空格字符

word 类型可以提取多个单词参数，避免 text 类型的贪婪匹配：

typescript
const matcher = new SegmentMatcher('config [key:word=name] [value:word=default]');

const result = matcher.match([
  { type: 'text', data: { text: 'config database mysql' } }
]);

console.log(result.params); // { key: 'database', value: 'mysql' }

3. 引号支持 - 包含空格的文本

使用引号可以提取多个包含空格的 text 参数：

typescript
const matcher = new SegmentMatcher('post [title:text=Untitled] [tags:text=none]');

// 使用双引号
const result1 = matcher.match([
  { type: 'text', data: { text: 'post "My Article Title" "tag1 tag2 tag3"' } }
]);
console.log(result1.params); 
// { title: 'My Article Title', tags: 'tag1 tag2 tag3' }

// 使用单引号
const result2 = matcher.match([
  { type: 'text', data: { text: "post 'Quick Tips' 'tutorial'" } }
]);
console.log(result2.params); 
// { title: 'Quick Tips', tags: 'tutorial' }

// 嵌套不同类型引号
const result3 = matcher.match([
  { type: 'text', data: { text: `post "It's great" 'He said "hello"'` } }
]);
console.log(result3.params); 
// { title: "It's great", tags: 'He said "hello"' }

4. 类型化字面量

匹配特定类型的消息段：

typescript
const matcher = new SegmentMatcher('{text:hello}{at:123456}');

const result = matcher.match([
  { type: 'text', data: { text: 'hello' } },
  { type: 'at', data: { user_id: 123456 } }
]);

// 匹配成功，result 包含完整的消息段信息

5. 剩余参数匹配

收集所有剩余的同类型消息段：

typescript
const matcher = new SegmentMatcher('图片[...images:image]');

const result = matcher.match([
  { type: 'text', data: { text: '图片' } },
  { type: 'image', data: { file: '1.jpg' } },
  { type: 'image', data: { file: '2.jpg' } }
]);

// result.params.images 包含所有图片的信息

6. 自定义字段映射

自定义字段映射规则，按优先级提取值：

typescript
const matcher = new SegmentMatcher('图片<img:image>', {
  image: ['url', 'file', 'src']  // 按优先级尝试这些字段
});

const result = matcher.match([
  { type: 'text', data: { text: '图片' } },
  { type: 'image', data: { url: 'https://example.com/image.jpg' } }
]);

// 按照 url -> file -> src 的优先级提取值

类型选择指南

根据不同的使用场景，选择合适的参数类型：

场景	推荐类型	示例	说明
单个单词	text `word`	text `[name:word]`	不包含空格的字符串
包含空格的文本	text `text` + 引号	text `[msg:text]` 输入 text `"hello world"`	明确边界
最后一个参数	text `text`	text `[msg:text]`	贪婪匹配剩余内容
数字	text `number`	text `[count:number]`	整数或浮点数
整数	text `integer`	text `[age:integer]`	只接受整数
浮点数	text `float`	text `[price:float]`	必须带小数点
布尔值	text `boolean`	text `[flag:boolean]`	true/false

最佳实践

1. 智能空格处理

typescript
// 参数间的单个空格会被自动处理
const matcher = new SegmentMatcher('cmd [a:number] [b:number]');

// 以下两种输入都可以匹配
matcher.match([{ type: 'text', data: { text: 'cmd 10 20' } }]);   // ✅
matcher.match([{ type: 'text', data: { text: 'cmd 1020' } }]);     // ✅

// 多个空格会被视为字面量
const strictMatcher = new SegmentMatcher('cmd  [a:number]'); // 两个空格
strictMatcher.match([{ type: 'text', data: { text: 'cmd  10' } }]);  // ✅
strictMatcher.match([{ type: 'text', data: { text: 'cmd 10' } }]);   // ❌

2. 引号使用建议

使用引号包裹包含空格的 text 参数
双引号内可以使用单引号，反之亦然
相同类型的引号不能嵌套

3. 类型选择

多个单词参数优先使用
text
```
word
```
类型
需要包含空格时使用
text
```
text
```
+ 引号
text
```
text
```
类型放在参数列表末尾可以省略引号

4. 性能优化

对于频繁使用的模式，重用
text
```
SegmentMatcher
```
实例
合理使用字段映射来避免不必要的字段访问
利用缓存系统提高匹配性能

实际应用场景

聊天机器人命令解析

typescript
// 定义机器人命令
const commandMatchers = {
  help: new SegmentMatcher('help [command:word]'),
  kick: new SegmentMatcher('kick {at:user}'),
  ban: new SegmentMatcher('ban {at:user} [duration:integer=0]'),
  config: new SegmentMatcher('config [key:word] [value:text]'),
  search: new SegmentMatcher('search <query:text>'),
};

// 处理消息
function handleMessage(segments) {
  for (const [name, matcher] of Object.entries(commandMatchers)) {
    const result = matcher.match(segments);
    if (result) {
      console.log(`执行命令: ${name}`, result.params);
      return;
    }
  }
  console.log('未知命令');
}

消息格式化工具

typescript
// 解析富文本消息
const formatter = new SegmentMatcher(
  '[...segments:text|at|image|emoji]'
);

const result = formatter.match([
  { type: 'text', data: { text: '你好 ' } },
  { type: 'at', data: { user_id: 123456 } },
  { type: 'text', data: { text: ' 看这张图片 ' } },
  { type: 'image', data: { url: 'example.jpg' } }
]);

// 格式化为 HTML
function formatToHTML(segments) {
  return segments.map(seg => {
    switch (seg.type) {
      case 'text':
        return seg.data.text;
      case 'at':
        return `<span class="at">@${seg.data.user_id}</span>`;
      case 'image':
        return `<img src="${seg.data.url}" />`;
      default:
        return '';
    }
  }).join('');
}

开发与测试

项目提供了完善的开发和测试支持：

bash
# 运行测试
npm test

# 运行测试并生成覆盖率报告
npm run test:coverage

# 构建项目
npm run build

# 清理构建产物
npm run clean

技术架构

模块化设计

清晰的模块划分: 将功能分解为独立的模块
低耦合高内聚: 模块之间依赖关系清晰
易于扩展: 方便添加新的类型和功能

性能优化

智能缓存: 类型检查缓存、模式解析缓存
算法优化: 针对不同场景的匹配算法优化
数组处理: 大小数组分别优化

类型安全

完整的类型定义: 全面的 TypeScript 类型支持
运行时检查: 在运行时验证类型安全
类型推导: 智能的类型推导系统

总结

Segment Matcher 是一个功能强大、性能优异的消息段模式匹配库。它为开发者提供了：

✅ 类型安全的消息段匹配
✅ 丰富的参数系统和类型支持
✅ 智能的空格处理和引号支持
✅ 高性能的匹配算法
✅ 灵活的配置选项
✅ 完善的测试覆盖

无论是开发聊天机器人、消息处理系统，还是需要复杂的文本解析功能，Segment Matcher 都能提供简单、高效的解决方案。项目采用 MIT 许可证，欢迎社区贡献和反馈！

本文介绍的 Segment Matcher 项目是 zhinjs 组织开发维护的开源项目。如果这个项目对你有帮助，欢迎给项目点个 Star ⭐