houbb/sensitive-word

sensitive-word

sensitive-word 基于 DFA 算法实现的高性能敏感词工具。

如果有一些疑难杂症，可以加入：技术交流群

sensitive-word-admin 是对应的控台的应用，目前功能处于初期开发中，MVP 版本可用。

创作目的

大家好，我是老马。

一直想实现一款简单好用敏感词工具，于是开源实现了这个工具。

基于 DFA 算法实现，目前敏感词库内容收录 6W+（源文件 18W+，经过一次删减）。

后期将进行持续优化和补充敏感词库，并进一步提升算法的性能。

v0.24.0 开始内置支持对敏感词的分类细化，不过工作量比较大，难免存在疏漏。

欢迎 PR 改进， github 提需求，或者加入技术交流群沟通吹牛！

特性

• 6W+ 词库，且不断优化更新

• 基于 fluent-api 实现，使用优雅简洁

• 基于 DFA 算法，性能为 14W+ QPS，应用无感

• 支持敏感词的判断、返回、脱敏等常见操作

• 支持常见的格式转换

全角半角互换、英文大小写互换、数字常见形式的互换、中文繁简体互换、英文常见形式的互换、忽略重复词等

• 支持敏感词检测、邮箱检测、数字检测、网址检测、IPV4等

• 支持自定义替换策略

• 支持用户自定义敏感词和白名单

• 支持数据的数据动态更新（用户自定义），实时生效

• 支持敏感词的标签接口+内置分类实现

• 支持跳过一些特殊字符，让匹配更灵活

• 支持黑白名单单个的新增/修改，无需全量初始化

• 支持词匹配模式的两种模式

项目推荐

下面是一些日志、加解密、脱敏安全相关的库推荐：

变更日志

CHANGE_LOG.md

更多资料

敏感词控台

有时候敏感词有一个控台，配置起来会更加灵活方便。

java 如何实现开箱即用的敏感词控台服务？

敏感词标签文件

梳理了大量的敏感词标签文件，可以让我们的敏感词更加方便。

这两个资料阅读可在下方文章获取：

v0.11.0-敏感词新特性及对应标签文件

目前 v0.24.0 已内置实现单词标签，需要的建议升级到最新版本。

支持开源

开源不易，如果本项目对你有帮助，你可以请老马喝一杯奶茶。

快速开始

准备

• JDK1.8+

• Maven 3.x+

Maven 引入

<dependency>
    <groupId>com.github.houbb</groupId>
    <artifactId>sensitive-word</artifactId>
    <version>0.29.5</version>
</dependency>

核心方法

SensitiveWordHelper 作为敏感词的工具类，核心方法如下：

注意：SensitiveWordHelper 提供的都是默认配置。如果你希望进行灵活的自定义配置，可参考 引导类特性配置

判断是否包含敏感词

final String text = "五星红旗迎风飘扬，毛主席的画像屹立在天安门前。";

Assert.assertTrue(SensitiveWordHelper.contains(text));

返回第一个敏感词

final String text = "五星红旗迎风飘扬，毛主席的画像屹立在天安门前。";

String word = SensitiveWordHelper.findFirst(text);
Assert.assertEquals("五星红旗", word);

SensitiveWordHelper.findFirst(text) 等价于：

String word = SensitiveWordHelper.findFirst(text, WordResultHandlers.word());

返回所有敏感词

final String text = "五星红旗迎风飘扬，毛主席的画像屹立在天安门前。";

List<String> wordList = SensitiveWordHelper.findAll(text);
Assert.assertEquals("[五星红旗, 毛主席, 天安门]", wordList.toString());

返回所有敏感词用法上类似于 SensitiveWordHelper.findFirst()，同样也支持指定结果处理类。

SensitiveWordHelper.findAll(text) 等价于：

List<String> wordList = SensitiveWordHelper.findAll(text, WordResultHandlers.word());

WordResultHandlers.raw() 可以保留对应的下标信息、类别信息：

final String text = "五星红旗迎风飘扬，毛主席的画像屹立在天安门前。";

// 默认敏感词标签为空
List<WordTagsDto> wordList1 = SensitiveWordHelper.findAll(text, WordResultHandlers.wordTags());
Assert.assertEquals("[WordTagsDto{word='五星红旗', tags=[]}, WordTagsDto{word='毛主席', tags=[]}, WordTagsDto{word='天安门', tags=[]}]", wordList1.toString());

默认的替换策略

final String text = "五星红旗迎风飘扬，毛主席的画像屹立在天安门前。";
String result = SensitiveWordHelper.replace(text);
Assert.assertEquals("****迎风飘扬，***的画像屹立在***前。", result);

指定替换的内容

final String text = "五星红旗迎风飘扬，毛主席的画像屹立在天安门前。";
String result = SensitiveWordHelper.replace(text, '0');
Assert.assertEquals("0000迎风飘扬，000的画像屹立在000前。", result);

自定义替换策略

