Psalm 的 psalm-refactor 重构工具详解:批量移动与重命名类、方法、命名空间

原创2026-10-09 13:10:511,644 阅读
文章标签:开发工具代码质量质量保障

Psalm 的 psalm-refactor 重构工具详解:批量移动与重命名类、方法、命名空间

Psalm 除了静态分析定位问题,还内置了一个专门用于结构性变更的重构工具 psalm-refactor,支持在移动或重命名类、方法的同时自动更新代码库中所有可识别的引用。本文基于仓库中的官方文档 refactoring.md 展开,逐条讲清五种重构场景的命令用法,并结合 Refactor.php 与 ProjectAnalyzer.php 的源码,说明其参数解析、通配符展开、引用改写与文件迁移的完整机制。

工具的两种调用入口

Psalm 的重构功能可以独立使用,也可以挂载在 psalm 主命令之后。文档给出的两种等价入口为:

vendor/bin/psalm-refactor [options]
vendor/bin/psalm --refactor [options]

独立入口对应的可执行脚本 psalm-refactor 本身只有 9 行,它引入并调用了 Psalm\Internal\Cli\Refactor 类的 run 方法:

// psalm-refactor
require_once __DIR__ . '/src/Psalm/Internal/Cli/Refactor.php';
Refactor::run($argv);

即 src/Psalm/Internal/Cli/Refactor.php 中的 Refactor::run() 是两类入口共同的实际执行体。从源码结构看,Refactor::run() 与 psalm、psalter 共享同一套基础设施:Xdebug 检测、自动加载器注册、CliUtils::initializeConfig() 读取 psalm.xml 配置、ProjectAnalyzer 驱动完整扫描,只是最后把扫描结果导向重构而非报错。

命令行参数速查

Refactor::run() 中定义了合法参数白名单(见 Refactor.php 第 79-83 行):

参数 说明
-h, --help 显示帮助信息
--move "[Identifier]" 指定要移动/迁移的符号(类、方法、属性、常量),可与 --into 连用
--into "[Destination]" 指定 --move 的目标类或命名空间
--rename "[Identifier]" 指定要重命名的符号
--to "[NewIdentifier]" 指定 --rename 的新标识符
-c, --config=psalm.xml 指定 psalm.xml 配置文件路径
-r, --root=<path> 以全局方式运行 Psalm 时必须提供的项目根目录
--threads=<n>, --scan-threads=<n> 多线程加速分析
--debug, --debug-by-line, --debug-emitted-issues 调试信息
--no-progress 关闭进度指示
-f, -m 分别控制输出格式与颜色(短选项白名单中的 f:、m)

帮助文本(Refactor.php 第 132-167 行)还揭示了一个文档未强调的能力:一次可以移动多个项目,用逗号分隔传入即可,例如:

--move "Ns\Foo::bar,Ns\Foo::baz" --into "Biz\Bang\DestinationClass"

参数解析采用了一个小的状态机:--move / --rename 分别把 operation 置为 move / rename,遇到 --into / --to 时要求前面必须已有待移动/重命名的符号,否则报错退出(Refactor.php 第 218-294 行)。所有映射最终汇总进 $to_refactor 数组(源 => 目标 的形式),若为空则提示 No --move or --rename arguments supplied 并退出。

--into 的处理有一个值得注意的细节:当被移动的是方法(含 ::)时,目标只替换类部分,方法名保持不变($arg . '::' . $identifier_name);当被移动的是类时,目标命名空间与原类名拼接($arg . '\\' . $class_name)。这正是"移动到某命名空间"与"重命名"两个语义在参数层的落地方式。

场景一:把一个命名空间下的所有类迁移到另一个命名空间

vendor/bin/psalm-refactor --move "Ns1\*" --into "Some\Other\Namespace"

此命令把 Ns1 下的所有类(如 Ns1\Foo、Ns1\Baz)移入目标命名空间,文件会按需移动(Files are moved as necessary)。

