Go 敏感词过滤实战：DFA/Trie 匹配与 AC 自动机选型-北京尧图网络

简介Sensitive-word-filtering 是一份面向 Go 开发者与内容安全场景的轻量敏感词过滤实现核心沿用 Java 版 DFA 算法思路并迁移至 Go适合需要在服务端快速接入关键词检测、文本校验或替换功能的开发者参考。压缩包共 6 个文件约 3KB以 4 个 go 源码、1 个 dict 词库和 1 个 md 说明为主go 文件承载 DFA 匹配与替换逻辑dict 提供可直接加载的词条数据md 用于交代用法与结构。当前已有 1911 人学习下载。使用时可在项目 init 方法中调用 ReadSwfDict 加载词库在检查点调用 Match 完成验证或用 Repl 进行敏感词替换词库取自百度搜索的临时版本支持替换为其他词库并自行添加词条具体示例见 swf_test.go。整体代码量小、结构直接便于嵌入现有 Go 项目也为二次扩展词库与匹配规则留出空间。1. 从一条用户昵称开始这套 Go 敏感词过滤到底解决什么问题上周某社区项目的注册接口被一串变体昵称刷屏运营同学拿着截图问能不能在上线前拦住。这个用 Go 写的 Sensitive-word-filtering 资源核心就是一件脏活把公开词库和业务自定义词库装进内存用 DFA 做多模式匹配在毫秒级完成命中、替换和返回位置。它适合需要自建内容风控前置层的后端、社区、IM、评论系统也适合想拆一套可扩展词库加载逻辑的 Go 开发者。词库不是魔法边界和误伤才是落地时要盯的地方。2. 选 DFA 还是 AC 自动机词库规模决定数据结构敏感词过滤听起来像“把词表扔进正则”真放到接口链路里就会变成性能事故。正则引擎在多模式匹配时会反复回溯词库一多单次请求的耗时能从几百微秒涨到几十毫秒更麻烦的是正则对“符号穿插”和“大小写变体”的处理很难做到既准确又可控。这个资源选择用 Go 手写匹配器把词库构建成前缀树再用状态转移完成扫描本质是把匹配成本前移到启动阶段。2.1 Trie 与 DFA 的匹配过程Trie 的思路很直白每个节点代表一个字符从根节点往下走能走通就说明当前片段是某个词的前缀走到带结束标记的节点就命中一个词。DFA 是在 Trie 上做状态转移扫描文本时不需要为每个起点重新构建状态机而是沿着已有的子节点继续走。对短文本、几万条词库这种结构足够稳代码也好维护。假设词库里有“敏感词”“敏感”“过滤”三个词构建出来的树根节点下挂“敏”再挂“感”然后分叉出“词”和“过”。扫描“这段敏感词内容”时从“敏”开始一路走到“感”发现“感”节点带结束标记记录一次命中继续走到“词”又命中更长的词。这里有一个关键选择记录最短命中还是最长命中。业务上通常要最长匹配否则“敏感词”会被“敏感”截断替换结果变成“**词”看起来就很怪。朴素 Trie 的匹配复杂度可以粗略看成 O(n×m)n 是文本长度m 是最长词长。文本短、词库小的时候完全够用如果一次要扫几 KB 的评论或者词库几十万条就得考虑 AC 自动机。Go 里用map[rune]*node实现 Trie 写起来快但每个节点一个 map 的内存开销不小词库规模上去后要换更紧凑的存储。2.2 AC 自动机什么时候值得上AC 自动机在 Trie 上补了失败指针扫描文本时不需要回退复杂度接近 O(n命中数)。它的优势在长文本和大词库比如站内搜索的关键词审核、文章发布前的全文扫描、批量导入的历史内容清洗。代价是实现复杂度高构建失败指针时要处理 BFS 队列和根节点回退排错不如 Trie 直观。我一般按两个信号判断要不要上 AC词库超过十万条或者单次待检文本经常超过 2KB。低于这个量级DFA 加最长匹配已经够快没必要为了“看起来高级”把维护成本拉满。另一个信号是命中密度如果一篇文章里可能命中几十个词AC 的失败指针能减少重复扫描如果只是昵称、标题这种短文本DFA 的简单路径更划算。这套资源的核心是 DFA 版本词库可扩展适合先跑通业务闭环。真遇到性能瓶颈再按接口层做切分短文本走 DFA长文本走 AC或者把长文本拆段后并行扫描。不要一上来就双数组 Trie调试成本会把排期吃掉。2.3 词库加载与内存估算词库文件通常是 UTF-8 文本一行一个词空行和#开头的注释跳过。加载时要做三件事去掉 BOM、去掉行尾空白、统一做大小写和全半角归一化。别小看这三步线上最常见的就是第一行带\ufeff导致第一个词永远不命中排查半天以为是匹配算法坏了。内存估算可以按“总字符数约等于节点数”来粗算。十万条词平均每条 5 个字符节点数大约 50 万每个节点如果用一个 map光 map 的桶和键值对就可能吃掉几百 MB。实际项目里我会先跑一个加载测试用runtime.ReadMemStats看堆增长再决定要不要换map[rune]int32的紧凑版或者双数组。词库不是越大越好很多业务词库里有大量长尾词和重复词合并去重后能省不少内存。提示词库加载放在服务启动阶段不要放在请求处理函数里。每次请求重新读文件、重新建树QPS 会被磁盘和 GC 一起拖垮。3. 把词库跑起来Go 工程里的最小可用实现这一章按“能跑、能查、能替换、能对外提供接口”的顺序落地。代码不追求大而全但每个函数都对应一个实际参数和边界拿到后可以先在本地跑通再替换成自己的词库目录。3.1 目录结构与词库准备我习惯把内置词库和业务词库分开内置词库只读业务词库放在独立目录启动时合并。这样升级词库不会覆盖业务自定义内容回滚也简单。路径用途是否可写dict/base.txt公开基础词库否dict/custom/*.txt业务自定义词库是dict/whitelist.txt白名单命中后跳过是cmd/server/main.goHTTP 服务入口否internal/filter/filter.go匹配器实现否词库文件格式保持简单一行一个词空行跳过#开头是注释。不要用 CSV敏感词里出现逗号、引号很常见CSV 解析会多一层转义坑。# 目录初始化词库文件按行存放UTF-8 编码 mkdir -p dict/custom cmd/server internal/filter printf 敏感词\n过滤\n dict/base.txt printf # 业务自定义词一行一个\n某品牌名\n dict/custom/business.txt上面这段只是把目录和最小词库摆好。实际拿到资源包后先把基础词库放进dict/base.txt业务词库按领域拆成多个文件比如comments.txt、nickname.txt。拆文件的好处是排查时能快速定位是哪一类词导致误伤合并加载时用同一个构建流程。3.2 构建过滤器与加载词库下面这段是核心结构node存子节点和结束标记Filter持根节点、读写锁和替换字符。AddWord对词做归一化LoadFile逐行读取并跳过空行和注释。package filter import ( bufio os strings sync unicode ) type Match struct { Start int // 命中起始位置按 rune 计 End int // 命中结束位置不包含 End Word string // 原文中命中的片段 } type node struct { children map[rune]*node end bool } type Filter struct { root *node mu sync.RWMutex replace rune } func New(replace rune) *Filter { return Filter{ root: node{children: make(map[rune]*node)}, replace: replace, } } // normalizeRune 做全角转半角、转小写并跳过空白和常见分隔符 func normalizeRune(r rune) (rune, bool) { if r 0xFF01 r 0xFF5E { r - 0xFEE0 } if r 0x3000 { return 0, false } r unicode.ToLower(r) if unicode.IsSpace(r) { return 0, false } switch r { case -, _, ., *, |, /, \\, ~, , !, , #, $, %, ^, , (, ), [, ], {, }, , , ,, ?, :, ;, \, : return 0, false } return r, true } func normalizeText(s string) string { var b strings.Builder for _, r : range s { if nr, ok : normalizeRune(r); ok { b.WriteRune(nr) } } return b.String() } func (f *Filter) AddWord(word string) { norm : normalizeText(word) if len([]rune(norm)) 0 { return } f.mu.Lock() defer f.mu.Unlock() p : f.root for _, r : range norm { child, ok : p.children[r] if !ok { child node{children: make(map[rune]*node)} p.children[r] child } p child } p.end true } func (f *Filter) LoadFile(path string) error { file, err : os.Open(path) if err ! nil { return err } defer file.Close() scanner : bufio.NewScanner(file) scanner.Buffer(make([]byte, 0, 64*1024), 1024*1024) for scanner.Scan() { line : strings.TrimSpace(scanner.Text()) line strings.TrimPrefix(line, \ufeff) if line || strings.HasPrefix(line, #) { continue } f.AddWord(line) } return scanner.Err() }New的replace参数决定替换字符常见用*或#。AddWord里先归一化再入树保证“”和“sensitive”落到同一路径。LoadFile里scanner.Buffer把单行上限调到 1MB防止超长词库行把扫描器撑爆TrimPrefix去掉 BOM解决第一行不命中的玄学问题。这里用sync.RWMutex是为了兼容后续热更新。如果服务启动后词库完全不变可以把锁去掉读性能会更好但只要留了“在线加词”的口子就别省这把锁。3.3 匹配、替换与边界参数匹配时要做位置映射原文里可能有空格、标点、全角字符归一化后的文本长度会变命中位置必须能映射回原文否则替换会错位。func normalizeWithIndex(text string) ([]rune, []int) { runes : []rune(text) out : make([]rune, 0, len(runes)) idx : make([]int, 0, len(runes)) for i, r : range runes { if nr, ok : normalizeRune(r); ok { out append(out, nr) idx append(idx, i) } } return out, idx } func (f *Filter) FindAll(text string) []Match { f.mu.RLock() defer f.mu.RUnlock() runes, idx : normalizeWithIndex(text) var matches []Match for i : 0; i len(runes); i { p : f.root lastEnd : -1 for j : i; j len(runes); j { child, ok : p.children[runes[j]] if !ok { break } p child if p.end { lastEnd j 1 // 记录最长命中避免短词截断长词 } } if lastEnd i { start : idx[i] end : idx[lastEnd-1] 1 all : []rune(text) matches append(matches, Match{ Start: start, End: end, Word: string(all[start:end]), }) i lastEnd - 1 } } return matches } func (f *Filter) Replace(text string) string { matches : f.FindAll(text) if len(matches) 0 { return text } all : []rune(text) var b strings.Builder last : 0 for _, m : range matches { b.WriteString(string(all[last:m.Start])) for i : m.Start; i m.End; i { b.WriteRune(f.replace) } last m.End } b.WriteString(string(all[last:])) return b.String() }normalizeWithIndex返回归一化后的 rune 序列和每个 rune 在原文中的索引。FindAll用lastEnd记录最长命中命中后把i跳到lastEnd-1避免重叠词重复输出。Replace按 rune 位置替换不会把多字节字符切坏。参数上要盯住几个点replace只影响输出不影响命中跳过符号的范围要克制别把句号、问号也跳掉否则“敏感。词”会被跨句匹配最长匹配是默认策略如果业务需要同时返回短词可以在命中时把路径上的所有end都收集起来但替换仍按最长区间走。3.4 封装成 HTTP 接口接口层只做三件事解析请求、调用过滤器、返回命中词和替换结果。不要在这里做词库加载也不要把敏感词明文写进日志。package main import ( encoding/json net/http sensitive/internal/filter ) type checkRequest struct { Text string json:text } type checkResponse struct { Hit bool json:hit Words []string json:words Replaced string json:replaced } func checkHandler(f *filter.Filter) http.HandlerFunc { return func(w http.ResponseWriter, r *http.Request) { var req checkRequest if err : json.NewDecoder(r.Body).Decode(req); err ! nil { http.Error(w, bad request, http.StatusBadRequest) return } matches : f.FindAll(req.Text) words : make([]string, 0, len(matches)) for _, m : range matches { words append(words, m.Word) } w.Header().Set(Content-Type, application/json; charsetutf-8) _ json.NewEncoder(w).Encode(checkResponse{ Hit: len(matches) 0, Words: words, Replaced: f.Replace(req.Text), }) } } func main() { f : filter.New(*) if err : f.LoadFile(dict/base.txt); err ! nil { panic(err) } http.HandleFunc(/check, checkHandler(f)) _ http.ListenAndServe(:8080, nil) }checkHandler里FindAll和Replace各扫一遍文本短文本没问题如果文本很长可以先拿FindAll的结果自己拼替换串少扫一次。返回结构里保留Words是为了运营排查但对外接口要考虑是否脱敏别把命中的敏感词原样吐给前端。4. 词库扩展与变形对抗不是加词就完事词库扩展最容易犯的错是“把能想到的词全塞进去”。词越多误伤概率越高内存和匹配耗时也上去。真正要解决的是哪些词必须硬拦哪些词交给人工审核哪些变体用归一化处理哪些变体只能靠样本积累。4.1 自定义词库的合并与去重业务词库按领域拆文件后启动时合并成一个树。合并前先做去重和长度过滤单字词单独放一个文件默认不启用避免“售”“代”这种字把正常词全误伤。func LoadDir(f *filter.Filter, dir string) error { entries, err : os.ReadDir(dir) if err ! nil { return err } seen : make(map[string]struct{}) for _, entry : range entries { if entry.IsDir() || !strings.HasSuffix(entry.Name(), .txt) { continue } path : filepath.Join(dir, entry.Name()) file, err : os.Open(path) if err ! nil { return err } scanner : bufio.NewScanner(file) for scanner.Scan() { word : strings.TrimSpace(strings.TrimPrefix(scanner.Text(), \ufeff)) if word || strings.HasPrefix(word, #) { continue } if _, ok : seen[word]; ok { continue } seen[word] struct{}{} f.AddWord(word) } file.Close() if err : scanner.Err(); err ! nil { return err } } return nil }LoadDir只处理.txt去重用的是原始词字符串不做归一化去重。原因是归一化后“”和“AB”会合并但它们在词库里可能代表不同来源保留原始行便于审计。真正入树时AddWord会再归一化重复路径不会重复建节点。自定义词库要留版本号比如文件名带日期或在文件头写# version: 2025-06。出问题时能快速回滚到上一版词库不用从备份里翻半天。4.2 全半角、大小写与符号穿插变体对抗的第一层是归一化全角转半角、大写转小写、跳过空白和常见分隔符。上面normalizeRune已经做了这些。第二层是重复字符比如“敏敏感感词词”要不要压缩我的建议是不要默认压缩压缩会带来新的误伤比如正常叠词“天天”“看看”被压成单字后命中单字词库。符号穿插要谨慎。跳过-、_、*这类符号能拦住“敏-感-词”但跳过太多标点会让“敏感。词”跨句命中。常见做法是只跳过低信息量的连接符保留句号、问号、感叹号作为边界。如果业务需要更强的对抗可以在归一化阶段记录跳过的字符数命中后回看原文超过阈值就降级为“疑似”而不是直接拦截。// 只跳过连接符和空白保留句末标点作为边界 func isSkippable(r rune) bool { switch r { case -, _, *, |, /, \\, ~, , : return true } return unicode.IsSpace(r) }这段isSkippable是给需要更细控制的场景用的。把它替换进normalizeRune的 switch 里就能把跳过范围收窄。参数没有绝对标准按业务样本调昵称场景可以多跳一点文章正文场景要保守。4.3 拼音、谐音与变体词的处理边界拼音和谐音是敏感词过滤里最容易过度设计的地方。把“敏感词”转成拼音全拼、首字母、谐音变体再全部塞进 Trie词库会膨胀几十倍误伤也跟着涨。更麻烦的是很多谐音只有结合上下文才成立单靠词表拦不住。我一般把变体分三档第一档是确定性变体比如全半角、大小写、符号穿插用归一化硬处理第二档是常见谐音人工维护一个小词表只在高风险场景启用第三档是拼音首字母和编辑距离不放进主匹配链路交给离线样本分析或人工审核队列。主链路只做确定性命中宁可漏一点也别把正常内容大面积误伤。如果一定要做拼音建议单独建一个索引不要和主词库混在一起。命中拼音索引后返回“疑似”由业务决定是拦截还是进审核。这样主链路的性能和准确率都可控排查时也能分清是词库问题还是变体规则问题。5. 避坑排查五个线上翻车现场这套东西代码量不大坑却不少。下面五条都是我在不同项目里真实遇到过的类型按“现象、原因、解决”拆开写方便对照排查。5.1 词库第一行永远不命中现象词库文件里明明有某个词接口就是不返回命中换一个词放到第二行就正常。原因文件保存成了带 BOM 的 UTF-8第一行开头多了\ufeff入树时这个词变成“\ufeff敏感词”匹配时文本里没有这个字符自然走不到结束节点。解决加载时统一strings.TrimPrefix(line, \ufeff)并且在 CI 里加一条检查词库文件不允许 BOM。顺带把 CRLF 也处理掉bufio.Scanner默认按行切行尾可能带\rTrimSpace能兜住但最好在编辑器里统一成 LF。5.2 长词被短词截断现象词库里有“敏感词”和“敏感”文本里明明是“敏感词”替换结果却是“**词”。原因匹配时一遇到end就返回没有继续往下走短词先命中长词被截断。解决在循环里用lastEnd记录最长命中走完整条路径再返回替换时按最长区间处理。如果业务需要同时返回短词可以在命中时收集路径上的所有end但拦截和替换仍以最长词为准。5.3 单字词和白名单导致误伤现象正常商品描述里的“售后”“客服”被拦运营反馈“你们这个过滤太傻了”。原因词库里有单字词“售”“客”或者短词没有配白名单匹配器按子串命中正常词被误伤。解决单字词单独放一个文件默认不加载必须加载时配白名单白名单命中的区间直接跳过。白名单也要做最长匹配否则“售后服务”被白名单“售后”截断后后面的“服务”又可能被其他词命中。上线前用正常样本跑一遍误报率别只看拦截率。5.4 热更新触发并发读写崩溃现象服务运行一段时间后突然fatal error: concurrent map read and map write重启后恢复。原因在线加词直接往正在被请求读取的 Trie 里写childrenmap读和写没有隔离。解决要么全程用RWMutex读加读锁、写加写锁要么用双缓冲新词库构建到新树构建完用atomic.Value整体替换读路径无锁。双缓冲更适合词库大的场景但要注意旧树被正在处理的请求引用GC 会晚一点回收内存峰值会短暂翻倍。5.5 每个请求重新加载词库拖垮 QPS现象压测时 QPS 上不去CPU 花在文件读取和 map 构建上GC 频繁。原因过滤器在 handler 里New然后LoadFile每个请求都建一遍树。解决启动时加载一次handler 复用同一个实例词库变更走热更新接口不在请求链路里读文件。压测时用go test -bench看单次FindAll的耗时再结合pprof看内存分配别凭感觉优化。6. 验证与调优用基准测试和误报样本收口最后一章落到验证。敏感词过滤不是“跑通就行”上线前至少要有基准测试、误报漏报样本和回滚方案。基准测试用来确认单次匹配耗时和内存分配样本集用来确认业务边界回滚方案用来兜住词库更新带来的意外。6.1 基准测试与内存观测func BenchmarkFindAll(b *testing.B) { f : filter.New(*) if err : f.LoadFile(dict/base.txt); err ! nil { b.Fatal(err) } text : strings.Repeat(这是一段正常的商品描述包含售后和客服。, 100) b.ResetTimer() b.ReportAllocs() for i : 0; i b.N; i { _ f.FindAll(text) } }b.ReportAllocs能看到每次匹配的分配次数FindAll里normalizeWithIndex会分配切片文本越长分配越多。如果分配成为瓶颈可以复用缓冲区把out和idx放进sync.Pool但要注意并发安全。基准测试的文本要贴近真实业务别只用短昵称测长评论和文章正文的耗时差一个量级。指标观察方式处理阈值单次匹配耗时go test -bench短文本低于 1ms每次分配次数-benchmem稳定后可接受少量分配堆内存增长runtime.ReadMemStats加载后观察避免持续上涨误报率正常样本集按业务容忍度定6.2 误报漏报样本集与灰度样本集分三组正常样本、确定命中样本、变体样本。正常样本从线上日志里脱敏抽样确定命中样本用词库里的词构造变体样本放全半角、符号穿插、大小写混写。每次改词库或改归一化规则三组都跑一遍记录误报和漏报数量。别只看“拦截率”误伤正常用户带来的投诉往往更贵。灰度时先切只记录不拦截的模式把命中结果写进审计表观察一周再决定是否开启替换。审计表里不要存敏感词明文存哈希或词 ID避免日志本身成为泄露源。6.3 热更新与版本回滚热更新用atomic.Value存当前过滤器构建新树成功后整体替换失败就保留旧树。词库文件带版本号回滚时把版本号指回上一版重新加载即可。我一般会在管理接口里加一个GET /dict/version返回当前词库的文件名、加载时间和词条数出问题时先看这个比翻日志快。从那以后我每次上线词库都强制走一遍“基准测试、三组样本、灰度观察”的流程哪怕只加了一个词。词库是活的业务在变变体也在变靠一次配置吃半年不现实。希望帮到你。本文还有配套的精品资源点击获取

Go 敏感词过滤实战：DFA/Trie 匹配与 AC 自动机选型

相关推荐

华为昇腾AI算子库CANN ops-nn架构解析与性能优化

通用型物联网平台架构设计与关键技术解析

华为CANN栈：AI异构计算性能优化实战

更多资讯

第七章异步访问的同步：7.8 同步机制的驱动集成

Zenith ZPS-4043-5网络设备核心功能与部署指南

Qwopus3.6-27B-Fusion-GGUF架构解析：混合注意力机制与262K上下文窗口的强大组合

Lambda表达式：函数式编程的核心特性与应用实践

2025代码大模型新标杆：Qwen3-Coder重构企业开发范式

WebHomeTV 扩展脚本快速上手：10 分钟给你的影视网站注入 App 原生播放能力

今日更新

AI智能体开发实战：从技术原理到商业落地

OpenShell 完全定制指南：从安装到深度配置，打造高效 Windows 开始菜单

Superpowers技能体系全解析：从Skills引入到安装的完整指南

本周精选

防幻觉智能体架构：电源硬件设计中的大模型编排与工具化实践

OpenGL面试核心考点：渲染管线、矩阵变换与性能排查全解析

全国计算机二级C语言真题PDF高效刷题指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？