PHP静态分析的Baseline管理：在旧项目中引入PHPStan/Psalm的平滑迁移

大家好，今天我们来聊聊如何在旧项目中引入PHPStan或Psalm这样的静态分析工具，并进行平滑迁移。这是一个很多PHP开发者都面临的问题，尤其是在接手历史遗留项目时。直接开启最高级别的静态分析，往往会产生大量的错误报告，让人望而却步。因此，我们需要一种循序渐进的方法，即Baseline管理。

什么是Baseline？为什么需要它？

Baseline，顾名思义，就是基线。在这里，Baseline指的是我们在引入静态分析工具时，允许存在的错误集合。简单来说，它就像一个“白名单”，告诉静态分析工具：这些错误我们已知，暂时允许存在，后续会逐步修复。

为什么需要Baseline？

降低初始噪音： 旧项目往往存在大量的代码坏味道和潜在错误。如果直接开启高等级别的静态分析，可能会产生几百甚至上千个错误报告，让人难以处理。Baseline可以帮助我们忽略这些已知错误，专注于新引入的或更严重的问题。
渐进式改进： 通过Baseline，我们可以逐步降低代码的复杂度，修复潜在的错误，并逐步提高静态分析的严格程度。
团队协作： Baseline可以作为团队成员共同维护的代码质量标准，确保大家朝着共同的目标前进。
减少心理压力： 面对大量的错误报告，开发者的心理压力会很大。Baseline可以帮助我们控制问题的范围，避免一次性解决所有问题的焦虑。

PHPStan和Psalm的Baseline生成

PHPStan和Psalm都提供了生成Baseline的功能，可以将当前项目中的所有错误记录下来，并作为Baseline文件。

1. PHPStan Baseline生成

使用PHPStan生成Baseline的命令如下：

./vendor/bin/phpstan analyse --generate-baseline phpstan-baseline.neon

这条命令会分析你的代码，并将所有错误信息保存到phpstan-baseline.neon文件中。 phpstan-baseline.neon文件采用Neon格式，内容类似于：

parameters:
    ignoreErrors:
        -
            message: "#Access to an undefined property.*#"
            path: src/Entity/User.php
        -
            message: "#Call to an undefined method.*#"
            path: src/Service/UserService.php
        -
            message: "#Parameter .* of method .* expects .* but gets .*# "
            path: src/Controller/UserController.php

然后在phpstan.neon配置文件中引入这个Baseline文件：

includes:
    - phpstan-baseline.neon

parameters:
    level: 5 # 逐渐提高等级

2. Psalm Baseline生成

使用Psalm生成Baseline的命令如下：

./vendor/bin/psalm --init

Psalm会引导你完成初始化配置，并询问是否生成Baseline。如果选择生成，它会将错误信息保存到psalm.xml配置文件中，位于<baseline>节点下。内容类似于：

<?xml version="1.0"?>
<psalm
    errorLevel="1"
    resolveFromConfigFile="true"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns="https://getpsalm.org/schema/config"
    xsi:schemaLocation="https://getpsalm.org/schema/config vendor/vimeo/psalm/config.xsd"
>
    <projectFiles>
        <directory name="src"/>
    </projectFiles>
    <baseline>
        <issue severity="error" type="UndefinedPropertyFetch" message="Property User::$nonExistentProperty does not exist" file="src/Entity/User.php" line="20"/>
        <issue severity="error" type="UndefinedMethod" message="Call to method User::doSomething() on an unknown class or interface User" file="src/Service/UserService.php" line="35"/>
    </baseline>
</psalm>

Baseline的管理策略

有了Baseline文件后，我们需要制定合理的管理策略，才能有效地提升代码质量。

1. 逐步提高静态分析等级

不要一开始就使用最高的静态分析等级。应该从较低的等级开始，例如PHPStan的level 0或Psalm的errorLevel="7"，然后逐步提高等级。每次提高等级后，都会发现新的错误。将这些错误添加到Baseline文件中，并进行修复。

工具	初始等级建议	逐步提高的方向
PHPStan	Level 0	Level 1 -> Level 2 -> … -> Level Max
Psalm	errorLevel="7"	errorLevel="6" -> errorLevel="5" -> … -> errorLevel="1"

2. 定期审查和更新Baseline

Baseline不是一成不变的。随着代码的不断修改，Baseline中的错误信息可能会失效。因此，我们需要定期审查和更新Baseline，删除已经修复的错误，添加新发现的错误。

建议的做法是：

每次发布新版本之前，更新Baseline。 这样可以确保Baseline始终与代码保持同步。
定期进行代码质量审查，并更新Baseline。 可以安排每周或每月的代码质量审查，集中处理Baseline中的错误。

3. 区分不同类型的错误

并非所有的错误都需要立即修复。有些错误可能比较紧急，需要优先处理；有些错误可能不那么重要，可以稍后再处理。

我们可以根据错误的类型，将其分为以下几类：

致命错误： 这些错误会导致程序崩溃或数据丢失。例如，未捕获的异常、访问不存在的属性或方法。
潜在错误： 这些错误可能会导致程序出现问题，但不一定会立即发生。例如，类型不匹配、变量未定义。
代码坏味道： 这些错误不会直接导致程序出错，但会降低代码的可读性和可维护性。例如，过长的函数、重复的代码。