V0.2.0 支持该特性。

场景说明：有时候我们希望不同的敏感词有不同的替换结果。比如【游戏】替换为【电子竞技】，【失业】替换为【灵活就业】。

诚然，提前使用字符串的正则替换也可以，不过性能一般。

使用例子：

/**
 * 自定替换策略
 * @since 0.2.0
 */
@Test
public void defineReplaceTest() {
    final String text = "五星红旗迎风飘扬，毛主席的画像屹立在天安门前。";

    ISensitiveWordReplace replace = new MySensitiveWordReplace();
    String result = SensitiveWordHelper.replace(text, replace);

    Assert.assertEquals("国家旗帜迎风飘扬，教员的画像屹立在***前。", result);
}

其中 MySensitiveWordReplace 是我们自定义的替换策略，实现如下：

public class MyWordReplace implements IWordReplace {

    @Override
    public void replace(StringBuilder stringBuilder, final char[] rawChars, IWordResult wordResult, IWordContext wordContext) {
        String sensitiveWord = InnerWordCharUtils.getString(rawChars, wordResult);
        // 自定义不同的敏感词替换策略，可以从数据库等地方读取
        if("五星红旗".equals(sensitiveWord)) {
            stringBuilder.append("国家旗帜");
        } else if("毛主席".equals(sensitiveWord)) {
            stringBuilder.append("教员");
        } else {
            // 其他默认使用 * 代替
            int wordLength = wordResult.endIndex() - wordResult.startIndex();
            for(int i = 0; i < wordLength; i++) {
                stringBuilder.append('*');
            }
        }
    }

}

我们针对其中的部分词做固定映射处理，其他的默认转换为 *。

IWordResultHandler 结果处理类

IWordResultHandler 可以对敏感词的结果进行处理，允许用户自定义。

内置实现见 WordResultHandlers 工具类：

• WordResultHandlers.word()

只保留敏感词单词本身。

• WordResultHandlers.raw()

保留敏感词相关信息，包含敏感词的开始和结束下标。

• WordResultHandlers.wordTags()

同时保留单词，和对应的词标签信息。

使用实例

所有测试案例参见 SensitiveWordHelperTest

1）基本例子

final String text = "五星红旗迎风飘扬，毛主席的画像屹立在天安门前。";

List<String> wordList = SensitiveWordHelper.findAll(text);
Assert.assertEquals("[五星红旗, 毛主席, 天安门]", wordList.toString());
List<String> wordList2 = SensitiveWordHelper.findAll(text, WordResultHandlers.word());
Assert.assertEquals("[五星红旗, 毛主席, 天安门]", wordList2.toString());

List<IWordResult> wordList3 = SensitiveWordHelper.findAll(text, WordResultHandlers.raw());
Assert.assertEquals("[WordResult{startIndex=0, endIndex=4}, WordResult{startIndex=9, endIndex=12}, WordResult{startIndex=18, endIndex=21}]", wordList3.toString());

2. wordTags 例子

我们在 dict_tag_test.txt 文件中指定对应词的标签信息。

final String text = "五星红旗迎风飘扬，毛主席的画像屹立在天安门前。";

// 默认敏感词标签为空
List<WordTagsDto> wordList1 = SensitiveWordHelper.findAll(text, WordResultHandlers.wordTags());
Assert.assertEquals("[WordTagsDto{word='五星红旗', tags=[]}, WordTagsDto{word='毛主席', tags=[]}, WordTagsDto{word='天安门', tags=[]}]", wordList1.toString());

List<WordTagsDto> wordList2 = SensitiveWordBs.newInstance()
        .wordTag(WordTags.file("dict_tag_test.txt"))
        .init()
        .findAll(text, WordResultHandlers.wordTags());
Assert.assertEquals("[WordTagsDto{word='五星红旗', tags=[政治, 国家]}, WordTagsDto{word='毛主席', tags=[政治, 伟人, 国家]}, WordTagsDto{word='天安门', tags=[政治, 国家, 地址]}]", wordList2.toString());

更多特性

后续的诸多特性，主要是针对各种针对各种情况的处理，尽可能的提升敏感词命中率。

这是一场漫长的攻防之战。

样式处理

忽略大小写

final String text = "fuCK the bad words.";

String word = SensitiveWordHelper.findFirst(text);
Assert.assertEquals("fuCK", word);

忽略半角圆角

final String text = "ｆｕｃｋ the bad words.";

String word = SensitiveWordHelper.findFirst(text);
Assert.assertEquals("ｆｕｃｋ", word);

忽略数字的写法

这里实现了数字常见形式的转换。

final String text = "这个是我的微信：9⓿二肆⁹₈③⑸⒋➃㈤㊄";

List<String> wordList = SensitiveWordBs.newInstance().enableNumCheck(true).init().findAll(text);
Assert.assertEquals("[9⓿二肆⁹₈③⑸⒋➃㈤㊄]", wordList.toString());

