PMD 对 Rust 语言的支持:CPD 重复代码检测指南
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 做了两处本地化修改:
- 将上游
RustLexerBase(Java 辅助基类)中的自定义函数内联进 lexer grammar,移除对RustLexerBase的依赖; - 额外支持反引号(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 比较框架; - 模块、发行清单、集成测试与文档导航均已就绪,任何官方发行版均可直接使用。