对于不同类型的错误，我们可以采取不同的处理策略：

致命错误： 必须立即修复。
潜在错误： 尽快修复，避免埋下隐患。
代码坏味道： 可以逐步重构，提高代码质量。

4. 自动化Baseline管理

手动管理Baseline文件可能会很繁琐。因此，我们可以考虑使用自动化工具来简化Baseline管理流程。

例如，可以使用Git Hooks来自动检查代码是否引入了新的静态分析错误。如果引入了新的错误，则阻止提交，并提示开发者修复错误或将其添加到Baseline文件中。

5. 结合CI/CD流程

将静态分析集成到CI/CD流程中，可以确保每次代码提交都会经过静态分析的检查。如果静态分析发现错误，则构建失败，并阻止部署。这样可以有效地防止低质量的代码进入生产环境。

案例分析：使用PHPStan在旧项目中进行Baseline管理

假设我们有一个名为LegacyProject的旧项目，目录结构如下：

LegacyProject/
├── src/
│   ├── Entity/
│   │   └── User.php
│   ├── Service/
│   │   └── UserService.php
│   └── Controller/
│       └── UserController.php
├── vendor/
├── composer.json
└── composer.lock

User.php文件可能包含以下代码：

<?php

namespace AppEntity;

class User
{
    public $name;
    public $age;

    public function __construct(string $name, int $age)
    {
        $this->name = $name;
        $this->age = $age;
    }

    public function getFullName()
    {
        return $this->name . " " . $this->lastName; // 故意引入错误：lastName未定义
    }
}

UserService.php文件可能包含以下代码：

<?php

namespace AppService;

use AppEntityUser;

class UserService
{
    public function createUser(string $name, int $age) : User
    {
        $user = new User($name, $age);
        $user->doSomething(); // 故意引入错误：User类没有doSomething方法
        return $user;
    }
}

步骤 1：安装PHPStan

首先，我们需要安装PHPStan：

composer require --dev phpstan/phpstan

步骤 2：生成Baseline文件

运行以下命令生成Baseline文件：

./vendor/bin/phpstan analyse --generate-baseline phpstan-baseline.neon

PHPStan会分析代码，并将错误信息保存到phpstan-baseline.neon文件中。

步骤 3：配置PHPStan

创建phpstan.neon配置文件：

includes:
    - phpstan-baseline.neon

parameters:
    level: 0 # 从最低等级开始
    paths:
        - src

步骤 4：运行PHPStan

运行PHPStan，检查代码是否存在错误：

./vendor/bin/phpstan analyse

PHPStan会忽略Baseline文件中的错误，只报告新的错误。

步骤 5：逐步提高等级并修复错误

逐步提高PHPStan的等级，例如：

parameters:
    level: 1

运行PHPStan，会发现新的错误。修复这些错误，并从phpstan-baseline.neon文件中删除对应的错误信息。如果无法立即修复，则将新的错误信息添加到phpstan-baseline.neon文件中。

步骤 6：定期审查和更新Baseline

定期审查phpstan-baseline.neon文件，删除已经修复的错误，添加新发现的错误。

代码示例：自动化Baseline管理 (Git Hook)

我们可以使用Git Hook来自动检查代码是否引入了新的静态分析错误。

1. 创建.git/hooks/pre-commit文件

在项目根目录下创建.git/hooks/pre-commit文件，并添加以下内容：

#!/bin/sh

# Run PHPStan and check for new errors
NEW_ERRORS=$("./vendor/bin/phpstan analyse --error-format json | jq '.files | to_entries | map(.value) | flatten | length'")

# If new errors are found, prevent the commit
if [ "$NEW_ERRORS" -gt 0 ]; then
  echo "Error: New PHPStan errors found. Please fix them or add them to the baseline."
  ./vendor/bin/phpstan analyse # 显示错误信息
  exit 1
fi

exit 0

2. 使.git/hooks/pre-commit文件可执行

chmod +x .git/hooks/pre-commit

现在，每次提交代码时，Git Hook会自动运行PHPStan，并检查是否存在新的错误。如果存在新的错误，则阻止提交，并提示开发者修复错误或将其添加到Baseline文件中。

注意: 这个Git Hook脚本依赖于jq工具，需要先安装jq。可以使用apt-get install jq (Debian/Ubuntu) 或 brew install jq (macOS) 来安装。

总结

通过Baseline管理，我们可以有效地降低在旧项目中引入静态分析工具的难度，并逐步提高代码质量。关键在于：

循序渐进： 从较低的静态分析等级开始，逐步提高等级。
定期维护： 定期审查和更新Baseline文件，确保其与代码保持同步。
自动化： 使用自动化工具简化Baseline管理流程。
团队协作： 建立团队共同维护的代码质量标准。
持续改进： 将静态分析集成到CI/CD流程中，确保每次代码提交都会经过检查。

通过坚持这些原则，我们可以将静态分析工具真正融入到开发流程中，从而持续提升代码质量，减少潜在的错误。

最后的想法

Baseline是引入静态分析到遗留项目中的关键策略。
逐步提高静态分析等级，并定期审查和更新Baseline。
自动化Baseline管理，并将其集成到CI/CD流程中，以实现持续的代码质量改进。