忽略繁简体

final String text = "我爱我的祖国和五星紅旗。";

List<String> wordList = SensitiveWordHelper.findAll(text);
Assert.assertEquals("[五星紅旗]", wordList.toString());

忽略英文的书写格式

final String text = "Ⓕⓤc⒦ the bad words";

List<String> wordList = SensitiveWordHelper.findAll(text);
Assert.assertEquals("[Ⓕⓤc⒦]", wordList.toString());

忽略重复词

final String text = "ⒻⒻⒻfⓤuⓤ⒰cⓒ⒦ the bad words";

List<String> wordList = SensitiveWordBs.newInstance()
        .ignoreRepeat(true)
        .init()
        .findAll(text);
Assert.assertEquals("[ⒻⒻⒻfⓤuⓤ⒰cⓒ⒦]", wordList.toString());

更多检测策略

说明

v0.25.0 目前的几个策略，也支持用户引导类自定义。所有的策略都是接口，支持用户自定义实现。

内置实现：

a) WordChecks.urlNoPrefix() 作为 url 的额外实现，可以不需要 https:// 和 http:// 前缀。

邮箱检测

邮箱等个人信息，默认未启用。

final String text = "楼主好人，邮箱 [email protected]";
List<String> wordList = SensitiveWordBs.newInstance().enableEmailCheck(true).init().findAll(text);
Assert.assertEquals("[[email protected]]", wordList.toString());

连续数字检测

一般用于过滤手机号/QQ等广告信息，默认未启用。

V0.2.1 之后，支持通过 numCheckLen(长度) 自定义检测的长度。

final String text = "你懂得：12345678";

// 默认检测 8 位
List<String> wordList = SensitiveWordBs.newInstance()
.enableNumCheck(true)
.init().findAll(text);
Assert.assertEquals("[12345678]", wordList.toString());

// 指定数字的长度，避免误杀
List<String> wordList2 = SensitiveWordBs.newInstance()
.enableNumCheck(true)
.numCheckLen(9)
.init()
.findAll(text);
Assert.assertEquals("[]", wordList2.toString());

网址检测

用于过滤常见的网址信息，默认未启用。

v0.18.0 优化 URL 检测，更加严格，降低误判率

final String text = "点击链接 https://www.baidu.com 查看答案";
final SensitiveWordBs sensitiveWordBs = SensitiveWordBs.newInstance().enableUrlCheck(true).init();
List<String> wordList = sensitiveWordBs.findAll(text);
Assert.assertEquals("[https://www.baidu.com]", wordList.toString());
Assert.assertEquals("点击链接 ********************* 查看答案", sensitiveWordBs.replace(text));

v0.25.0 内置支持不需要 http 协议的前缀检测：

final String text = "点击链接 https://www.baidu.com 查看答案，当然也可以是 baidu.com、www.baidu.com";

final SensitiveWordBs sensitiveWordBs = SensitiveWordBs.newInstance()
        .enableUrlCheck(true) // 启用URL检测
        .wordCheckUrl(WordChecks.urlNoPrefix()) //指定检测的方式
        .init();
List<String> wordList = sensitiveWordBs.findAll(text);
Assert.assertEquals("[www.baidu.com, baidu.com, www.baidu.com]", wordList.toString());

Assert.assertEquals("点击链接 https://************* 查看答案，当然也可以是 *********、*************", sensitiveWordBs.replace(text));

IPV4 检测

v0.17.0 支持

避免用户通过 ip 绕过网址检测等，默认未启用。

final String text = "个人网站，如果网址打不开可以访问 127.0.0.1。";
final SensitiveWordBs sensitiveWordBs = SensitiveWordBs.newInstance().enableIpv4Check(true).init();
List<String> wordList = sensitiveWordBs.findAll(text);
Assert.assertEquals("[127.0.0.1]", wordList.toString());

引导类特性配置

说明

上面的特性默认都是开启的，有时业务需要灵活定义相关的配置特性。

所以 v0.0.14 开放了属性配置。

配置方法

为了让使用更加优雅，统一使用 fluent-api 的方式定义。

用户可以使用 SensitiveWordBs 进行如下定义：

注意：配置后，要使用我们新定义的 SensitiveWordBs 的对象，而不是以前的工具方法。工具方法配置都是默认的。

SensitiveWordBs wordBs = SensitiveWordBs.newInstance()
        .ignoreCase(true)
        .ignoreWidth(true)
        .ignoreNumStyle(true)
        .ignoreChineseStyle(true)
        .ignoreEnglishStyle(true)
        .ignoreRepeat(false)
        .enableNumCheck(false)
        .enableEmailCheck(false)
        .enableUrlCheck(false)
        .enableIpv4Check(false)
        .enableWordCheck(true)
        .wordFailFast(true)
        .wordCheckNum(WordChecks.num())
        .wordCheckEmail(WordChecks.email())
        .wordCheckUrl(WordChecks.url())
        .wordCheckIpv4(WordChecks.ipv4())
        .wordCheckWord(WordChecks.word())
        .numCheckLen(8)
        .wordTag(WordTags.none())
        .charIgnore(SensitiveWordCharIgnores.defaults())
        .wordResultCondition(WordResultConditions.alwaysTrue())
        .init();