通配符的展开并不发生在 CLI 层,而是在分析阶段由 ProjectAnalyzer::interpretRefactors() 完成(ProjectAnalyzer.php 第 507-523 行):当 source 与 destination 都以 * 结尾时,遍历 codebase->classlike_storage_provider->getAll() 中所有已知的类,凡是名字以 Ns1\ 为前缀的类,都会生成一条 Ns1\Foo => Some\Other\Namespace\Foo 的具体映射,替换掉原始的通配条目。这解释了为什么文档示例中源侧必须写 Ns1\*——它依赖的是扫描阶段收集到的全量类列表,而不是简单的字符串替换。

场景二:在命名空间之间移动单个类

vendor/bin/psalm-refactor --move "Ns1\Foo" --into "Ns2"

把类 Ns1\Foo 移入命名空间 Ns2,代码库中所有对 Ns1\Foo 的引用都会被改写为 Ns2\Foo,文件同样按需移动。

对"纯类到纯类"(source 与 destination 都不含 ::)的映射,interpretRefactors() 的处理(ProjectAnalyzer.php 第 535-564 行)包括:

  1. 校验源类存在:classlikes->hasFullyQualifiedClassName($source),否则抛出 RefactorException('Source class ... doesn't exist');
  2. 校验目标类不存在:目标已存在时抛 Destination class ... already exists,避免命名冲突;
  3. 将 source => destination 记入 codebase->classes_to_move,并为目标创建一个占位的 ClassLikeStorage(继承源的 location、stmt_location、aliases,把 aliases 的 namespace 更新为目标命名空间);
  4. 记入 codebase->class_transforms,供后续改写文件内容与引用时使用。

场景三:移动并重命名一个类

vendor/bin/psalm-refactor --rename "Ns1\Foo" --to "Ns2\Bar\Baz"

把类 Ns1\Foo 移入命名空间 Ns2\Bar 并重命名为 Baz,所有 Ns1\Foo 引用变为 Ns2\Bar\Baz,文件按需移动。

从源码结构看,--rename --to 走的是与场景二相同的"类到类"分支(interpretRefactors() 并不区分该映射来自 --move 还是 --rename,只按 源 => 目标 对处理),因此校验逻辑与 classes_to_move / class_transforms 的登记方式完全一致。

场景四:在类之间移动方法

vendor/bin/psalm-refactor --move "Ns1\Foo::bar" --into "Ns2\Baz"

把 Ns1\Foo 中名为 bar 的方法移入 Ns2\Baz,所有对 Ns1\Foo::bar 的调用改为 Ns2\Baz::bar。

文档明确指出其约束:静态方法可以在任意类之间移动;实例方法只能移入该类的子类。这条约束在源码中有精确对应(ProjectAnalyzer.php 第 591-613 行):

if (!$source_method_storage->is_static
    && !isset(
        $destination_class_storage->parent_classes[strtolower($source_method_id->fq_class_name)],
    )
) {
    throw new RefactorException(
        'Cannot move non-static method ' . $source
            . ' into unrelated class ' . $destination_parts[0],
    );
}

即:源与目标类不同时,若方法是实例方法且源类不在目标类的 parent_classes 集合中,直接抛出 RefactorException。此外方法移动还有两道前置校验:

  • 目标方法已存在时报 Destination method ... already exists;
  • 目标类不存在时报 Destination class ... doesn't exist。

通过校验后,映射分别落入 codebase->methods_to_move(跨类移动)或 codebase->methods_to_rename(同类的纯重命名),并登记一条调用点正则变换(ProjectAnalyzer.php 第 612 行):

$this->codebase->call_transforms[$source_lc . '\((.*\))'] = $destination . '($1)';

这条规则把 Ns1\Foo::bar(...) 形式的调用整体改写为 Ns2\Baz::bar(...),参数部分通过捕获组 (.*) 原样保留——这就是"自动更新所有引用"的实现路径之一。

场景五:移动并重命名一个方法

vendor/bin/psalm-refactor --rename "Ns1\Foo::bar" --to "Ns2\Baz::bat"

把方法 Ns1\Foo::bar 移入 Ns2\Baz 并重命名为 bat,所有 Ns1\Foo::bar 调用变为 Ns2\Baz::bat。

与场景四类似,--rename --to 在方法场景下直接以完整的 目标类::新名 作为映射值($to_refactor<a href="https://link.gitcode.com/i/eb86b47cdead3aaf89bba15927778005" target="_blank">$last_arg] = $arg,见 [Refactor.php 第 278 行),interpretRefactors() 会据此区分"跨类移动"(methods_to_move)与"同类改名"(methods_to_rename),并同样登记 call_transforms 规则。

文档之外的扩展能力:属性、常量与批量移动

阅读 interpretRefactors() 的完整实现(ProjectAnalyzer.php 第 501-700 行)可以发现,除了类与方法,该状态机还支持两类符号的重构,文档未单独列出,但命令格式与方法完全一致:

  1. 属性:形如 Ns1\Foo::$bar 的标识符(源标识符含 $)。限制是:跨类移动只允许静态属性,非静态属性会抛 Cannot move non-static property(第 641-655 行);映射记入 properties_to_move / properties_to_rename 与 property_transforms。
  2. 类常量:Ns1\Foo::CONSTANT 形式。会校验源常量存在(getConstantsForClass)、目标类存在、目标常量不冲突,记入 class_constants_to_move / class_constants_to_rename 与 class_constant_transforms(第 661-694 行)。

对于无法识别的源符号,最终抛出 RefactorException('Psalm cannot locate ' . $source),保证错误在使用前尽早暴露。

底层工作流程:从命令到代码迁移

把源码串起来看,一次 psalm-refactor 执行的完整链路是:

  1. CLI 解析:Refactor::run() 解析参数、构建 $to_refactor 映射表(Refactor.php 第 213-299 行);
  2. 登记重构:ProjectAnalyzer::refactorCodeAfterCompletion($to_refactor) 把映射存入 $this->to_refactor 并置 codebase->alter_code = true(ProjectAnalyzer.php 第 1076-1081 行),此时尚未做任何解释;
  3. 全量扫描:$project_analyzer->check($current_dir) 正常扫描整个项目,收集类、方法、属性、常量的存储与所有引用;
  4. 解释重构:interpretRefactors() 在此之后运行,展开通配符、做存在性与冲突校验,把映射分类落入 classes_to_move、methods_to_move、properties_to_move、class_constants_to_move 以及各 *_transforms 表(ProjectAnalyzer.php 第 501-700 行);
  5. 执行迁移:prepareMigration() 调用 codebase->classlikes->moveMethods()、moveProperties()、moveClassConstants() 等,完成声明位置的移动,配合 class_transforms / call_transforms 改写全部引用,文件随声明体一起移动到目标目录结构。

仓库中有一组对应的测试用例验证了上述能力,可作为行为佐证:ClassMoveTest.php(类移动)、NamespaceMoveTest.php(命名空间迁移)、MethodMoveTest.php(方法移动),它们位于 tests/FileManipulation/ 目录下。

与 psalter(代码修复工具)的分工

Psalm 还有另一个修改代码的工具 Psalter(psalter / psalm --alter),它面向的是基于问题名的自动修复(补全返回类型、参数类型、删除未使用变量等),详见 fixing.md;而 psalm-refactor 面向的是结构性重构——类、方法、属性、常量的移动与重命名,且以 --move/--into 与 --rename/--to 两种显式操作驱动。两者共享 alter_code 模式下的代码改写基础设施(例如 FileManipulation.php 定义的 start/end/insertion_text 文本变换模型),但触发方式和适用场景不同:想批量补类型用 psalter,想动类与方法结构则用 psalm-refactor。

使用建议与限制

  • 重构依赖 Psalm 对代码库的完整索引,请确保项目已配置好 psalm.xml(可用 -c 指定),且所有被移动符号及其引用都在扫描范围内,否则引用可能漏改;
  • 移动操作会真实移动文件,建议在版本控制下执行并在运行后 git diff 复核;目标类/方法/属性/常量重名时会直接以 RefactorException 失败,不会产生半成品的改动;
  • 实例方法只能移入子类、跨类属性移动仅限静态属性,这是当前实现的硬性边界,规划重构时应提前考虑;
  • 出现意外时可用 --debug、--debug-by-line、--debug-emitted-issues 排查分析过程中的中间状态。
登录后查看全文
psalm