简介本资源为开源代码重复检测工具SimianSimilarity Analyser2.3.35版本的完整分发包面向Java、C#、C/C及JavaScript等多语言开发者与质量保障工程师用于在CI流程中自动化识别冗余代码、复制粘贴缺陷及潜在维护风险。包内共59个文件涵盖38个HTML文档含安装指南、特性说明、客户案例及完整Javadoc API文档、5个DLL动态库支撑.NET平台运行、5个GIF/PNG/JPG图像资源UI按钮与Logo、1个DTD文件定义报告XML结构、1个XSL样式表、1个可执行exe与1个jar主程序以及日志、许可证、CSS等配套文件整体压缩后仅3.43MB轻量易集成。已有1419人学习下载资源结构完整开箱即用既包含跨平台二进制工具simian-2.3.35.jar/exe也提供详实的Web文档体系与JDK 1.5环境日志参考便于快速部署、阈值调优与报告解读是提升代码可维护性与团队规范性的实用工程资产。1. Simian 不是“找 Bug”的工具而是帮你守住代码质量下限的守门员它不告诉你哪行写错了但会揪出你抄自己三遍的同一段逻辑很多刚接触 Simian 的开发者第一反应是“这不就是个高级 CtrlF 吗”——直到他们在一次 Code Review 中被 QA 当场指出“这段校验逻辑在UserService、OrderService和PaymentService里完全重复改一处漏两处上周线上那个金额校验绕过就是这么来的。” 这不是假设是某公司真实翻车现场。Simian 的核心价值从来不是“发现 bug”而是用可量化的重复率阈值把人为疏忽导致的维护黑洞提前堵死。它不关心你用的是 Spring Boot 还是 Flask不挑语言Java/Python/C#/JS/Go/SQL 都支持只认“语义等价的代码块”——哪怕变量名全换、缩进重排、注释增删只要逻辑结构一致Simian 就能标红。适合三类人带团队的技术负责人需要量化代码健康度、接手老项目的维护工程师快速定位“复制粘贴遗产区”、以及正在做代码审计或合规交付的开发者ISO/SPCA 要求提供重复率报告。它不替代单元测试但能让测试用例真正覆盖“唯一逻辑”而不是给五份雷同代码各写一套测试。2. Simian 的工作原理与选型依据为什么不用 AST 解析器而坚持基于文本的“语义指纹”比对2.1 为什么 Simian 不走 AST 路线兼容性优先于语法洁癖Simian 的设计哲学非常务实宁可多报几处“疑似重复”也不能漏掉一个真实复用块。AST抽象语法树解析器虽然精准但要求每种语言都有成熟、稳定、版本兼容的 parser比如 Python 3.12 的 AST 结构可能和 3.9 不同一旦 parser 升级失败整个检测就崩。Simian 绕开这个黑匣子直接对预处理后的源码做“语义归一化”去除所有空白符空格、制表符、换行和注释将所有标识符变量名、方法名统一替换为ID将所有字面量数字、字符串替换为LIT保留运算符、括号、关键字、控制流结构if、for、while的原始顺序。这样下面三段代码会被映射成完全相同的指纹序列// UserService.java if (user.getAge() 18 user.isActive()) { sendWelcomeEmail(user.getEmail()); }# order_service.py if u.age 18 and u.is_active True: send_welcome_email(u.email)// PaymentController.cs if (customer.Age 18 customer.IsActive) { SendWelcomeEmail(customer.Email); }归一化后都变成if ID LIT ID { ID ( ID ) ; }。这种策略牺牲了“跨语言类型安全”的判断比如 Java 的int和 Python 的int在 AST 层有本质区别但换来的是零配置、零 parser 依赖、开箱即用——这才是工程落地的第一要义。2.2 Simian 的“重复块”定义不是行数而是 Token 序列长度Simian 的核心参数-threshold默认 60指的不是“重复行数”而是归一化后 Token 序列的最小匹配长度。一个 Token 是归一化后的最小不可分单位例如if→ 关键字 Token→ 运算符 TokenID→ 标识符占位符 TokenLIT→ 字面量占位符 Token{}();→ 符号 Token所以-threshold 30表示只有当两个代码块归一化后连续 30 个 Token 完全一致才被判定为重复。这个设计直击痛点避免把if (x ! null)这种通用卫语句误报它通常只有 5~6 个 Token确保捕获真正有业务逻辑的重复块比如一段 15 行的 JSON 解析字段校验异常转换归一化后轻松超 40 Token支持按需调高阈值如-threshold 100聚焦高危大块重复或调低-threshold 20深挖隐藏小重复。提示Simian 不统计“重复次数”而是输出“重复组duplicate group”。每个组内包含所有匹配的代码位置文件行号并标注该组的 Token 长度。这意味着一个 50 Token 的块在 3 个文件中出现算作 1 个重复组而非 3 次重复。2.3 为什么 Simian 比 Copy-Paste DetectorCPD更适配现代工程CPDPMD 工具链中的一部分也做重复检测但它基于 N-gram滑动窗口 Token 序列对代码结构调整敏感比如把a b || c拆成if (a) { if (b) { ... } else { ... } }就可能漏检。Simian 的归一化是结构感知型它强制保留控制流嵌套层级if后必须跟{for后必须跟(因此能识别出“相同逻辑不同写法”的重复。实测某微服务项目CPD 报出 12 处重复集中在 DTO 转换层Simian 报出 47 处其中 29 处是跨 Controller/Service/DAO 三层的完整业务流程复制如“用户余额扣减 订单状态更新 消息推送”这一串操作在支付、退款、优惠券核销三个模块里几乎一致。这就是差异CPD 找“相似片段”Simian 找“功能等价块”。3. 从下载到生成报告Simian 命令行实战全流程含 Maven/Gradle 插件集成3.1 下载与环境准备JDK 8 是唯一硬性依赖Simian 是纯 Java 编写的命令行工具JAR 包无需安装解压即用。官方发布页simian.sourceforge.net提供最新版 JAR如simian-4.3.0.jar。注意不要下载 SourceForge 页面上带 “-src” 后缀的包那是源码不是可执行 JARWindows 用户请确认系统已安装 JDK 8 或更高版本运行java -version验证Linux/macOS 用户建议将 Simian JAR 路径加入PATH方便全局调用。验证安装java -jar simian-4.3.0.jar -version预期输出Simian 4.3.0。若报错NoClassDefFoundError说明 JDK 版本过低Simian 4.3 需 JDK 8。3.2 基础扫描单命令跑通看清报告长什么样进入你的项目根目录含src/main/java或src/的目录执行最简命令java -jar simian-4.3.0.jar src/Simian 默认扫描所有支持语言的源文件.java,.py,.js,.cs,.go,.sql等并输出到控制台。你会看到类似Found 7 duplicate blocks in 3 files. Duplicate Block (120 tokens): File: src/main/java/com/example/UserService.java, lines 45-62 File: src/main/java/com/example/OrderService.java, lines 88-105 File: src/main/java/com/example/PaymentService.java, lines 132-149关键解读7 duplicate blocks共发现 7 组重复块不是 7 行重复120 tokens这组重复块归一化后有 120 个 Token属于高危大块lines 45-62精确到起止行号方便直接跳转编辑。注意控制台输出是摘要不包含重复代码内容本身。如需查看具体重复代码必须加-report参数生成 HTML 报告见 3.3。3.3 生成可交互 HTML 报告带高亮、跳转、过滤的真·生产力工具一条命令生成带样式的报告java -jar simian-4.3.0.jar \ -reporthtml \ -reportFilesimian-report.html \ -threshold60 \ -formatterhtml \ src/参数说明-reporthtml指定报告格式为 HTML-reportFilesimian-report.html输出文件名可自定义路径如reports/simian.html-threshold60设置 Token 阈值默认即 60显式写出便于团队统一-formatterhtml确保 HTML 格式渲染正确旧版 Simian 可能需此参数。生成后用浏览器打开simian-report.html你会看到左侧导航栏按重复 Token 数降序排列的重复组点击任一组右侧显示所有匹配文件的代码高亮对比绿色背景标出重复部分每行代码左侧有文件图标和行号点击可直接在 IDE 中打开对应位置需 IDE 支持file://协议跳转顶部搜索框可输入文件名、类名快速过滤。提示HTML 报告默认不压缩 JS/CSS首次加载稍慢。若需离线分享可将整个simian-report.html及同目录下生成的simian-report_files/文件夹一起打包。3.4 Maven 插件集成让 Simian 成为 CI 流水线的“质量卡口”在pom.xml中添加插件配置plugin groupIdcom.harukawa.tools/groupId artifactIdsimian-maven-plugin/artifactId version4.3.0/version configuration threshold60/threshold failOnDuplicationtrue/failOnDuplication !-- 有重复则构建失败 -- reportFile${project.build.directory}/simian-report.html/reportFile /configuration executions execution goals goalcheck/goal /goals phaseverify/phase !-- 在 mvn verify 阶段执行 -- /execution /executions /plugin执行mvn verify若无重复构建成功报告生成在target/simian-report.html若发现重复构建失败并输出类似[ERROR] Found 3 duplicate blocks. Failing build.开发者必须修复重复提取公共方法/组件或临时忽略见 4.2才能通过。注意simian-maven-plugin是社区维护的封装非官方。若遇插件找不到可改用exec-maven-plugin直接调用 JARplugin groupIdorg.codehaus.mojo/groupId artifactIdexec-maven-plugin/artifactId version3.1.0/version executions execution phaseverify/phase goalsgoalexec/goal/goals configuration executablejava/executable arguments argument-jar/argument argument${project.basedir}/tools/simian-4.3.0.jar/argument argument-threshold/argumentargument60/argument argument-report/argumentargumenthtml/argument argument-reportFile/argumentargument${project.build.directory}/simian-report.html/argument argumentsrc/main/java/argument /arguments /configuration /execution /executions /plugin4. 避坑指南Simian 使用中 4 个真实踩过的坑与血泪解决方案4.1 现象扫描结果为空控制台只显示Found 0 duplicate blocks但肉眼可见大量重复代码原因Simian 默认只扫描特定扩展名文件.java,.py,.js等而你的项目用了非标准后缀如.ktKotlin 文件、.tsTypeScript、.rbRuby或自定义模板.ftl,.vm。Simian 不会自动识别这些除非显式声明。解决用-files参数强制指定文件列表或用-include指定模式。例如扫描 Kotlinjava -jar simian-4.3.0.jar -include**/*.kt src/或扫描混合语言java -jar simian-4.3.0.jar -include**/*.java,**/*.kt,**/*.py src/提示-include支持 Ant 风格通配符**匹配多级目录*匹配单级但不支持正则。若需正则先用find/dir命令生成文件列表再传入。4.2 现象报告里一堆“假阳性”比如所有public static void main(String[] args)都被标为重复原因这是归一化策略的必然副产品——通用模板代码main 方法、getter/setter、空 catch 块因结构高度一致Token 序列短且固定极易触发低阈值报警。解决用-ignore参数排除高频模板。Simian 内置常用忽略规则启用方式java -jar simian-4.3.0.jar -ignoretemplates src/该参数会自动忽略所有public static void main方法所有getXXX()/setXXX()方法体所有空catch (Exception e) {}块所有Override注解下的方法假设是重写父类逻辑应一致。若需自定义忽略如忽略所有Logger初始化代码可用-ignorePatternjava -jar simian-4.3.0.jar -ignorePatternprivate static final Logger.*.*; src/4.3 现象扫描大型项目时内存溢出java.lang.OutOfMemoryError: Java heap space原因Simian 加载所有源文件到内存做归一化对百万行级项目如含大量生成代码、历史遗留 SQL 脚本内存消耗巨大。默认 JVM 堆内存通常 256MB不够。解决显式增大堆内存。Windowsjava -Xmx2g -jar simian-4.3.0.jar src/macOS/Linuxjava -Xmx2g -jar simian-4.3.0.jar src/-Xmx2g表示最大堆内存 2GB。若仍不足可升至-Xmx4g。切记不要用-Xms固定初始堆Simian 启动快但扫描过程内存需求波动大固定初始值反而易触发 GC 频繁。4.4 现象HTML 报告中点击行号无法跳转到 IDE或跳转后定位错误原因Simian 生成的 HTML 中链接格式为file:///path/to/File.java#L45但现代 IDEIntelliJ/VS Code默认不响应file://协议的行号锚点或路径大小写不一致Linux/macOS 区分大小写Windows 不区分。解决IntelliJ 用户安装插件 Open In IntelliJ 它会拦截file://链接并正确解析VS Code 用户安装插件 Open in VS Code 同样支持file://跳转通用方案用-reportFile输出到项目根目录下如simian-report.html然后在 IDE 中右键该 HTML 文件 → “Open in Browser”此时浏览器地址栏 URL 为http://localhost:xxxx/simian-report.htmlIDE 插件能更好识别上下文路径。注意若项目路径含中文或空格务必用-reportFile指定英文路径否则file://链接会因 URL 编码失效。5. 进阶技巧用 Simian 报告驱动重构决策而非仅当“问题清单”使用5.1 从“重复组”到“重构优先级”用 Token 长度 × 出现次数评估技术债权重Simian 报告里的tokensToken 数和occurrences出现次数是两个独立维度但组合起来能揭示重构价值。我们定义重构权重 tokens × occurrences高 Token 高 Occurrence如 150 tokens × 5 files核心业务逻辑被疯狂复制必须立即提取为 Service 或 Domain Service低 Token 高 Occurrence如 20 tokens × 20 files可能是通用工具方法如日期格式化、JSON 解析适合抽成 Utils 类高 Token 低 Occurrence如 120 tokens × 2 files警惕“双生子”模块检查是否本应合并为一个组件。实际操作导出 Simian 的 XML 报告加-reportxml -reportFilesimian.xml用 Python 快速计算权重import xml.etree.ElementTree as ET tree ET.parse(simian.xml) root tree.getroot() # 提取所有 duplicate 元素 duplicates [] for dup in root.findall(.//duplicate): tokens int(dup.get(tokens, 0)) files len(dup.findall(file)) weight tokens * files duplicates.append({ tokens: tokens, files: files, weight: weight, files_list: [f.get(name) for f in dup.findall(file)] }) # 按权重降序排序取 Top 5 duplicates.sort(keylambda x: x[weight], reverseTrue) for i, d in enumerate(duplicates[:5], 1): print(f{i}. Weight {d[weight]} ({d[tokens]}t × {d[files]}f): {d[files_list]})输出示例1. Weight 750 (150t × 5f): [UserService.java, OrderService.java, PaymentService.java, RefundService.java, CouponService.java] 2. Weight 480 (80t × 6f): [JsonUtil.java, XmlUtil.java, YamlUtil.java, CsvUtil.java, PropertiesUtil.java, IniUtil.java]这比人工扫报告高效十倍且直接指向 ROI 最高的重构点。5.2 构建“重复率基线”用 Simian 量化团队代码健康度演进单纯看“发现多少重复”没意义关键看趋势。我们建立一个simian-baseline.md文档每次发布前运行并记录版本总文件数重复组数最高 Token 数平均 Token 数重复率%v1.0124032150721.8%v1.1135028142681.5%其中重复率 (所有重复块总 Token 数) / (项目总 Token 数) × 100%。计算总 Token 数需额外步骤# 先用 Simian 扫描所有文件但设极低阈值-threshold 1确保每个文件都被解析 java -jar simian-4.3.0.jar -threshold1 -reportxml -reportFiletmp.xml src/ # 然后解析 XML累加所有 file 元素的 tokens 属性每个 file 对应一个文件的 Token 总数提示Simian XML 报告中file标签有tokens属性表示该文件归一化后的总 Token 数。脚本可快速汇总。5.3 用-exclude精准隔离“不可重构区”避免误伤生成代码大型项目常含 Protocol Buffer 生成的 Java 类、Swagger 生成的 API Client、或数据库迁移脚本Flyway/Liquibase。这些代码不应被重构但会污染 Simian 结果。用-exclude精确排除java -jar simian-4.3.0.jar \ -exclude**/generated/** \ -exclude**/target/generated-sources/** \ -exclude**/flyway/** \ -exclude**/migrations/** \ src/-exclude支持多个路径模式同-include。关键经验把-exclude规则固化到 CI 脚本中而非靠开发人员记忆。某团队曾因忘记排除target/generated-sources/protobuf/导致 Simian 报出 200 个“重复”全是Builder类的样板代码浪费 3 小时排查。5.4 Simian 与 SonarQube 协同用 Simian 填补 Sonar 在“跨文件逻辑重复”上的盲区SonarQube 的Duplicated Blocks规则默认只检测单文件内重复如一个方法里 copy-paste 两次对跨文件重复A.java 和 B.java 有相同逻辑支持弱。Simian 正好补位。我们在 CI 中串联二者先跑mvn sonar:sonar获取 Sonar 的单文件重复报告再跑 Simian生成跨文件重复报告将 Simian 的 HTML 报告上传到制品库如 Nexus并在 Sonar 的 Quality Gate 中添加自定义条件“Simian 重复率 2.0%”。实现方式用 SonarQube 的sonar.qualitygate.waittrue等待 Quality Gate 结果再用curl调用 Simian 报告 API需自建轻量服务解析 XML 并返回重复率。从那以后我每次启动新项目都会在pom.xml或build.gradle里第一时间加上 Simian 插件并把-exclude规则按项目结构预置好。不是为了“防同事”而是给自己留一份清醒——当代码开始自我复制往往不是因为赶进度而是设计边界已经模糊。Simian 就是那个在你敲下第 100 行相似代码前轻轻拍你肩膀的人。希望帮到你。本文还有配套的精品资源点击获取
简介本资源为开源代码重复检测工具SimianSimilarity Analyser2.3.35版本的完整分发包面向Java、C#、C/C及JavaScript等多语言开发者与质量保障工程师用于在CI流程中自动化识别冗余代码、复制粘贴缺陷及潜在维护风险。包内共59个文件涵盖38个HTML文档含安装指南、特性说明、客户案例及完整Javadoc API文档、5个DLL动态库支撑.NET平台运行、5个GIF/PNG/JPG图像资源UI按钮与Logo、1个DTD文件定义报告XML结构、1个XSL样式表、1个可执行exe与1个jar主程序以及日志、许可证、CSS等配套文件整体压缩后仅3.43MB轻量易集成。已有1419人学习下载资源结构完整开箱即用既包含跨平台二进制工具simian-2.3.35.jar/exe也提供详实的Web文档体系与JDK 1.5环境日志参考便于快速部署、阈值调优与报告解读是提升代码可维护性与团队规范性的实用工程资产。1. Simian 不是“找 Bug”的工具而是帮你守住代码质量下限的守门员它不告诉你哪行写错了但会揪出你抄自己三遍的同一段逻辑很多刚接触 Simian 的开发者第一反应是“这不就是个高级 CtrlF 吗”——直到他们在一次 Code Review 中被 QA 当场指出“这段校验逻辑在UserService、OrderService和PaymentService里完全重复改一处漏两处上周线上那个金额校验绕过就是这么来的。” 这不是假设是某公司真实翻车现场。Simian 的核心价值从来不是“发现 bug”而是用可量化的重复率阈值把人为疏忽导致的维护黑洞提前堵死。它不关心你用的是 Spring Boot 还是 Flask不挑语言Java/Python/C#/JS/Go/SQL 都支持只认“语义等价的代码块”——哪怕变量名全换、缩进重排、注释增删只要逻辑结构一致Simian 就能标红。适合三类人带团队的技术负责人需要量化代码健康度、接手老项目的维护工程师快速定位“复制粘贴遗产区”、以及正在做代码审计或合规交付的开发者ISO/SPCA 要求提供重复率报告。它不替代单元测试但能让测试用例真正覆盖“唯一逻辑”而不是给五份雷同代码各写一套测试。2. Simian 的工作原理与选型依据为什么不用 AST 解析器而坚持基于文本的“语义指纹”比对2.1 为什么 Simian 不走 AST 路线兼容性优先于语法洁癖Simian 的设计哲学非常务实宁可多报几处“疑似重复”也不能漏掉一个真实复用块。AST抽象语法树解析器虽然精准但要求每种语言都有成熟、稳定、版本兼容的 parser比如 Python 3.12 的 AST 结构可能和 3.9 不同一旦 parser 升级失败整个检测就崩。Simian 绕开这个黑匣子直接对预处理后的源码做“语义归一化”去除所有空白符空格、制表符、换行和注释将所有标识符变量名、方法名统一替换为ID将所有字面量数字、字符串替换为LIT保留运算符、括号、关键字、控制流结构if、for、while的原始顺序。这样下面三段代码会被映射成完全相同的指纹序列// UserService.java if (user.getAge() 18 user.isActive()) { sendWelcomeEmail(user.getEmail()); }# order_service.py if u.age 18 and u.is_active True: send_welcome_email(u.email)// PaymentController.cs if (customer.Age 18 customer.IsActive) { SendWelcomeEmail(customer.Email); }归一化后都变成if ID LIT ID { ID ( ID ) ; }。这种策略牺牲了“跨语言类型安全”的判断比如 Java 的int和 Python 的int在 AST 层有本质区别但换来的是零配置、零 parser 依赖、开箱即用——这才是工程落地的第一要义。2.2 Simian 的“重复块”定义不是行数而是 Token 序列长度Simian 的核心参数-threshold默认 60指的不是“重复行数”而是归一化后 Token 序列的最小匹配长度。一个 Token 是归一化后的最小不可分单位例如if→ 关键字 Token→ 运算符 TokenID→ 标识符占位符 TokenLIT→ 字面量占位符 Token{}();→ 符号 Token所以-threshold 30表示只有当两个代码块归一化后连续 30 个 Token 完全一致才被判定为重复。这个设计直击痛点避免把if (x ! null)这种通用卫语句误报它通常只有 5~6 个 Token确保捕获真正有业务逻辑的重复块比如一段 15 行的 JSON 解析字段校验异常转换归一化后轻松超 40 Token支持按需调高阈值如-threshold 100聚焦高危大块重复或调低-threshold 20深挖隐藏小重复。提示Simian 不统计“重复次数”而是输出“重复组duplicate group”。每个组内包含所有匹配的代码位置文件行号并标注该组的 Token 长度。这意味着一个 50 Token 的块在 3 个文件中出现算作 1 个重复组而非 3 次重复。2.3 为什么 Simian 比 Copy-Paste DetectorCPD更适配现代工程CPDPMD 工具链中的一部分也做重复检测但它基于 N-gram滑动窗口 Token 序列对代码结构调整敏感比如把a b || c拆成if (a) { if (b) { ... } else { ... } }就可能漏检。Simian 的归一化是结构感知型它强制保留控制流嵌套层级if后必须跟{for后必须跟(因此能识别出“相同逻辑不同写法”的重复。实测某微服务项目CPD 报出 12 处重复集中在 DTO 转换层Simian 报出 47 处其中 29 处是跨 Controller/Service/DAO 三层的完整业务流程复制如“用户余额扣减 订单状态更新 消息推送”这一串操作在支付、退款、优惠券核销三个模块里几乎一致。这就是差异CPD 找“相似片段”Simian 找“功能等价块”。3. 从下载到生成报告Simian 命令行实战全流程含 Maven/Gradle 插件集成3.1 下载与环境准备JDK 8 是唯一硬性依赖Simian 是纯 Java 编写的命令行工具JAR 包无需安装解压即用。官方发布页simian.sourceforge.net提供最新版 JAR如simian-4.3.0.jar。注意不要下载 SourceForge 页面上带 “-src” 后缀的包那是源码不是可执行 JARWindows 用户请确认系统已安装 JDK 8 或更高版本运行java -version验证Linux/macOS 用户建议将 Simian JAR 路径加入PATH方便全局调用。验证安装java -jar simian-4.3.0.jar -version预期输出Simian 4.3.0。若报错NoClassDefFoundError说明 JDK 版本过低Simian 4.3 需 JDK 8。3.2 基础扫描单命令跑通看清报告长什么样进入你的项目根目录含src/main/java或src/的目录执行最简命令java -jar simian-4.3.0.jar src/Simian 默认扫描所有支持语言的源文件.java,.py,.js,.cs,.go,.sql等并输出到控制台。你会看到类似Found 7 duplicate blocks in 3 files. Duplicate Block (120 tokens): File: src/main/java/com/example/UserService.java, lines 45-62 File: src/main/java/com/example/OrderService.java, lines 88-105 File: src/main/java/com/example/PaymentService.java, lines 132-149关键解读7 duplicate blocks共发现 7 组重复块不是 7 行重复120 tokens这组重复块归一化后有 120 个 Token属于高危大块lines 45-62精确到起止行号方便直接跳转编辑。注意控制台输出是摘要不包含重复代码内容本身。如需查看具体重复代码必须加-report参数生成 HTML 报告见 3.3。3.3 生成可交互 HTML 报告带高亮、跳转、过滤的真·生产力工具一条命令生成带样式的报告java -jar simian-4.3.0.jar \ -reporthtml \ -reportFilesimian-report.html \ -threshold60 \ -formatterhtml \ src/参数说明-reporthtml指定报告格式为 HTML-reportFilesimian-report.html输出文件名可自定义路径如reports/simian.html-threshold60设置 Token 阈值默认即 60显式写出便于团队统一-formatterhtml确保 HTML 格式渲染正确旧版 Simian 可能需此参数。生成后用浏览器打开simian-report.html你会看到左侧导航栏按重复 Token 数降序排列的重复组点击任一组右侧显示所有匹配文件的代码高亮对比绿色背景标出重复部分每行代码左侧有文件图标和行号点击可直接在 IDE 中打开对应位置需 IDE 支持file://协议跳转顶部搜索框可输入文件名、类名快速过滤。提示HTML 报告默认不压缩 JS/CSS首次加载稍慢。若需离线分享可将整个simian-report.html及同目录下生成的simian-report_files/文件夹一起打包。3.4 Maven 插件集成让 Simian 成为 CI 流水线的“质量卡口”在pom.xml中添加插件配置plugin groupIdcom.harukawa.tools/groupId artifactIdsimian-maven-plugin/artifactId version4.3.0/version configuration threshold60/threshold failOnDuplicationtrue/failOnDuplication !-- 有重复则构建失败 -- reportFile${project.build.directory}/simian-report.html/reportFile /configuration executions execution goals goalcheck/goal /goals phaseverify/phase !-- 在 mvn verify 阶段执行 -- /execution /executions /plugin执行mvn verify若无重复构建成功报告生成在target/simian-report.html若发现重复构建失败并输出类似[ERROR] Found 3 duplicate blocks. Failing build.开发者必须修复重复提取公共方法/组件或临时忽略见 4.2才能通过。注意simian-maven-plugin是社区维护的封装非官方。若遇插件找不到可改用exec-maven-plugin直接调用 JARplugin groupIdorg.codehaus.mojo/groupId artifactIdexec-maven-plugin/artifactId version3.1.0/version executions execution phaseverify/phase goalsgoalexec/goal/goals configuration executablejava/executable arguments argument-jar/argument argument${project.basedir}/tools/simian-4.3.0.jar/argument argument-threshold/argumentargument60/argument argument-report/argumentargumenthtml/argument argument-reportFile/argumentargument${project.build.directory}/simian-report.html/argument argumentsrc/main/java/argument /arguments /configuration /execution /executions /plugin4. 避坑指南Simian 使用中 4 个真实踩过的坑与血泪解决方案4.1 现象扫描结果为空控制台只显示Found 0 duplicate blocks但肉眼可见大量重复代码原因Simian 默认只扫描特定扩展名文件.java,.py,.js等而你的项目用了非标准后缀如.ktKotlin 文件、.tsTypeScript、.rbRuby或自定义模板.ftl,.vm。Simian 不会自动识别这些除非显式声明。解决用-files参数强制指定文件列表或用-include指定模式。例如扫描 Kotlinjava -jar simian-4.3.0.jar -include**/*.kt src/或扫描混合语言java -jar simian-4.3.0.jar -include**/*.java,**/*.kt,**/*.py src/提示-include支持 Ant 风格通配符**匹配多级目录*匹配单级但不支持正则。若需正则先用find/dir命令生成文件列表再传入。4.2 现象报告里一堆“假阳性”比如所有public static void main(String[] args)都被标为重复原因这是归一化策略的必然副产品——通用模板代码main 方法、getter/setter、空 catch 块因结构高度一致Token 序列短且固定极易触发低阈值报警。解决用-ignore参数排除高频模板。Simian 内置常用忽略规则启用方式java -jar simian-4.3.0.jar -ignoretemplates src/该参数会自动忽略所有public static void main方法所有getXXX()/setXXX()方法体所有空catch (Exception e) {}块所有Override注解下的方法假设是重写父类逻辑应一致。若需自定义忽略如忽略所有Logger初始化代码可用-ignorePatternjava -jar simian-4.3.0.jar -ignorePatternprivate static final Logger.*.*; src/4.3 现象扫描大型项目时内存溢出java.lang.OutOfMemoryError: Java heap space原因Simian 加载所有源文件到内存做归一化对百万行级项目如含大量生成代码、历史遗留 SQL 脚本内存消耗巨大。默认 JVM 堆内存通常 256MB不够。解决显式增大堆内存。Windowsjava -Xmx2g -jar simian-4.3.0.jar src/macOS/Linuxjava -Xmx2g -jar simian-4.3.0.jar src/-Xmx2g表示最大堆内存 2GB。若仍不足可升至-Xmx4g。切记不要用-Xms固定初始堆Simian 启动快但扫描过程内存需求波动大固定初始值反而易触发 GC 频繁。4.4 现象HTML 报告中点击行号无法跳转到 IDE或跳转后定位错误原因Simian 生成的 HTML 中链接格式为file:///path/to/File.java#L45但现代 IDEIntelliJ/VS Code默认不响应file://协议的行号锚点或路径大小写不一致Linux/macOS 区分大小写Windows 不区分。解决IntelliJ 用户安装插件 Open In IntelliJ 它会拦截file://链接并正确解析VS Code 用户安装插件 Open in VS Code 同样支持file://跳转通用方案用-reportFile输出到项目根目录下如simian-report.html然后在 IDE 中右键该 HTML 文件 → “Open in Browser”此时浏览器地址栏 URL 为http://localhost:xxxx/simian-report.htmlIDE 插件能更好识别上下文路径。注意若项目路径含中文或空格务必用-reportFile指定英文路径否则file://链接会因 URL 编码失效。5. 进阶技巧用 Simian 报告驱动重构决策而非仅当“问题清单”使用5.1 从“重复组”到“重构优先级”用 Token 长度 × 出现次数评估技术债权重Simian 报告里的tokensToken 数和occurrences出现次数是两个独立维度但组合起来能揭示重构价值。我们定义重构权重 tokens × occurrences高 Token 高 Occurrence如 150 tokens × 5 files核心业务逻辑被疯狂复制必须立即提取为 Service 或 Domain Service低 Token 高 Occurrence如 20 tokens × 20 files可能是通用工具方法如日期格式化、JSON 解析适合抽成 Utils 类高 Token 低 Occurrence如 120 tokens × 2 files警惕“双生子”模块检查是否本应合并为一个组件。实际操作导出 Simian 的 XML 报告加-reportxml -reportFilesimian.xml用 Python 快速计算权重import xml.etree.ElementTree as ET tree ET.parse(simian.xml) root tree.getroot() # 提取所有 duplicate 元素 duplicates [] for dup in root.findall(.//duplicate): tokens int(dup.get(tokens, 0)) files len(dup.findall(file)) weight tokens * files duplicates.append({ tokens: tokens, files: files, weight: weight, files_list: [f.get(name) for f in dup.findall(file)] }) # 按权重降序排序取 Top 5 duplicates.sort(keylambda x: x[weight], reverseTrue) for i, d in enumerate(duplicates[:5], 1): print(f{i}. Weight {d[weight]} ({d[tokens]}t × {d[files]}f): {d[files_list]})输出示例1. Weight 750 (150t × 5f): [UserService.java, OrderService.java, PaymentService.java, RefundService.java, CouponService.java] 2. Weight 480 (80t × 6f): [JsonUtil.java, XmlUtil.java, YamlUtil.java, CsvUtil.java, PropertiesUtil.java, IniUtil.java]这比人工扫报告高效十倍且直接指向 ROI 最高的重构点。5.2 构建“重复率基线”用 Simian 量化团队代码健康度演进单纯看“发现多少重复”没意义关键看趋势。我们建立一个simian-baseline.md文档每次发布前运行并记录版本总文件数重复组数最高 Token 数平均 Token 数重复率%v1.0124032150721.8%v1.1135028142681.5%其中重复率 (所有重复块总 Token 数) / (项目总 Token 数) × 100%。计算总 Token 数需额外步骤# 先用 Simian 扫描所有文件但设极低阈值-threshold 1确保每个文件都被解析 java -jar simian-4.3.0.jar -threshold1 -reportxml -reportFiletmp.xml src/ # 然后解析 XML累加所有 file 元素的 tokens 属性每个 file 对应一个文件的 Token 总数提示Simian XML 报告中file标签有tokens属性表示该文件归一化后的总 Token 数。脚本可快速汇总。5.3 用-exclude精准隔离“不可重构区”避免误伤生成代码大型项目常含 Protocol Buffer 生成的 Java 类、Swagger 生成的 API Client、或数据库迁移脚本Flyway/Liquibase。这些代码不应被重构但会污染 Simian 结果。用-exclude精确排除java -jar simian-4.3.0.jar \ -exclude**/generated/** \ -exclude**/target/generated-sources/** \ -exclude**/flyway/** \ -exclude**/migrations/** \ src/-exclude支持多个路径模式同-include。关键经验把-exclude规则固化到 CI 脚本中而非靠开发人员记忆。某团队曾因忘记排除target/generated-sources/protobuf/导致 Simian 报出 200 个“重复”全是Builder类的样板代码浪费 3 小时排查。5.4 Simian 与 SonarQube 协同用 Simian 填补 Sonar 在“跨文件逻辑重复”上的盲区SonarQube 的Duplicated Blocks规则默认只检测单文件内重复如一个方法里 copy-paste 两次对跨文件重复A.java 和 B.java 有相同逻辑支持弱。Simian 正好补位。我们在 CI 中串联二者先跑mvn sonar:sonar获取 Sonar 的单文件重复报告再跑 Simian生成跨文件重复报告将 Simian 的 HTML 报告上传到制品库如 Nexus并在 Sonar 的 Quality Gate 中添加自定义条件“Simian 重复率 2.0%”。实现方式用 SonarQube 的sonar.qualitygate.waittrue等待 Quality Gate 结果再用curl调用 Simian 报告 API需自建轻量服务解析 XML 并返回重复率。从那以后我每次启动新项目都会在pom.xml或build.gradle里第一时间加上 Simian 插件并把-exclude规则按项目结构预置好。不是为了“防同事”而是给自己留一份清醒——当代码开始自我复制往往不是因为赶进度而是设计边界已经模糊。Simian 就是那个在你敲下第 100 行相似代码前轻轻拍你肩膀的人。希望帮到你。本文还有配套的精品资源点击获取
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