final String text = "五星红旗迎风飘扬，毛主席的画像屹立在天安门前。";
Assert.assertTrue(wordBs.contains(text));

配置说明

其中各项配置的说明如下：

wordFailFast 敏感词匹配快速失败模式

场景说明

v0.26.0 开始支持。

默认情况下，wordFailFast=true。匹配时快速返回，性能较好。

但是有时候不太符合人的直觉。

默认如下：

SensitiveWordBs bs2 = SensitiveWordBs.newInstance()
        .wordDeny(new IWordDeny() {
            @Override
            public List<String> deny() {
                return Arrays.asList("我的世界", "我的");
            }
        }).init();
String text = "他的世界它的世界和她的世界都不是我的也不是我的世界";
List<String> textList2 = bs2.findAll(text);
Assert.assertEquals(Arrays.asList("我的", "我的"), textList2);

此时会优先匹配短的【我的】，导致后面的【我的世界】被跳过。

failOver 模式

尽可能找到最长的匹配词。

SensitiveWordBs bs = SensitiveWordBs.newInstance()
        .wordFailFast(false)
        .wordDeny(new IWordDeny() {
            @Override
            public List<String> deny() {
                return Arrays.asList("我的世界", "我的");
            }
        }).init();

String text = "他的世界它的世界和她的世界都不是我的也不是我的世界";
List<String> textList = bs.findAll(text);
Assert.assertEquals(Arrays.asList("我的", "我的世界"), textList);

内存资源的释放

v0.16.1 开始支持，有时候我们需要释放内存，可以如下：

关于内存回收问题

SensitiveWordBs wordBs = SensitiveWordBs.newInstance()
                .init();
// 后续因为一些原因移除了对应信息，希望释放内存。
wordBs.destroy();

针对单个黑名单词的新增/删除，无需全量初始化

使用场景：在初始化之后，我们希望针对单个词的新增/删除，而不是完全重新初始化。这个特性就是为此准备的。

支持版本：v0.19.0

方法说明

addWord(word) 新增敏感词，支持单个词/集合

removeWord(word) 删除敏感词，支持单个词/集合

实例代码：

final String text = "测试一下新增敏感词，验证一下删除和新增对不对";

SensitiveWordBs sensitiveWordBs =
SensitiveWordBs.newInstance()
        .wordAllow(WordAllows.empty())
        .wordDeny(WordDenys.empty())
        .init();

// 当前
Assert.assertEquals("[]", sensitiveWordBs.findAll(text).toString());

// 新增单个
sensitiveWordBs.addWord("测试");
sensitiveWordBs.addWord("新增");
Assert.assertEquals("[测试, 新增, 新增]", sensitiveWordBs.findAll(text).toString());

// 删除单个
sensitiveWordBs.removeWord("新增");
Assert.assertEquals("[测试]", sensitiveWordBs.findAll(text).toString());
sensitiveWordBs.removeWord("测试");
Assert.assertEquals("[]", sensitiveWordBs.findAll(text).toString());

// 新增集合
sensitiveWordBs.addWord(Arrays.asList("新增", "测试"));
Assert.assertEquals("[测试, 新增, 新增]", sensitiveWordBs.findAll(text).toString());
// 删除集合
sensitiveWordBs.removeWord(Arrays.asList("新增", "测试"));
Assert.assertEquals("[]", sensitiveWordBs.findAll(text).toString());

// 新增数组
sensitiveWordBs.addWord("新增", "测试");
Assert.assertEquals("[测试, 新增, 新增]", sensitiveWordBs.findAll(text).toString());
// 删除集合
sensitiveWordBs.removeWord("新增", "测试");
Assert.assertEquals("[]", sensitiveWordBs.findAll(text).toString());

针对单个白名单词的新增/删除，无需全量初始化

使用场景：在初始化之后，我们希望针对单个词的新增/删除，而不是完全重新初始化。这个特性就是为此准备的。

支持版本：v0.21.0

方法说明

addWordAllow(word) 新增白名单，支持单个词/集合

removeWordAllow(word) 删除白名单，支持单个词/集合

