Hyperf 敏感词过滤组件

基于确定有穷自动机算法(DFA)的敏感词过滤 Hyperf 组件，高效、灵活，支持协程环境。支持表情符号处理、变形文本检测和动态白名单管理。

特性亮点

🚀 高性能DFA算法：基于确定有穷自动机，检测效率高
🏗️ 模块化架构：采用单责任原则和策略模式，代码结构清晰，易于维护和扩展
🎯 智能白名单系统：支持动态白名单管理，避免误判
🔧 灵活配置：支持多种表情符号处理策略和变形文本检测
💾 智能缓存：三级缓存机制，大幅提升加载速度
🔍 前缀索引加速：针对中等长度文本的匹配优化
🌐 协程友好：完全支持 Hyperf 协程环境
📊 详细位置信息：支持返回敏感词的精确位置和长度
🛡️ 异常安全：敏感词处理异常不会影响业务流程
🔍 模糊匹配：支持绕过技术检测，如表情符号分隔、特殊字符插入等

安装

composer require lovevivi/hyperf-sensitive-words

发布配置

php bin/hyperf.php vendor:publish lovevivi/hyperf-sensitive-words

配置

配置文件位于 config/autoload/sensitive_words.php：

return [
    // 用户自定义敏感词库路径，留空则使用默认词库
    'word_path' => '',
    
    // 词库合并模式：override-覆盖模式，append-追加模式
    'merge_mode' => 'append',
    
    // 是否开启中间件自动过滤
    'middleware_enable' => false,
    
    // 替换字符
    'replace_char' => '*',
    
    // 是否重复替换字符
    'repeat_char' => true,
    
    // 处理哪些HTTP请求参数
    'http_params' => ['content', 'text', 'message'],
    
    // 是否启用词库缓存
    'enable_cache' => true,
    
    // 缓存过期时间（秒），默认86400秒（1天）
    'cache_expire' => 86400,
    
    // 缓存文件存放路径，留空则按优先级决定
    'cache_path' => '',
    
    // 是否在应用启动时预热词库
    'preload' => false,
    
    // 是否启用前缀索引加速
    'enable_prefix_index' => true,
    
    // 表情符号处理策略 (ignore, remove, replace, include)
    'emoji_strategy' => 'remove',
    
    // 表情符号替换占位符（当emoji_strategy为replace时有效）
    'emoji_placeholder' => '[表情]',
    
    // 是否启用变形文本检测（如拼音、特殊字符分隔等）
    'detect_variant_text' => true,
    
    // 变形文本映射表路径（自定义映射表，留空使用内置映射）
    'variant_map_path' => '',
    
    // 白名单词库 - 新增功能
    // 这里的词语即使命中敏感词规则，也不会被处理
    'whitelist' => [
        'assessment',       // 示例: 防止 "ass" 被错误匹配
        'helloween',        // 示例: 防止 "hell" 被错误匹配
        '中华人民共和国',   // 示例: 整个词是合法的
        // 在这里添加您需要的白名单词
    ],
];

使用方式

1. 使用服务方式

<?php

namespace App\Service;
    
use SensitiveWords\SensitiveWordsManager;

class ContentService
{
    /**
     * @var SensitiveWordsManager
     */
    protected $sensitiveWordsManager;
    
    public function __construct(SensitiveWordsManager $sensitiveWordsManager)
    {
        $this->sensitiveWordsManager = $sensitiveWordsManager;
    }
    
    public function filterContent(string $content): string
    {
        // 检查内容是否包含敏感词
        if (!$this->sensitiveWordsManager->check($content)) {
            // 替换敏感词
            $content = $this->sensitiveWordsManager->replace($content);

            // 或者获取所有敏感词
            $badWords = $this->sensitiveWordsManager->getBadWords($content);
        }
        
        return $content;
    }
}

### 1.1. 模糊匹配功能 **[新增]**

