PMD 对 Rust 语言的支持:CPD 重复代码检测指南

原创2026-10-12 18:42:491,988 阅读
文章标签:静态分析代码质量

PMD 对 Rust 语言的支持:CPD 重复代码检测指南

PMD 是开源的多语言静态代码分析器,其子工具 CPD(Copy/Paste Detector,复制粘贴检测器) 负责跨多种语言查找重复代码块。本文聚焦 PMD 自 7.9.0 起新增的 Rust 语言支持,说明如何在命令行中用 CPD 分析 Rust 工程、识别可复用的重复代码,并介绍底层基于 ANTLR 的词法实现与测试验证方式,帮助你直接上手并理解其工作原理。

Rust 以“极速且内存高效”著称:没有运行时和垃圾回收器,足以支撑性能敏感的服务、运行在嵌入式设备上,并能与其他语言轻松集成。它也因此进入了 CPD 支持的语言清单。

支持概况:CPD-only,从 7.9.0 开始

语言支持页面(docs/pages/pmd/languages/rust.md)通过 Jekyll 的语言信息组件(language_info.html)声明了 Rust 的核心元数据,可整理为下表:

项目 值
语言名称 Rust
语言 Id rust
实现类 rust::lang.rust.RustLanguageModule(即 net.sourceforge.pmd.lang.rust.RustLanguageModule)
自 PMD 版本 7.9.0
PMD 规则支持 ❌ 不支持(无规则引擎支持)
CPD 支持 ✔️ 支持

关键结论是:Rust 在 PMD 中属于“仅 CPD”语言(CPD-only language),即目前 PMD 只为 Rust 提供重复代码检测能力,尚不能编写基于 AST 的 PMD 规则对其做静态规则检查。

语言模块的源码事实

RustLanguageModule.java 继承了 CpdOnlyLanguageModuleBase(仅 CPD 语言模块基类),并明确了:

private static final String ID = "rust";

public RustLanguageModule() {
    super(LanguageMetadata.withId(ID).name("Rust").extensions("rs"));
}
  • 文件扩展名仅一个:.rs;
  • createCpdLexer(...) 返回 RustCpdLexer,供 CPD 在运行时取词。

入门:用 CPD 检测 Rust 重复代码

Rust 支持随 PMD 7.9.0 正式发布,发布说明(release_notes_old_pmd7.md)明确写着:"CPD now supports Rust... It is shipped in the new module pmd-rust." 该模块已被加入根 POM 的 <module> 列表(pom.xml),并作为依赖被引入 pmd-languages-deps/pom.xml,因此任何官方二进制发行版(pmd-dist)都会自动包含 Rust 支持。

命令行用法

使用 PMD 的 CPD 分析 Rust 源码,只需用 --language rust(或 -l rust)指定语言,并给定源码目录:

pmd cpd --minimum-tokens 100 --dir src --language rust

Windows 下使用 pmd.bat:

pmd.bat cpd --minimum-tokens 100 --dir src --language rust

命令各参数说明:

参数 含义 默认值
--minimum-tokens 报告为重复所需的最小 token 数 必填
--dir 待扫描的源码目录(可重复指定多个) 必填
--language / -l 源代码语言,传 rust java
--format / -f 报告格式,如 text、xml、csv、markdown 等 text
--report-file / -r 报告输出文件路径 标准输出
--[no-]fail-on-violation 发现重复时是否以非零状态退出(默认状态码 4) 启用

退出码约定

CPD 与脚本、CI 集成的关键之一是退出码语义(见 cpd.md):

  • 0:一切正常,未发现重复代码,也无可恢复错误;
  • 1:CPD 因异常退出;
  • 2:用法错误(命令行参数非法或缺失);
  • 4:检测到至少一处重复代码(自 PMD 5.0 起),除非设置 --no-fail-on-violation;
  • 5:发生至少一个可恢复错误(自 PMD 7.3.0 起),可用 --no-fail-on-error 忽略。