使用例子

        final String text = "测试一下新增敏感词白名单，验证一下删除和新增对不对";

        SensitiveWordBs sensitiveWordBs =
                SensitiveWordBs.newInstance()
                        .wordAllow(WordAllows.empty())
                        .wordDeny(new IWordDeny() {
                            @Override
                            public List<String> deny() {
                                return Arrays.asList("测试", "新增");
                            }
                        })
                        .init();

        // 当前
        Assert.assertEquals("[测试, 新增, 新增]", sensitiveWordBs.findAll(text).toString());

        // 新增单个
        sensitiveWordBs.addWordAllow("测试");
        sensitiveWordBs.addWordAllow("新增");
        Assert.assertEquals("[]", sensitiveWordBs.findAll(text).toString());

        // 删除单个
        sensitiveWordBs.removeWordAllow("测试");
        Assert.assertEquals("[测试]", sensitiveWordBs.findAll(text).toString());
        sensitiveWordBs.removeWordAllow("新增");
        Assert.assertEquals("[测试, 新增, 新增]", sensitiveWordBs.findAll(text).toString());

        // 新增集合
        sensitiveWordBs.addWordAllow(Arrays.asList("新增", "测试"));
        Assert.assertEquals("[]", sensitiveWordBs.findAll(text).toString());
        // 删除集合
        sensitiveWordBs.removeWordAllow(Arrays.asList("新增", "测试"));
        Assert.assertEquals("[测试, 新增, 新增]", sensitiveWordBs.findAll(text).toString());

        // 新增数组
        sensitiveWordBs.addWordAllow("新增", "测试");
        Assert.assertEquals("[]", sensitiveWordBs.findAll(text).toString());
        // 删除集合
        sensitiveWordBs.removeWordAllow("新增", "测试");
        Assert.assertEquals("[测试, 新增, 新增]", sensitiveWordBs.findAll(text).toString());

全量初始化

说明

此方式已废弃，建议使用上面增量添加的方式，避免全量加载。为了兼容，此方式依然保留。

使用方式：在调用 sensitiveWordBs.init() 的时候，根据 IWordDeny+IWordAllow 重新构建敏感词库。 因为初始化可能耗时较长（秒级别），所有优化为 init 未完成时不影响旧的词库功能，完成后以新的为准。

例子

@Component
public class SensitiveWordService {

    @Autowired
    private SensitiveWordBs sensitiveWordBs;

    /**
     * 更新词库
     *
     * 每次数据库的信息发生变化之后，首先调用更新数据库敏感词库的方法。
     * 如果需要生效，则调用这个方法。
     *
     * 说明：重新初始化不影响旧的方法使用。初始化完成后，会以新的为准。
     */
    public void refresh() {
        // 每次数据库的信息发生变化之后，首先调用更新数据库敏感词库的方法，然后调用这个方法。
        sensitiveWordBs.init();
    }

}

如上，你可以在数据库词库发生变更时，需要词库生效，主动触发一次初始化 sensitiveWordBs.init();。

其他使用保持不变，无需重启应用。

wordResultCondition-针对匹配词进一步判断

说明

支持版本：v0.13.0

有时候我们可能希望对匹配的敏感词进一步限制，比如虽然我们定义了【av】作为敏感词，但是不希望【have】被匹配。

就可以自定义实现 wordResultCondition 接口，实现自己的策略。

系统内置的策略在 WordResultConditions#alwaysTrue() 恒为真，WordResultConditions#englishWordMatch() 则要求英文必须全词匹配。

内置策略

WordResultConditions 工具类可以获取匹配策略

使用例子

原始的默认情况：

final String text = "I have a nice day。";

List<String> wordList = SensitiveWordBs.newInstance()
        .wordDeny(new IWordDeny() {
            @Override
            public List<String> deny() {
                return Collections.singletonList("av");
            }
        })
        .wordResultCondition(WordResultConditions.alwaysTrue())
        .init()
        .findAll(text);
Assert.assertEquals("[av]", wordList.toString());

我们可以指定为英文必须全词匹配。

final String text = "I have a nice day。";

List<String> wordList = SensitiveWordBs.newInstance()
        .wordDeny(new IWordDeny() {
            @Override
            public List<String> deny() {
                return Collections.singletonList("av");
            }
        })
        .wordResultCondition(WordResultConditions.englishWordMatch())
        .init()
        .findAll(text);
Assert.assertEquals("[]", wordList.toString());

当然可以根据需要实现更加复杂的策略。

wordTags 单词标签

支持版本： v0.23.0

我们可以只返回隶属于某一种标签的敏感词。

我们指定了两个敏感词：商品、AV

MyWordTag 是我们定义的一个敏感词标签实现：

/**
 * 自定义单词标签
 * @since 0.23.0
 */
public class MyWordTag extends AbstractWordTag {

    private static Map<String, Set<String>> dataMap;

    static {
        dataMap = new HashMap<>();
        dataMap.put("商品", buildSet("广告", "中文"));
        dataMap.put("AV", buildSet("色情", "单词", "英文"));
    }

    private static Set<String> buildSet(String... tags) {
        Set<String> set = new HashSet<>();
        for(String tag : tags) {
            set.add(tag);
        }
        return set;
    }

    @Override
    protected Set<String> doGetTag(String word) {
        return dataMap.get(word);
    }

}

测试用例如下，我们模拟了两个不同的实现类，每一个关注的单词标签不同。

