简介代码重复检测工具Simian的完整发布包与配套文档专为Java、C#、C及JavaScript等项目的开发者和质量保障人员准备用于排查重复代码块、降低复制粘贴带来的维护负担。压缩包以gz格式打包共59个文件大小3.43MB包含可直接运行的JAR和EXE程序、依赖的DLL库、PDF与TXT格式的许可证说明、HTML格式的帮助手册、CSS样式表、PNG和GIF界面素材以及DTD和XSL报告格式定义能够满足本地安装、命令行调用和报告解析等多类使用需求。目前已有1416人下载学习。借助这份资料读者可以快速启动Simian的重复扫描通过配置文件设定检测灵敏度与忽略规则并将报告集成到Maven或Gradle构建流程中作为持续集成质量门禁使用同时随包提供的官方文档和示例页面也能帮助新人理解各项参数含义减少重复代码的引入。1. simian代码重复检测工具在查什么被复制三遍的代码改一个 bug 要命接手旧项目时最怕的不是看不懂而是在三个不相关的文件里看到几乎一样的 50 行逻辑。改一处 bug另外两处得跟着改漏一处就是线上事故。代码重复是最隐蔽的技术债评审时没人替你指出来但它每天在消耗维护成本。simian代码重复检测工具就是专门做这件事的扫描源代码把超过指定长度的重复代码块找出来输出报告告诉你重复集中在哪个文件、哪几行。它解决的不只是谁抄了谁的问题而是给重构提供一个可量化的起点。适合接手老项目、准备做结构性重构、以及想在 CI 里拦住新增重复代码的人。2. simian 怎么找重复从 Token 序列到重复块判定2.1 为什么是 simian而不是 diff 或 grep先想清楚一个问题代码重复为什么难发现因为重复往往不是逐字相同的。A 同学在订单模块写了一轮校验逻辑B 同学在支付模块复制过去后把变量名从 orderId 改成 payId加了一行日志缩进也可能不同。这时候用 grep 搜同一个字符串搜不到用 diff 比对两个文件又会因为上下文不同而产生大量无关差异。人工评审更不可能把每个文件拼在一起逐行比对。simian 这类工具的做法是先不碰文本而是把源码拆成语义上的最小单位 Token再在 Token 序列里找重复子序列。变量名不同、字符串不同、空行缩进不同只要结构骨架一样它就能识别出来。不用 AST 级别的克隆检测工具是因为它们的集成成本高。很多静态分析平台具备克隆代码检测能力但需要配置规则、起服务、维护插件对一个刚开始重视重复问题的仓库来说太重了。simian 是单 jar 包、命令行工具一条命令出报告没有一堆依赖。它牺牲了 AST 级别的语义理解换来的是极低的接入成本。如果你的目标只是先摸清仓库里哪些地方在复制粘贴它是性价比最高的切入点。2.2 Token 化与规范化三个步骤决定检测结果simian 的核心流程分三步弄清这三步后面调参就不会靠猜。第一步是词法拆解。simian 把每个源文件的内容切成 Token 流不同语言用各自的词法规则切。对 Java 来说public、class、void这类关键字是一个 Token标识符是一个 Token数字字面量是 Token括号分号也各算一个 Token。空白、换行、注释在默认情况下不进入 Token 流所以缩进风格不同、注释写得多或少不会影响重复判定。这一步让视觉上不一样的代码在 Token 层面变得可比。第二步是可选规范化。simian 提供几个开关让你决定哪些 Token 差异可以被忽略。最常用的三个-ignoreStrings忽略字符串字面量内容比如订单创建成功和支付创建成功会被当成同一个 Token-ignoreCharacters作用类似针对单个字符-ignoreVariableNames忽略变量名差异orderId 和 payId 在比较时视为等价。注意这三个开关是独立的默认都不开。实际项目里我至少会打开-ignoreVariableNames否则复制代码时把变量名一改工具就认为不重复检测就失去了意义。第三步是滑动窗口匹配。simian 会设定一个阈值-threshold表示至少多少行代码才算重复。它把所有 Token 流放在一起在流上开一个候选窗口向后搜索长度达到阈值的相同 Token 子序列再把这个子序列尽量向两端扩展直到找不到更多相同 Token 为止。扩展后的完整区间就是一个重复块。所以 threshold 越小找到的候选越多误报也越多threshold 越大查出来的是整段整块的复制但小段重复会漏掉。2.3 输出模型重复组、文件位置与行长区间理解 simian 的报告要先理解它的组织模型。一个重复组set里包含多个代码位置每个位置block有文件名和起始行号、结束行号。同一个重复块出现在三个文件里你会看到三个 block它们属于同一个 set。严谨的说法是这组位置彼此两两重复而不是某文件重复了。text 格式下输出大致长这样Found a duplicate of 12 lines in the following files: src/main/java/com/example/order/OrderValidator.java Lines: 42-53 src/main/java/com/example/pay/PayValidator.java Lines: 87-98行号区间是闭区间也就是包含第 42 行和第 53 行。我在处理报告时更倾向于直接生成 XML因为 XML 里 block 会带sourceFile、startLineNumber、endLineNumber属性方便写脚本做增量对比和统计。text 格式适合人肉快速确认XML 适合机器处理这一点前后不要混。牢记这个模型还有一个用处当你看到某个文件出现在多个 set 里说明它是重复源头的重灾区当一个 set 里有 4 个 block说明这段逻辑被复制了 4 份重构时优先处理收益最大。3. 本地跑通 simian最小命令与四个必调参数3.1 环境准备拿到 jar 包并确认可用simian 是 Java 工具机器上要有 Java 运行时。获取方式一般是两个从项目发布渠道下载 jar 包或者由团队统一放在制品库里。我建议把固定版本的 jar 提交到团队内部仓库不要每个人各自下载否则版本不一致会导致报告对不上这在 CI 排查时会很痛苦。拿到 jar 包后先验证环境不要直接扫大项目java -version java -jar simian.jar -?第一条命令确认 JRE 版本够用第二条确认 jar 包完整并且会打印当前支持的参数列表。不同版本的参数措辞有细微差异以实际帮助信息为准不要背参数名要会看帮助。3.2 最小命令扫一个 Java 目录假设项目是常见的 Maven 结构源码都在src/main/java下。最简单的检测命令如下java -jar simian.jar -includes**/*.java -threshold6 .命令末尾的.表示从当前目录开始递归搜索-includes限定只收集 Java 文件。-threshold6的意思是少于 6 行的重复不考虑。为什么不设成更小因为三五行的小重复大概率是框架模板比如一个getter、一个空方法、一个 try-catch 骨架这些噪声会淹没真正有重构价值的重复块。我的习惯是先设 6 跑一遍看整体规模再根据报告决定往上还是往下调。第一次跑完的预期是终端打印扫描文件数、重复组数和耗时。如果几秒就跑完大概率是-includes没匹配上文件一定要检查输出里的扫描文件数确认不是 0。3.3 输出格式从 text 切到 XML默认输出是 text不加参数时 simian 会把重复块逐条打印在终端。文件一多就刷屏而且不方便二次处理。我建议一上来就用 XML 输出保留原始报告java -jar simian.jar -includes**/*.java -threshold6 -reportFormatxml dup.xml-reportFormatxml把报告写进标准输出再用重定向落到dup.xml。如果当前版本支持-outputFile参数直接用参数更省事。XML 报告里每个 block 的行号、文件路径都结构化保存后面做基线对比、写统计脚本都靠它。3.4 四个必调参数先抄这一张表参数不需要全背真正影响结果的是下面四个。参数作用我常用的值-threshold最小重复行数6 10-ignoreVariableNames忽略变量名差异开-ignoreStrings忽略字符串字面量差异开-includes/-excludes文件过滤includes 按语言写excludes 排除生成代码-ignoreStrings很多人不敢开担心把两个文案完全不同但结构一样的提示框当成重复。这个担心是多余的重复检测的价值在于找结构复制字符串内容不同是后续人工确认的事。关掉它报告里全是订单创建成功和支付创建成功的一字之差反而没法看。-excludes必须把生成代码排除。常见的是target、build、以及代码生成器输出的 Java 文件。不排除的话生成代码本身就高度重复会占满报告前几十页业务里的真重复被彻底淹没。我一般这样写java -jar simian.jar \ -includes**/*.java \ -excludes**/target/**;**/build/**;**/generated/** \ -threshold6 \ -ignoreVariableNamestrue \ -ignoreStringstrue \ -reportFormatxml dup.xml这里-excludes的多个模式用分号分隔常见做法是把**/target/**这类中间层目录排除掉注意通配符要保留两层**否则可能在部分平台上匹配不到。调参的过程不复杂。第一次扫描只看两个数字报告总页数和 Top 重复文件。如果总页数超过几十页说明阈值太低如果报告短得离谱先确认扫描文件数不为 0再确认生成代码有没有混进来。连续调两轮找到一个报告能读完、且每一条都值得人工确认的阈值这就是你这个项目的基准配置。4. 把 simian 接进 CI让新增重复在合并前被拦住4.1 CI 任务的最小形态本地跑通只是第一步真正有价值的是让每次构建自动检查新增重复。常见做法是在流水线的静态检查阶段加一个任务下载 simian jar执行全量扫描把 XML 报告留档。最粗暴的门禁是加-failOnDuplicationtrue一旦发现超过阈值的重复块构建直接失败。但第一次接入时不要直接开启失败策略先跑两周收集数据摸清报告的基准体量再决定阈值和例外名单。下面是 CI 脚本里最常见的写法set -e java -jar simian.jar \ -includes**/*.java \ -excludes**/generated/**;**/target/** \ -threshold8 \ -ignoreVariableNamestrue \ -ignoreStringstrue \ -reportFormatxml \ -failOnDuplicationfalse \ -outputFiledup.xml说明几点。set -e保证 simian 异常退出时脚本立刻失败排错时能看到是哪一步挂了。-failOnDuplicationfalse在前两周一直保持这个值只产出报告不改节奏。-outputFile在有这个参数的版本里直接用没有就重定向。CI 里最关键的还有一点jar 包的版本必须锁死用制品库里固定路径的产物不要每次动态拉最新版否则报告口径一直在漂移。4.2 增量检测只拦新增重复不翻历史旧账老仓库里积累了几年的重复代码一搜一大堆直接 fail 会把整个队伍卡死。真正该拦的是这次改动新增的重复。增量检测常见做两种我分别说清楚优缺点。第一种是基线对比。在主干上保存一份报告作为数据基线每次 MR 跑完本次扫描后用脚本把本次结果和基线做差新增的重复组才报错。这个方案稳定不需要 simian 提供额外功能只需要写一个解析 XML 的脚本。它的缺点是维护成本高每次基线更新都要人工确认它是健康的。第二种是只扫变更文件。从 git 里取本次变更的 Java 文件把它们单独放进临时目录或者直接通过-includes传进去simian 只在这批文件里找重复。局限很明显它只能发现本次文件之间或本次文件内部的重复发现不了新文件和老文件重复。后者恰恰是复制粘贴最常见的来源。所以我从不单独用方案二最多在方案一的报告里批量复核时辅助一下。这里给一个解析 XML 的 Python 片段模拟项目 X 里我用来做基线对比的脚本你可以直接改路径用import xml.etree.ElementTree as ET tree ET.parse(dup.xml) sets tree.getroot().findall(set) for s in sets: blocks s.findall(block) if len(blocks) 2: continue locs | .join( f{b.get(sourceFile)}:{b.get(startLineNumber)}-{b.get(endLineNumber)} for b in blocks ) print(locs)注意不同版本 simian 的 XML 节点属性名可能略有不同sourceFile、startLineNumber、endLineNumber是常见命名。跑一次后用less dup.xml看一下结构确认属性名再批量跑否则脚本会静默解析出一堆 None。4.3 门禁阈值怎么定用历史报告的中位数说话门禁阈值不能拍脑袋。常见做法是看历史报告里的行长分布把老报告里所有重复组的行长取出来算分布取 P50 或 P60 作为阈值。如果历史数据里 50% 的重复组在 8 行以下说明小重复是常态那就把-threshold设为 8只拦超过 8 行的大段重复。第二步是把常见误报模式加进-excludes。这类误报很有规律自动生成的 POJO、接口的默认实现、日志模板块。把这些路径提前排掉报告里剩下的重复质量会显著提升。第三步是允许部分存量文件豁免。对重复非常严重的文件加一个最差文件名单这些文件允许继续存在但禁止新增重复组。实现方式是在报告解析脚本里维护一个豁免文件列表属于这些文件的 block 不参与 fail 判断。所有这三个选择都要写进 CI 脚本的注释里写清楚为什么这么设、基线数据是哪一天采集的。否则半年后没人敢动这条规则它就成了黑匣子最后要么被绕过要么被整个关掉。5. simian 常见问题与排查5 个翻车记录5.1 历史代码全是重复报告几千页根本没法看现象第一次在旧项目上跑 simian报告文件大得编辑器都打不开Group 数量上万。原因两个问题叠加。第一是-threshold设得太低三四行的模板代码全被识别成重复第二是生成代码没有排除target、build里的自动生成 Java 文件本身就高度雷同占据了报告大半篇幅。解决先把-threshold提到 10跑一遍看整体规模同时把**/generated/**、**/target/**等路径写进-excludes。仍然太多就往 15 提直到报告精简到两百页以内。这一步的目的不是消灭重复而是让报告可读。5.2 开了-ignoreVariableNames重复组数量一点没降现象参数明明加了-ignoreVariableNamestrue报告里的重复组数量和之前差不多。原因最常见的情况是变量名确实被忽略了但字符串内容差异没有忽略。两个结构相同的代码块一个写订单创建成功一个写支付创建成功在字符串 Token 上就被判定为不同。另一个原因是项目里重复的是字段名或方法名这些不是局部变量不在该参数的覆盖范围内。解决同时打开-ignoreStringstrue组合使用。如果重复组的核心差异确实来自标识符命名确认这些标识符是局部变量还是字段名。方法是拿一条具体报告做试验改一组参数跑一次对比同一段代码是否消失比闷头猜快得多。5.3 Windows 上能跑通Linux CI 上扫描文件数为 0现象本地 Windows cmd 里执行命令没问题同样的脚本放到 Linux 流水线上输出显示扫描到 0 个文件。原因shell 对通配符的处理不同。在 Windows cmd 下**/*.java由 simian 自己展开在 Linux 下如果-includes的值没有加引号bash 会先尝试展开找不到匹配就把空值传给 simian最终匹配不到任何文件。解决在脚本里始终给-includes和-excludes的值加上引号用单引号更保险避免 shell 参与展开。例如java -jar simian.jar -includes**/*.java -threshold6 .这个写法在两个平台上都稳。另外要注意路径分隔符Windows 下反斜杠在双引号里会有转义问题能正斜杠就正斜杠。5.4 扫描大仓库超时或直接 OOM现象几千个文件的大仓库simian 跑到一半就报OutOfMemoryError或者把 CI 机器的 CPU 打满。原因simian 会把所有 Token 流放到内存里做窗口匹配仓库越大内存占得越厉害。另外如果.xml、.json、.sql这类资源也被-includes兜了进来文本量大Tokenizer 全按源码处理内存直接翻倍。解决第一在-excludes里明确排除资源文件和非源码文件第二把仓库按模块拆开一个模块一个扫描任务报告分开出第三给 JVM 加大堆内存命令开头加-Xmx4g。顺序不要反先确认没混入资源文件再考虑加内存否则加 8G 也白搭。5.5 同一份代码不同机器跑出的报告不一样现象开发者在本地扫出重复组 30 组CI 上扫出 28 组两边对比半天数量对不上。原因环境差异。常见的有三处simian 的 jar 包版本不同新版本词法规则有调整Java 运行时版本不同影响了文件读取的编码和字符处理方式-includes里用的是相对路径不同机器的工作目录不一致扫描范围天然不同。解决把 jar 包固定到制品库的同一路径加入校验CI 里统一 JDK 镜像版本本地开发也尽量用相同版本脚本里写死基线目录的绝对路径不依赖当前工作目录。排查顺序是先比版本再比工作目录最后比 JDK命中率最高。6. 进阶把 simian 报告换算成重构收益报告能看懂之后下一步是让数据指导排期。我有个习惯每次重构迭代前后各跑一次全量扫描把重复行数的变化记录成表格用趋势判断重构有没有真正生效。统计重复行数时要注意一个陷阱同一个重复组里有三个副本逐 block 累加会把该段代码算三遍。下面的脚本保留的是粗粒度总和理解它就好import xml.etree.ElementTree as ET tree ET.parse(dup.xml) total 0 for s in tree.getroot().findall(set): blocks s.findall(block) if len(blocks) 2: continue for b in blocks: start int(b.get(startLineNumber)) end int(b.get(endLineNumber)) total max(0, end - start 1) print(raw total lines involved in duplicates:, total)实际可精简的行数大概等于total * (副本数 - 1) / 副本数因为你保留一份就够了。这个数字可以直接放进迭代计划里跟产品说这一轮重构预计减少 800 行重复逻辑比空谈代码质量有说服力得多。优先级排序我一般不看总行数只看跨模块重复。同一个模块内部的重复通常是提取一个函数就能解决跨模块的重复往往意味着职责边界没划清比如两个服务各写了一套权限校验。把dup.xml里sourceFile的前两级路径取出来做分组同一个 set 里出现两个不同模块路径的标记为高优先级。我现在的习惯是固定每周五下午跑一次全量扫描把新增重复组的数量记进表格连续一个月下坡就说明重构真的在生效连续反复就说明约定没落地。希望帮到你。本文还有配套的精品资源点击获取