[!NOTE] 若 PMD 以 5 退出,说明有一个或多个文件在词法分析阶段出错,这些文件的整体重复检测结果将缺失(相当于误报缺失),应当排查根因,若是 PMD 自身问题请提交 bug 报告。

底层实现:ANTLR 词法分析

Rust 的 CPD 支持不依赖自定义解析器,而是复用了 ANTLR 生态中现成的 Rust 词法文法。

Lexer 类结构

RustCpdLexer.java 是整个 Rust 支持的取词入口:

public class RustCpdLexer extends AntlrCpdLexer {

    @Override
    protected Lexer getLexerForSource(CharStream charStream) {
        return new RustLexer(charStream);
    }
}

它继承自 PMD 核心的通用 ANTLR 适配基类 AntlrCpdLexer(pmd-core/src/main/java/net/sourceforge/pmd/cpd/impl/AntlrCpdLexer.java)。该基类负责把源文件读入 CharStream,再用 AntlrTokenManager 将词法 token 转成 CPD 统一的 AntlrToken 流,之后 CPD 的 Karp-Rabin 字符串匹配算法便在这些 token 上查找重复序列。因此,任何 ANTLR 文法只要实现 getLexerForSource,就能快速接入 CPD。

文法来源与本地化改造

词法文法位于 RustLexer.g4。按目录内 README.md 的说明,该文法取自 antlr/grammars-v4 的 Rust 文法(MIT 许可),PMD 做了两处本地化修改:

  1. 将上游 RustLexerBase(Java 辅助基类)中的自定义函数内联进 lexer grammar,移除对 RustLexerBase 的依赖;
  2. 额外支持反引号(backtick "`") token,以更好覆盖 Rust 生态中(如宏/IDL 场景)出现的反引号写法。

文法覆盖的 Rust 语言要素

从 RustLexer.g4 可以确认其完整覆盖了 Rust 官方参考手册定义的关键词与词法规则:

  • 严格关键字:as、break、const、continue、crate、else、enum、extern、false、fn、for、if、impl、in、let、loop、match、mod、move、mut、pub、ref、return、self、Self、static、struct、super、trait、true、type、unsafe、use、where、while,以及 2018+ 的 async、await、dyn;
  • 保留关键字:abstract、become、box、do、final、macro、override、priv、typeof、unsized、virtual、yield、try;
  • 弱关键字/特殊 token:union、'static、'_、macro_rules、$crate、r# raw identifier;
  • 字面量与数字:字符、字符串、raw 字符串、字节(b'...'、b"..."、br"..."),十进制/二进制/八进制/十六进制整数(支持 u8~u128、i8~i128、usize、isize 后缀),以及浮点数(f32/f64 后缀与指数形式);
  • 注释:// 行注释、/* */ 块注释、//! 与 /*! 内部文档注释、/// 与 /** 外部文档注释,均归入 HIDDEN 通道,不参与重复比较;
  • Shebang:支持文件开头的 #! 行(通过 SOF() 判定文件起始);
  • 标识符:基于 Unicode XID 规则,兼容 \p{L} 等 Unicode 类别与 Other_ID_Start/Other_ID_Continue 特殊字符集合;
  • 运算符与分隔符:+、-、*、/、%、^、!、&、|、&&、||、+=、-=、*=、/=、%=、^=、&=、|=、<<=、>>=、=、==、!=、>、<、>=、<=、@、_、.、..、...、..=、,、;、:、::、->、=>、#、$、?、`,以及各类括号。

浮点数歧义消解的自定义谓词

Rust 文法中最棘手的部分是“.”的歧义(例如 1.f32 是方法调用还是浮点字面量)。上游文法的两个自定义函数被内联进 RustLexer.g4 的 @lexer::members 块中,用于在词法层消解歧义:

  • floatDotPossible():决定小数点后是否还能跟数字/字母——例如 1.f32 中 f32 是浮点后缀,而 1.foo() 中的 f 是方法名;
  • floatLiteralPossible():结合上一个 token 的类型(如是否紧跟在 DOT、字符串/字符字面量、GT、右括号或普通标识符之后)判断当前是否构成浮点字面量。