```php
<?php

namespace App\Service;
    
use SensitiveWords\SensitiveWordsManager;

class AdvancedContentService
{
    /**
     * @var SensitiveWordsManager
     */
    protected $sensitiveWordsManager;
    
    public function __construct(SensitiveWordsManager $sensitiveWordsManager)
    {
        $this->sensitiveWordsManager = $sensitiveWordsManager;
    }
    
    public function smartFilterContent(string $content): array
    {
        // 常规检测：快速，但无法识别绕过技术
        $normalCheck = $this->sensitiveWordsManager->check($content);
        $normalBadWords = $this->sensitiveWordsManager->getBadWords($content);
        
        // 模糊检测：能发现各种绕过技术
        $fuzzyCheck = $this->sensitiveWordsManager->check($content, true);
        $fuzzyBadWords = $this->sensitiveWordsManager->getBadWords($content, 0, true);
        
        return [
            'normal_detection' => [
                'has_sensitive' => $normalCheck,
                'bad_words' => $normalBadWords
            ],
            'fuzzy_detection' => [
                'has_sensitive' => $fuzzyCheck,
                'bad_words' => $fuzzyBadWords
            ],
            'bypass_detected' => $fuzzyCheck && !$normalCheck, // 是否检测到绕过技术
        ];
    }
    
    public function handleBypassAttempts(string $content): string
    {
        // 示例绕过文本：'a法😊b轮😜c功d' (试图绕过"法轮功")
        
        // 常规检测无法发现绕过
        $normalDetected = $this->sensitiveWordsManager->getBadWords($content);
        // 结果：[] (空数组)
        
        // 模糊检测能发现绕过
        $fuzzyDetected = $this->sensitiveWordsManager->getBadWords($content, 0, true);
        // 结果：['法轮功'] (找到了原始敏感词)
        
        if (!empty($fuzzyDetected)) {
            // 发现绕过尝试，记录日志或采取其他措施
            logger()->warning('检测到敏感词绕过尝试', [
                'content' => $content,
                'detected_words' => $fuzzyDetected
            ]);
            
            return '内容包含不当信息';
        }
        
        return $content;
    }
}

2. 使用注解方式

<?php

namespace App\Controller;

use Hyperf\HttpServer\Annotation\Controller;
use Hyperf\HttpServer\Annotation\RequestMapping;
use SensitiveWords\Annotation\SensitiveCheck;

/**
 * @Controller
 */
class ContentController
{
    /**
     * @RequestMapping(path="/sensitive/aspect-test", methods={"GET", "POST"})
     */
    public function test(RequestInterface $request)
    {
        // 从请求中获取内容
        $content = $request->input('string', '');
        
        // 调用助手方法，它将被切片处理
        $filteredContent = $this->filterContent($content);
        
        // 使用过滤后的内容构建响应
        return [
            'code' => 0,
            'message' => '成功',
            'data' => [
                'original_content' => $content,
                'processed_content' => $filteredContent
            ]
        ];
    }
    
    /**
     * 助手方法：过滤敏感词
     * 
     * @SensitiveCheck(param="content", replace=true, replaceChar="#")
     */
    protected function filterContent(string $content): string
    {
        // 切片会在方法执行前处理$content参数
        // 这里直接返回(可能已经被过滤的)内容
        return $content;
    }
}

3. 使用中间件方式

方式一：使用全局中间件，在 config/autoload/middlewares.php 中添加：

return [
    'http' => [
        SensitiveWords\Middleware\SensitiveWordsMiddleware::class,
    ],
];

方式二：按需使用中间件：注解方式注入中间件

use Hyperf\HttpServer\Annotation\Middleware;
use SensitiveWords\Middleware\SensitiveWordsMiddleware;

/**
 * @Middleware(SensitiveWordsMiddleware::class)
 */
class SensitiveMiddlewareTestController

同时在配置文件中设置 middleware_enable 为 true 可以启用中间件自动过滤功能。

4. 管理敏感词库

// 预热词库（在应用启动时调用，提高首次访问性能）
$container->get(SensitiveWordsManager::class)->warmup();

// 清除词库缓存
$container->get(SensitiveWordsManager::class)->clearCache();

// 设置词库（覆盖现有词库）- 方法已重命名
$container->get(SensitiveWordsManager::class)->setWordLibrary(['新词1', '新词2']);

// 增量添加敏感词
$container->get(SensitiveWordsManager::class)->addWords(['新词1', '新词2']);

5. 动态白名单管理 - 新增功能

$manager = $container->get(SensitiveWordsManager::class);

// 添加白名单词语
$manager->addWhitelistWords(['正常词汇', '合法内容']);

// 删除白名单词语
$manager->removeWhitelistWords(['不再需要的白名单']);

// 设置白名单（覆盖现有白名单）
$manager->setWhitelistWords(['新白名单1', '新白名单2']);

// 获取当前所有白名单词语
$whitelistWords = $manager->getWhitelistWords();

// 检查词语是否在白名单中
$isWhitelisted = $manager->isWhitelisted('某个词语');

// 清空所有白名单
$manager->clearWhitelist();

6. 获取所有敏感词列表

$manager = $container->get(SensitiveWordsManager::class);

// 获取当前词库中的所有敏感词
$allSensitiveWords = $manager->getAllSensitiveWords();

// 示例输出：['敏感词1', '敏感词2', '违禁词', ...]
var_dump($allSensitiveWords);

// 可以用于词库管理、统计分析等场景
$wordCount = count($allSensitiveWords);
echo "当前词库包含 {$wordCount} 个敏感词";

7. 表情符号与变形文本处理

// 设置表情符号处理策略
$manager->setEmojiStrategy('remove'); // 可选：ignore, remove, replace, include

// 如果选择replace策略，可以自定义替换占位符
$manager->setEmojiStrategy('replace', '[表情符号]');

// 启用或禁用变形文本检测
$manager->enableVariantTextDetection(true);

// 设置自定义变形文本映射表
$manager->setVariantMapPath('/path/to/custom/variant_map.php');

8. 获取详细位置信息 - 增强功能

// 获取敏感词的详细位置信息
$badWordsDetails = $manager->getBadWords($content, 0, true); // 第三个参数为true时返回详细信息

// 返回格式：
// [
//     ['word' => '敏感词', 'offset' => 5, 'len' => 3],
//     ['word' => '违禁词', 'offset' => 12, 'len' => 3]
// ]

模糊匹配技术 [新增]

模糊匹配能够检测各种绕过技术，有效防止恶意用户通过插入字符、表情符号等方式规避敏感词检测：

支持的绕过技术检测

表情符号分隔：法😊轮😜功 → 检测到 法轮功
特殊字符插入：法.轮.功、法-轮-功 → 检测到 法轮功
字母数字分隔：法a轮b功c、法1轮2功3 → 检测到 法轮功
空格分隔：法轮功 → 检测到 法轮功
混合分隔：a法😊b轮😜c功d → 检测到 法轮功

使用场景对比

$bypassText = 'a法😊b轮😜c功d相关内容';

// 常规检测：无法识别绕过
$normalWords = $manager->getBadWords($bypassText, 0, false);
// 结果：[] (空数组)

// 模糊检测：能识别绕过
$fuzzyWords = $manager->getBadWords($bypassText, 0, true);  
// 结果：['法轮功'] (找到原始敏感词)

性能与准确性平衡

常规检测：速度快，适合大量文本的实时处理
模糊检测：稍慢但更准确，适合关键内容的深度检测
智能缓存：模糊检测结果会被缓存，重复内容检测速度显著提升

API 参考

SensitiveWordsManager 类

基础功能

check(string $content, bool $useFuzzyMatch = false): bool - 检查内容是否包含敏感词，支持模糊匹配检测绕过技术 [增强]
replace(string $content, string $replaceChar = '*', bool $repeat = true): string - 替换内容中的敏感词，优化格式保持 [优化]
getBadWords(string $content, int $wordNum = 0, bool $useFuzzyMatch = false): array - 获取内容中的敏感词列表，支持模糊匹配和详细位置信息 [增强]
mark(string $content, string $sTag = '<span style="color:red">', string $eTag = '</span>'): string - 标记内容中的敏感词，优化格式保持 [优化]

词库管理

setWordLibrary(array $words = []): bool - 设置词库（覆盖现有词库）[方法重命名]
addWords(array $words): bool - 增量添加敏感词
getAllSensitiveWords(): array - 获取当前词库中的所有敏感词
warmup(): bool - 预热词库，提高首次访问性能
clearCache(): bool - 清除词库缓存，在词库更新后调用

白名单管理 [新增功能]

addWhitelistWords(array $words): bool - 添加白名单词语
removeWhitelistWords(array $words): bool - 删除白名单词语
setWhitelistWords(array $words): bool - 设置白名单词语（覆盖现有白名单）
getWhitelistWords(): array - 获取当前所有白名单词语
isWhitelisted(string $word): bool - 检查词语是否在白名单中
clearWhitelist(): bool - 清空所有白名单词语

高级设置

setEmojiStrategy(string $strategy, string $placeholder = '[表情]'): bool - 设置表情符号处理策略
enableVariantTextDetection(bool $enable = true): bool - 启用或禁用变形文本检测
setVariantMapPath(string $path): bool - 设置变形文本映射表路径

高级功能

模块化架构设计 [v1.2.0新增]

架构概览

组件采用模块化设计，将原本的单一类拆分为多个专职类，遵循单责任原则和策略模式：

SensitiveHelper (主类)
├── FilterManager (过滤器管理器)
│   ├── BoundaryFilter (边界检测过滤器)
│   ├── LengthFilter (长度过滤器)
│   └── ContextFilter (上下文过滤器)
└── FuzzyMatcher (模糊匹配器)

核心组件

FilterManager - 过滤器管理器

统一管理所有过滤策略
支持动态添加和移除过滤器
通过依赖注入提供给主类使用

BoundaryFilter - 边界检测过滤器

专门处理单字符边界检测逻辑
防止正常词汇中的单字符被误判
支持中英文混合文本的边界识别

LengthFilter - 长度过滤器

处理英文短词在中文语境中的过滤
避免短英文单词在中文文本中的误匹配
智能判断语境相关性

ContextFilter - 上下文过滤器

专业术语保护（技术、医学、农业等）
商业新闻内容的上下文分析
品牌和专有名词的智能识别

FuzzyMatcher - 模糊匹配器

独立处理所有模糊匹配逻辑
管理模糊匹配的缓存机制
支持各种绕过技术的检测

设计优势

单责任原则：每个类只负责一个特定功能
策略模式：过滤器可以独立开发和测试
依赖注入：组件之间松耦合，便于单元测试
向后兼容：公共API保持不变，现有代码无需修改
易于扩展：新的过滤策略只需实现FilterStrategyInterface

智能白名单系统

白名单系统支持两种过滤模式：

1. 直接白名单

直接将词语加入白名单，该词语将不会被检测为敏感词：

$manager->addWhitelistWords(['assessment', 'helloween']);
// "assessment" 和 "helloween" 不会被检测为敏感词

2. 上下文白名单

当敏感词是更长白名单词语的一部分时，也会被过滤：

// 敏感词库包含：['ass', 'hell']
// 白名单包含：['assessment', 'helloween']

$text = 'This is an assessment of the helloween party.';
// "ass" 和 "hell" 不会被检测，因为它们是白名单词语的一部分

3. 动态管理

支持运行时动态添加、删除、查询白名单：

// 运行时添加
$manager->addWhitelistWords(['新的合法词汇']);

// 检查是否在白名单中
if ($manager->isWhitelisted('某个词')) {
    // 处理逻辑
}

// 获取所有白名单
$allWhitelist = $manager->getWhitelistWords();

表情符号处理

组件支持多种表情符号处理策略：

ignore: 忽略表情符号(默认)
remove: 移除所有表情符号后再检测
replace: 将表情符号替换为占位符再检测
include: 将表情符号作为正常字符处理

变形文本检测

能够识别常见的变形规避手段：

全角/半角转换（如"Ａｐｐｌｅ"→"Apple"）
特殊符号分隔（如"敏.感.词"→"敏感词"）
数字与汉字混用（如"全①国"→"全1国"/"全一国"）
中英文混合（如"wo爱中国"→"我爱中国"）

缓存与预热机制

支持词库缓存，大幅提升加载速度
三级缓存路径：用户配置、框架缓存目录、系统临时目录
支持自动预热，避免首次请求的性能损耗
白名单也会被缓存，确保性能一致性

前缀索引加速

针对中等长度文本的匹配算法优化：

按首字符索引敏感词，预先过滤不可能匹配的词
减少大型词库的检查次数，提高检测效率

详细位置信息

支持返回敏感词的精确位置信息：

$details = $manager->getBadWords($content, 0, true);
// 返回：[['word' => '敏感词', 'offset' => 5, 'len' => 3], ...]

性能优化

基于DFA算法的高效词库树结构
前缀索引加速，减少检测过程中的比较次数
词库文件懒加载与缓存机制，避免频繁IO操作
支持协程环境下的高并发处理
灵活的降级策略，保证组件在各种环境下可用
异常安全，敏感词处理异常不会影响业务流程
智能白名单缓存，避免重复计算

版本更新说明

v1.2.0 - 架构重构与代码质量提升版本 [最新]

1. 模块化架构重构 [重大重构]

单责任原则：将原本1749行的SensitiveHelper类拆分为多个专职类
策略模式实现：创建FilterStrategyInterface和具体过滤器类
- BoundaryFilter: 单字符边界检测逻辑
- LengthFilter: 英文短词在中文语境的智能过滤
- ContextFilter: 专业术语、商业新闻和品牌保护逻辑
依赖注入设计：通过FilterManager统一管理所有过滤策略
模糊匹配器独立：FuzzyMatcher类专门处理模糊匹配和缓存

2. 过滤精度大幅提升 [核心优化]

边界检测优化：单字符敏感词只在独立出现时才被检测
上下文语义分析：根据语境自动过滤正常用词
专业术语保护：自动识别技术、科研、农业等专业领域术语
商业内容保护：电商、企业、媒体等商业词汇智能保护
误检率降低：在真实新闻文本测试中，误检率从87.5%降至0%

3. 性能与稳定性提升

缓存管理优化：模糊匹配缓存通过专门的FuzzyMatcher管理
初始化修复：解决addWords和getBadWord方法的词库自动加载问题
测试完善：52个测试用例全部通过，代码稳定性显著提升

4. 代码质量改进

可维护性：模块化设计便于独立开发和测试各个功能
可扩展性：新的过滤策略可以轻松通过实现接口来添加
向后兼容：所有公共方法保持完全兼容，现有代码无需修改

v1.1.0 - 模糊匹配与格式优化版本

1. 模糊匹配功能 [重大新增]

新增 check() 方法的 $useFuzzyMatch 参数，支持绕过技术检测
新增 getBadWords() 方法的 $useFuzzyMatch 参数，支持模糊匹配获取敏感词
新增 getFuzzyBadWords() 底层方法，专门处理模糊匹配逻辑
支持检测表情符号分隔、特殊字符插入、字母数字分隔等绕过技术
智能缓存机制：模糊检测结果自动缓存，避免重复计算

2. 格式保持优化 [重要修复]

修复 replace() 和 mark() 方法在变形文本检测开启时移除空格的问题
通过临时禁用变形文本检测，完美保持原始文本格式
英文敏感词替换现在能正确保留空格：'This is bad word' → 'This is *** word'

3. API 增强

getBadWords() 方法现在支持模糊匹配模式
新增性能优化的缓存清理机制
保持完全向后兼容，现有代码无需修改

4. 测试完善

新增 testGetBadWordsWithFuzzyMatch() 测试用例
新增模糊匹配性能对比测试
修复格式保持相关的测试用例
总计新增 4 个测试方法，确保功能稳定性

5. 性能提升

模糊检测通过优化算法和缓存机制，性能大幅提升
重复内容检测提速高达 472%
敏感词按长度排序，优化匹配效率

历史版本

v1.0.x - 基础功能完善版本

1. 白名单功能全面升级

新增动态白名单管理API
支持上下文白名单过滤
白名单与缓存系统集成
配置文件支持白名单预设

2. API方法重命名

updateWordLibrary() → setWordLibrary() - 更准确地反映方法功能

3. 功能增强

getBadWords() 方法支持返回详细位置信息
replace() 和 mark() 方法基于精确位置进行操作
匹配算法一致性优化，确保前缀索引与DFA主循环行为统一
新增 getAllSensitiveWords() 方法，支持获取当前词库中的所有敏感词

4. 测试覆盖完善

新增 SensitiveWordsManagerTest.php - 管理器功能全面测试
新增 WhitelistManagementTest.php - 白名单功能专项测试
52个测试用例，307个断言，确保功能稳定性

5. 代码质量提升

重复代码优化，提取公共逻辑
中文注释完善，提高代码可读性
异常处理增强，提高系统健壮性

许可证

MIT

测试

本项目包含全面的单元测试，确保所有功能的正确性和稳定性。

测试结构

tests/
├── Cases/
│   ├── SensitiveHelperTest.php          # SensitiveHelper 核心功能测试
│   ├── SensitiveWordsManagerTest.php    # SensitiveWordsManager 管理器测试
│   └── WhitelistManagementTest.php      # 白名单功能专项测试
└── AbstractTestCase.php                 # 测试基类

测试覆盖范围

SensitiveHelperTest.php

白名单功能测试（上下文过滤、直接白名单等）
addWords 增量添加功能测试
getBadWord 详细模式测试（返回位置信息）
replace 和 mark 方法测试（各种匹配模式）
变形文本处理测试
边界情况和异常处理测试
getAllSensitiveWords 功能测试 - 新增

SensitiveWordsManagerTest.php

基础功能测试：check、replace、getBadWords、mark
词库管理测试：setWordLibrary、addWords、getAllSensitiveWords
系统功能测试：warmup、clearCache
配置管理测试：setEmojiStrategy、enableVariantTextDetection、setVariantMapPath
复杂场景测试：多功能组合使用
性能测试：大词库和大文本处理
边界情况测试：空内容、特殊字符等
模糊匹配测试：testGetBadWordsWithFuzzyMatch - 新增

WhitelistManagementTest.php

动态白名单管理：addWhitelistWords、removeWhitelistWords
白名单设置：setWhitelistWords、clearWhitelist
白名单查询：getWhitelistWords、isWhitelisted
白名单与敏感词检测的交互测试
预处理对白名单的影响测试

运行测试

# 运行所有测试
composer test

# 或者使用 PHPUnit 直接运行
./vendor/bin/phpunit

# 运行特定测试文件
./vendor/bin/phpunit tests/Cases/SensitiveWordsManagerTest.php

# 运行特定测试方法
./vendor/bin/phpunit tests/Cases/SensitiveWordsManagerTest.php::testGetAllSensitiveWords

# 显示详细输出
./vendor/bin/phpunit --verbose

# 生成代码覆盖率报告（需要安装 xdebug）
./vendor/bin/phpunit --coverage-html coverage/

测试统计

总测试数: 52个测试 (包含架构重构后的所有功能测试)
总断言数: 313个断言
测试覆盖: 核心功能100%覆盖，包括模糊匹配和模块化架构
测试类型: 单元测试、集成测试、性能测试、模糊匹配专项测试
架构测试: 过滤器策略、依赖注入、缓存管理等模块化功能全面测试

添加新测试

如果你需要添加新的测试用例，请遵循以下规范：

测试文件命名: 使用 *Test.php 后缀
测试方法命名: 使用 test* 前缀，方法名要清晰描述测试内容
测试分组: 按功能模块分组，相关测试放在同一个测试类中
断言使用: 使用具体的断言方法，如 assertStringContainsString 而不是通用的 assertTrue
测试数据: 使用有意义的测试数据，包含中英文、特殊字符等各种情况

持续集成

项目配置了完整的测试流程，每次代码提交都会自动运行全部测试，确保代码质量。

Name		Name	Last commit message	Last commit date
Latest commit History 31 Commits
data		data
publish		publish
src		src
tests		tests
.gitignore		.gitignore
README.md		README.md
composer.json		composer.json
phpunit.xml		phpunit.xml

Folders and files

Latest commit

History

Repository files navigation