// 只关心SE情
SensitiveWordBs sensitiveWordBsYellow = SensitiveWordBs.newInstance()
        .wordDeny(new IWordDeny() {
            @Override
            public List<String> deny() {
                return Arrays.asList("商品", "AV");
            }
        })
        .wordAllow(WordAllows.empty())
        .wordTag(new MyWordTag())
        .wordResultCondition(WordResultConditions.wordTags(Arrays.asList("色情")))
        .init();

// 只关心广告
SensitiveWordBs sensitiveWordBsAd = SensitiveWordBs.newInstance()
        .wordDeny(new IWordDeny() {
            @Override
            public List<String> deny() {
                return Arrays.asList("商品", "AV");
            }
        })
        .wordAllow(WordAllows.empty())
        .wordTag(new MyWordTag())
        .wordResultCondition(WordResultConditions.wordTags(Arrays.asList("广告")))
        .init();

final String text = "这些 AV 商品什么价格？";
Assert.assertEquals("[AV]", sensitiveWordBsYellow.findAll(text).toString());
Assert.assertEquals("[商品]", sensitiveWordBsAd.findAll(text).toString());

忽略字符

说明

我们的敏感词一般都是比较连续的，比如【傻帽】

那就有大聪明发现，可以在中间加一些字符，比如【傻!@#$帽】跳过检测，但是骂人等攻击力不减。

那么，如何应对这些类似的场景呢？

我们可以指定特殊字符的跳过集合，忽略掉这些无意义的字符即可。

v0.11.0 开始支持

例子

其中 charIgnore 对应的字符策略，用户可以自行灵活定义。

final String text = "傻@冒，狗+东西";

//默认因为有特殊字符分割，无法识别
List<String> wordList = SensitiveWordBs.newInstance().init().findAll(text);
Assert.assertEquals("[]", wordList.toString());

// 指定忽略的字符策略，可自行实现。
List<String> wordList2 = SensitiveWordBs.newInstance()
        .charIgnore(SensitiveWordCharIgnores.specialChars())
        .init()
        .findAll(text);

Assert.assertEquals("[傻@冒, 狗+东西]", wordList2.toString());

敏感词标签

说明

有时候我们希望对敏感词加一个分类标签：比如社情、暴/力等等。

这样后续可以按照标签等进行更多特性操作，比如只处理某一类的标签。

支持版本：v0.10.0

主要特性支持版本：v0.24.0

标签接口

这里只是一个抽象的接口，用户可以自行定义实现。比如从数据库查询、文件读取、api 调用等。

public interface IWordTag {

    /**
     * 查询标签列表
     * @param word 脏词
     * @return 结果
     */
    Set<String> getTag(String word);

}

内置实现

方法列表

为了方便大部分情况使用，内置实现一些场景策略在 WordTags 类中

格式约定

敏感词标签的格式我们默认约定如下 敏感词 tag1,tag2，代表这 敏感词 的标签为 tag1 和 tag2

比如

五星红旗 政治,国家

所有的文件行内容，和指定的字符串行内容也建议用这种方式。如果不满足，自定义实现即可。

系统内置实现（默认效果）

v0.24.0 版本开始，默认的单词标签为 WordTags.system()。

说明：目前数据统计自网络，存在不少疏漏。也欢迎大家指正，持续改进中...

SensitiveWordBs sensitiveWordBs = SensitiveWordBs.newInstance()
.wordTag(WordTags.system())
.init();
Set<String> tagSet = sensitiveWordBs.tags("博彩");
Assert.assertEquals("[3]", tagSet.toString());

这里为了压缩大小优化，对应的类别用数字表示。

数字的含义列表如下：

0 政治
1 毒品
2 色情
3 赌博
4 违法

文件入门例子

这里以文件为例子，演示一下如何使用。

final String path = "~\\test\\resources\\dict_tag_test.txt";

// 演示默认方法
IWordTag wordTag = WordTags.file(path);
SensitiveWordBs sensitiveWordBs = SensitiveWordBs.newInstance()
        .wordTag(wordTag)
        .init();

Set<String> tagSet = sensitiveWordBs.tags("零售");
        Assert.assertEquals("[广告, 网络]", tagSet.toString());


// 演示指定分隔符
IWordTag wordTag2 = WordTags.file(path, " ", ",");
SensitiveWordBs sensitiveWordBs2 = SensitiveWordBs.newInstance()
        .wordTag(wordTag2)
        .init();
Set<String> tagSet2 = sensitiveWordBs2.tags("零售");
        Assert.assertEquals("[广告, 网络]", tagSet2.toString());

其中 dict_tag_test.txt 我们自定义的内容如下：

零售 广告,网络

单词标签和敏感词发现的联动

我们在获取敏感词的时候，是可以设置对应的结果处理策略，从而获取对应的敏感词标签信息

// 自定义测试标签类
IWordTag wordTag = WordTags.lines(Arrays.asList("天安门 政治,国家,地址"));