这些谓词保证了 1.0、1.f64、2e5、0x1F 等各类 Rust 数字写法能被正确切分,避免 CPD 产生错误的 token 序列。

测试验证:文本对照测试

pmd-rust 模块自带针对 CPD 词法器的单元测试 RustCpdLexerTest.java:

class RustCpdLexerTest extends CpdTextComparisonTest {

    RustCpdLexerTest() {
        super("rust", ".rs");
    }

    @Test
    void testHelloWorld() {
        doTest("helloworld");
    }
}
  • 测试基类 CpdTextComparisonTest 来自 pmd-lang-test 测试模块,用于把词法器输出与基线文本做精确对比;
  • 测试数据文件为 helloworld.rs,内容是经典的 Rust Hello World:
// This is the main function.
fn main() {
    // Print text to the console.
    println!("Hello World!");
}
  • pmd-rust 的 pom.xml 通过 antlr4-maven-plugin 在 generate-sources 阶段用 antlr4-wrapper.xml 的 cpd-language 目标生成 lexer 源码,并依赖 pmd-core、antlr4-runtime(编译期)以及 junit-jupiter、pmd-test、pmd-lang-test(测试期)。

发行与清单确认

  • 模块注册:根 pom.xml 已将 pmd-rust 加入 <modules>,随多模块构建一并编译;
  • 发行包含:pmd-languages-deps/pom.xml 把 pmd-rust 列入依赖,使 pmd-dist 二进制发行包自动带上 Rust 支持;
  • 集成测试:BinaryDistributionIT.java 的 SUPPORTED_LANGUAGES_CPD 常量中包含 "rust",集成测试会校验发行包实际可用的 CPD 语言清单,确认 Rust 开箱即用;
  • 文档导航:pmd_sidebar.yml 中已加入 "Rust" 条目,指向 pmd_languages_rust.html 页面。

常见问题

Q:PMD 能对 Rust 运行静态规则检查(如检测坏味道)吗? A:目前不能。Rust 在 PMD 中注册为 CPD-only 语言,仅 CpdCapableLanguage 能力被激活,PMD 规则引擎暂不覆盖 Rust。如果你需要为 Rust 补充 CPD 之外的能力,可参考 adding_new_cpd_language.md 中扩展 CPD 语言的完整指南。

Q:CPD 对 Rust 支持哪些“忽略”选项(如 --ignore-identifiers)? A:CPD 的忽略类选项(--ignore-literals、--ignore-identifiers、--ignore-annotations、--ignore-sequences、--ignore-usings 等)目前主要面向 Java、C++、C# 等语言(详见 cpd.md),Rust 词法器未声明额外的可配置属性,使用默认的精确匹配模式即可。

Q:Rust 文件无法被词法分析导致 CPD 以状态码 5 退出怎么办? A:按 CPD 文档建议,先检查是否为 PMD 文法未覆盖的合法 Rust 语法(可对照 RustLexer.g4 的规则范围),再确认文件编码与 shebang 写法;若确属 PMD 缺陷,应提交 bug 报告。

小结

  • PMD 7.9.0 起为 Rust 提供 CPD 重复代码检测,语言 Id 为 rust,扩展名 .rs,属“仅 CPD”语言;
  • 命令行一行即可接入 CI:pmd cpd --minimum-tokens 100 --dir src --language rust;
  • 底层复用 antlr/grammars-v4 的 Rust 文法并内联了浮点数歧义消解谓词,通过 AntlrCpdLexer 桥接进入 CPD 的 token 比较框架;
  • 模块、发行清单、集成测试与文档导航均已就绪,任何官方发行版均可直接使用。
登录后查看全文
pmd