// 指定初始化
SensitiveWordBs sensitiveWordBs = SensitiveWordBs.newInstance()
        .wordTag(wordTag)
        .init()
        ;

List<WordTagsDto> wordTagsDtoList1 = sensitiveWordBs.findAll("天安门", WordResultHandlers.wordTags());
Assert.assertEquals("[WordTagsDto{word='天安门', tags=[政治, 国家, 地址]}]", wordTagsDtoList1.toString());

我们自定义了 天安门 关键词的标签，然后通过指定 findAll 的结果处理策略为 WordResultHandlers.wordTags()，就可以在获取敏感词的同时，获取对应的标签列表。

动态加载（用户自定义）

情景说明

有时候我们希望将敏感词的加载设计成动态的，比如控台修改，然后可以实时生效。

v0.0.13 支持了这种特性。

接口说明

为了实现这个特性，并且兼容以前的功能，我们定义了两个接口。

IWordDeny

接口如下，可以自定义自己的实现。

返回的列表，表示这个词是一个敏感词。

/**
 * 拒绝出现的数据-返回的内容被当做是敏感词
 * @author binbin.hou
 * @since 0.0.13
 */
public interface IWordDeny {

    /**
     * 获取结果
     * @return 结果
     * @since 0.0.13
     */
    List<String> deny();

}

比如：

public class MyWordDeny implements IWordDeny {

    @Override
    public List<String> deny() {
        return Arrays.asList("我的自定义敏感词");
    }

}

IWordAllow

接口如下，可以自定义自己的实现。

返回的列表，表示这个词不是一个敏感词。

/**
 * 允许的内容-返回的内容不被当做敏感词
 * @author binbin.hou
 * @since 0.0.13
 */
public interface IWordAllow {

    /**
     * 获取结果
     * @return 结果
     * @since 0.0.13
     */
    List<String> allow();

}

如：

public class MyWordAllow implements IWordAllow {

    @Override
    public List<String> allow() {
        return Arrays.asList("五星红旗");
    }

}

配置使用

接口自定义之后，当然需要指定才能生效。

为了让使用更加优雅，我们设计了引导类 SensitiveWordBs。

可以通过 wordDeny() 指定敏感词，wordAllow() 指定非敏感词，通过 init() 初始化敏感词字典。

系统的默认配置

SensitiveWordBs wordBs = SensitiveWordBs.newInstance()
        .wordDeny(WordDenys.defaults())
        .wordAllow(WordAllows.defaults())
        .init();

final String text = "五星红旗迎风飘扬，毛主席的画像屹立在天安门前。";
Assert.assertTrue(wordBs.contains(text));

备注：init() 对于敏感词 DFA 的构建是比较耗时的，一般建议在应用初始化的时候只初始化一次。而不是重复初始化！

指定自己的实现

我们可以测试一下自定义的实现，如下:

String text = "这是一个测试，我的自定义敏感词。";

SensitiveWordBs wordBs = SensitiveWordBs.newInstance()
        .wordDeny(new MyWordDeny())
        .wordAllow(new MyWordAllow())
        .init();

Assert.assertEquals("[我的自定义敏感词]", wordBs.findAll(text).toString());

这里只有 我的自定义敏感词 是敏感词，而 测试 不是敏感词。

当然，这里是全部使用我们自定义的实现，一般建议使用系统的默认配置+自定义配置。

可以使用下面的方式。

同时配置多个

• 多个敏感词

WordDenys.chains() 方法，将多个实现合并为同一个 IWordDeny。

• 多个白名单

WordAllows.chains() 方法，将多个实现合并为同一个 IWordAllow。

例子：

String text = "这是一个测试。我的自定义敏感词。";

IWordDeny wordDeny = WordDenys.chains(WordDenys.defaults(), new MyWordDeny());
IWordAllow wordAllow = WordAllows.chains(WordAllows.defaults(), new MyWordAllow());

SensitiveWordBs wordBs = SensitiveWordBs.newInstance()
        .wordDeny(wordDeny)
        .wordAllow(wordAllow)
        .init();

Assert.assertEquals("[我的自定义敏感词]", wordBs.findAll(text).toString());

这里都是同时使用了系统默认配置，和自定义的配置。

注意：我们初始化了新的 wordBs，那么用新的 wordBs 去判断。而不是用以前的 SensitiveWordHelper 工具方法，工具方法配置是默认的！

系统内置词库及如何排除

内置词库文件说明

v0.27.0 将词库和当前项目拆分开，词库可以在 https://github.com/houbb/sensitive-word-data 项目查看。

对应的资源文件在 https://github.com/houbb/sensitive-word-data/tree/main/src/main/resources 目录下

如何排除

比如一些 android app 引入时不希望包中内置敏感的信息，希望对词库加解密或者是放在服务端初始化加载。

系统的内置词库通过下面的 maven 依赖导入

<dependency>
    <groupId>com.github.houbb</groupId>
    <artifactId>sensitive-word-data</artifactId>
    <version>${sensitive-word-data.version}</version>
</dependency>

依赖排除

所以可以按照 maven 排除规范，如下将其排除

<dependency>
    <groupId>com.github.houbb</groupId>
    <artifactId>sensitive-word</artifactId>
    <version>${sensitive-word.version}</version>
    <exclusions>
        <exclusion>
            <groupId>com.github.houbb</groupId>
            <artifactId>sensitive-word-data</artifactId>
        </exclusion>
    </exclusions>
</dependency>

排除后自定义

不希望使用内置词库，那就需要将原来内置的词库依赖改为自己的依赖

默认配置项：

SensitiveWordBs sensitiveWordBs = SensitiveWordBs.newInstance()
                .wordAllow(WordAllows.defaults())
                .wordDeny(WordDenys.defaults())
                .wordTag(WordTags.defaults())
                .init();

你可以将用到的这3个类，改为自己的实现。

可以通过加解密，或者加载远程服务的文件信息都可以。

spring 整合

背景

实际使用中，比如可以在页面配置修改，然后实时生效。

数据存储在数据库中，下面是一个伪代码的例子，可以参考 SpringSensitiveWordConfig.java

要求，版本 v0.0.15 及其以上。

自定义数据源

简化伪代码如下，数据的源头为数据库。

MyDdWordAllow 和 MyDdWordDeny 是基于数据库为源头的自定义实现类。

@Configuration
public class SpringSensitiveWordConfig {

    @Autowired
    private MyDdWordAllow myDdWordAllow;

    @Autowired
    private MyDdWordDeny myDdWordDeny;

    /**
     * 初始化引导类
     * @return 初始化引导类
     * @since 1.0.0
     */
    @Bean
    public SensitiveWordBs sensitiveWordBs() {
        SensitiveWordBs sensitiveWordBs = SensitiveWordBs.newInstance()
                .wordAllow(WordAllows.chains(WordAllows.defaults(), myDdWordAllow))
                .wordDeny(myDdWordDeny)
                // 各种其他配置
                .init();

        return sensitiveWordBs;
    }

}

敏感词库的初始化较为耗时，建议程序启动时做一次 init 初始化。

Benchmark

V0.29.2 以后，对应的 benchmark 测试。

BenchmarkTimesTest

环境

测试环境为普通的笔记本:

处理器	12th Gen Intel(R) Core(TM) i7-1260P   2.10 GHz
机带 RAM	16.0 GB (15.7 GB 可用)
系统类型	64 位操作系统, 基于 x64 的处理器

ps: 不同环境会有差异，但是比例基本稳定。

测试效果记录

测试数据：100+ 字符串，循环 10W 次。

STAR

后期 road-map

• 各种其他涉及到 char 拆箱的地方改进

• [] 中文转换优化-opencc4j 内存+性能优化

拓展阅读

敏感词系列

sensitive-word-admin 敏感词控台 v1.2.0 版本开源

sensitive-word-admin v1.3.0 发布 如何支持分布式部署？

01-开源敏感词工具入门使用

02-如何实现一个敏感词工具？违禁词实现思路梳理

03-敏感词之 StopWord 停止词优化与特殊符号

04-敏感词之字典瘦身

05-敏感词之 DFA 算法(Trie Tree 算法)详解

06-敏感词(脏词) 如何忽略无意义的字符？达到更好的过滤效果

v0.10.0-脏词分类标签初步支持

v0.11.0-敏感词新特性：忽略无意义的字符，词标签字典

v0.12.0-敏感词/脏词词标签能力进一步增强

v0.13.0-敏感词特性版本发布 支持英文单词全词匹配

v0.16.1-敏感词新特性之字典内存资源释放

v0.19.0-敏感词新特性之敏感词单个编辑，不必重复初始化

v0.20.0 敏感词新特性之数字全部匹配，而不是部分匹配

v0.21.0 敏感词新特性之白名单支持单个编辑，修正白名单包含黑名单时的问题

v0.23.0 敏感词结果条件拓展，内置支持链式+单词标签

v0.24.0 新特性支持标签分类，内置实现多种策略

v0.25.0 新特性之 wordCheck 策略支持用户自定义

v0.25.1 新特性之返回匹配词，修正 tags 标签

v0.27.0 敏感词库独立拆分

v0.28.0+v0.29.0 敏感词性能优化值本地方法调用为何这么慢?

v0.29.1 敏感词性能优化-0.29.1-内部类+迭代器内部类

v0.29.2 基本类型拆箱、装箱的进一步优化的尝试

vv0.29.3 依赖的繁简体转换 opencc4j 优化

NLP 开源矩阵

pinyin 汉字转拼音

pinyin2hanzi 拼音转汉字

segment 高性能中文分词

opencc4j 中文繁简体转换

nlp-hanzi-similar 汉字相似度

word-checker 拼写检测

sensitive-word 敏感词