一次 Hyperf 註解失效問題分析

本文講述了我排查「Hyperf 註解失效」問題的過程，整個排查過程看似一氣呵成，但實際上要曲折得多，甚至一度覺得這是個玄學問題。 ...

問題環境

PHP: 8.0.13
Swoole: 4.6.2
Hyperf: 2.2.33
運行環境: Docker Desktop on WSL2

文章會持續修訂，轉載請註明來源地址：https://her-cat.com/posts/2023/03/02/hyperf-annotation-failure-problem-analysis/

問題背景

有同事說我之前使用註解實現的某個功能有問題，具體表現就是有部分使用了註解的類沒有被 Hyperf 收集到註解收集器中，導致出現了不符合預期的結果。

由於這個功能已經運行了一段時間，並且我在自己的電腦（Mac）上測試是正常的，找另外一個跟他同樣使用 Windows + Docker 開發的同事進行測試也是正常的，所以可以排除業務代碼和環境的問題。

簡化後的代碼如下：

#[Attribute(Attribute::TARGET_CLASS)]  
class CustomAnnotation extends AbstractAnnotation
{
}  
  
#[CustomAnnotation]  
class Foo
{  
}  
  
#[CustomAnnotation]  
class Bar
{  
}

在上面的代碼中，定義了一個註解類 CustomAnnotation，並且在兩個類上使用了這個註解。期望的結果是 Foo 和 Bar 都能夠被 Hyperf 收集到註解收集器中，但實際上只有 Foo 被收集到了。

Foo 和 Bar 分別在不同的文件中，但是都在同一個目錄下，該目錄下的文件數量有 60+。

於是我倆開始在他的電腦上排查是不是 Hyperf 的問題。

源碼分析

在 Hyperf 啟動時， ClassLoader 類載入器會掃描項目中所有的類文件，並將元數據（註解與類之間的關係）收集到相應的註解收集器中，如果沒有自定義註解收集器，則預設統一收集到 Hyperf\Di\Annotation\AnnotationCollector 類中。

下麵是完成收集註解的主要邏輯：

使用 symfony/finder 組件提供的 Finder 類遍歷指定目錄下所有的 PHP 類文件。
通過反射讀取每個文件中的類及其屬性、方法上使用的註解。
依次檢查這些註解是否實現了 Hyperf\Di\Annotation\AnnotationInterface 介面，該介面定義了三個方法分別用於收集類、方法、屬性的元數據。
如果註解實現了該介面，根據註解使用位置調用相應的方法將其收集到註解收集器中。

完成收集後，我們就能使用註解收集器提供的靜態方法的獲取對應的元數據用於實現一些自定義的邏輯和功能。

第一步就是先檢查類文件是否被 Finder 類讀取到了，這部分的邏輯在 ReflectionManager::getAllClasses() 靜態方法中。

public static function getAllClasses(array $paths): array  
{  
    $finder = new Finder();  
    // 設置讀取指定目錄下的 PHP 文件
    $finder->files()->in($paths)->name('*.php');  
    $parser = new Ast();  
  
    $reflectionClasses = [];  
    foreach ($finder as $file) {  
        try {  
	        // 解析文件內容獲取類名稱
            $stmts = $parser->parse($file->getContents());  
            if (! $className = $parser->parseClassByStmts($stmts)) {
	            // 沒獲取到說明沒有定義類
                continue;  
            }
            $reflectionClasses[$className] = static::reflectClass($className);  
        } catch (\Throwable) {  
        }    
    }    
    return $reflectionClasses;  
}

將獲取目錄下文件的這段代碼提出來單獨進行測試。由於 Finder 類實現了 IteratorAggregate 介面，所以在上面的代碼中可以直接對 Finder 類進行遍歷，也可以使用 iterator_to_array() 函數直接獲取迭代器的結果。

$finder = new Finder();  
// 設置讀取指定目錄下的 PHP 文件
$finder->files()->in('出現問題的目錄路徑')->name('*.php'); 
var_dump(iterator_to_array($finder));

通過觀察列印的結果就發現了問題所在：沒有讀取到 Bar 的類文件。

當時就在想，這麼流行的一個組件包總不能出現這麼低級的 Bug 吧？抱著懷疑的心態繼續分析 Finder 類實現迭代器的代碼，最後將問題定位到了 PHP 內置的 RecursiveDirectoryIterator 類上，Finder 類實際上就是對 PHP 的這些類做了一層封裝。

RecursiveDirectoryIterator 提供了一個用於遞歸迭代文件系統目錄的功能，用這個類再次進行上面的測試，依然沒有讀取到 Bar 的類文件。

$iter = new RecursiveDirectoryIterator('出現問題的目錄路徑');
var_dump(iterator_to_array($iter));

於是，我又一次陷入了懷疑中，難道 PHP 實現的這個類有問題？還得繼續看 PHP 的源碼？我在猶豫了一會後打開了 Google，抱著肯定有人也遇到過這個問題的想法輸入了「RecursiveDirectoryIterator bug」，按下回車，在短暫的頁面載入後...

嘿，還真有人已經遇到過這個問題。

真相大白

在前幾條搜索結果中，赫然發現有人在 PHP 官方的 Bug 系統反饋了這個問題：RecursiveDirectoryIterator returns incorrect results for Docker Desktop on WSL2，並貼心的附帶了可以復現問題的代碼。

下麵是精簡過後的復現代碼。

$filesPath = __DIR__.'/files';  
  
if (! mkdir($filesPath) && ! is_dir($filesPath)) {  
    throw new \RuntimeException(sprintf('Directory "%s" was not created', 'files'));  
}  
  
$max = 1;  
$stop = 5000;  
  
// 生成測試文件，模擬目錄中文件較多的情況  
foreach(range(1, $stop) as $index) {  
    $message = sprintf("creating %s\n", $index);  
    echo $message;  
    file_put_contents(__DIR__ . '/files/file' . $index, str_repeat('A', 100));  
}  
  
$iter = new \RecursiveDirectoryIterator($filesPath, FilesystemIterator::KEY_AS_PATHNAME|FilesystemIterator::CURRENT_AS_FILEINFO|FilesystemIterator::SKIP_DOTS);  
var_dump(iterator_count($iter));
// 列印出來的數字小於 5000 說明復現成功了

PHP 官方給出了回覆：這是 WSL 的 Bug，並提供了相關的 issue：WSL2: Seek of directory entry by lseek does not work on v9fs。裡面的實際輸出跟我們發現這個問題時的列印結果幾乎一模一樣，感興趣的可以去看看。

有人可能會問，lseek() 函數跟 RecursiveDirectoryIterator 類有什麼關係嗎？

當然有！將上面的代碼保存到 test.php 文件，然後執行 strace php test.php 命令查看 PHP 代碼的系統調用情況。

...省略其他部分...
openat(AT_FDCWD, "/home/ubuntu/files", O_RDONLY|O_NONBLOCK|O_CLOEXEC|O_DIRECTORY) = 4
fstat(4, {st_mode=S_IFDIR|0775, st_size=135168, ...}) = 0
brk(0x55d84733f000)                     = 0x55d84733f000
getdents(4, /* 1024 entries */, 32768)  = 32752
lseek(4, 0, SEEK_SET)                   = 0
getdents(4, /* 1024 entries */, 32768)  = 32752
getdents(4, /* 1024 entries */, 32768)  = 32768
getdents(4, /* 1024 entries */, 32768)  = 32768
getdents(4, /* 1024 entries */, 32768)  = 32768
getdents(4, /* 906 entries */, 32768)   = 28992
getdents(4, /* 0 entries */, 32768)     = 0
write(1, "int(5000)\n", 10int(5000)
)             = 10
close(3)                                = 0
close(4)                                = 0
...省略其他部分...

可以看到，RecursiveDirectoryIterator 類在底層中調用了 lseek() 函數，它的作用是設置文件偏移量。lseek(4, 0, SEEK_SET) 表示將文件偏移量設置為 0，即文件開頭的位置，該函數無法工作會導致下次操作依然使用的是原來的文件偏移量。

Linux 中萬物皆為文件，包括目錄。

用 PHP 代碼來舉個例子，這裡使用 PHP 的 rewinddir() 函數代替 lseek() 函數，實際上底層調用的還是 lseek() 函數。

$dh = opendir(__DIR__ . '/files');  
  
echo '開始讀取目錄中的所有文件:' . PHP_EOL;  
while (($file = readdir($dh)) !== false) {  
    echo 'filename:' . $file . PHP_EOL;  
}
  
echo '再次讀取目錄中的所有文件:' . PHP_EOL;  
// 這時文件偏移量已經到達文件的末尾，再次讀取目錄將不會有任何輸出，模擬 lseek() 函數無法工作的情況 
while (($file = readdir($dh)) !== false) {  
    echo 'filename:' . $file . PHP_EOL;  
}  
  
// 將文件偏移量重置到文件的開頭  
rewinddir($dh);  
  
echo '重置偏移量後讀取目錄中的所有文件:' . PHP_EOL;  
// 與第一次讀取的結果相同，模擬 lseek() 函數正常工作的情況
while (($file = readdir($dh)) !== false) {
    echo 'filename:' . $file . PHP_EOL;  
}  
  
closedir($dh);

在 WSL2 以外的系統中運行以上代碼，可以得到與預期一致的結果。那麼在 WSL2 中運行的結果是什麼？

解決問題

當然，最好是 WSL 官方能夠修複這個問題，但是從有人提出這個問題到現在已經快三年了依然沒有被解決的情況來看，不知道得等到猴年馬月。

提問的作者也給出了一種解決方案，開啟 Hyper V。但是經過測試後發現開啟 Hyper V 依然會出現這個問題，所以最後直接從 WSL2 回滾到 WSL1，從另一種「根本上」解決這個問題。

總結

等等，文章開頭不是說已經排除是環境的問題了嗎？怎麼最後又是環境的問題了？

是的，這是由於我當時並沒有問清楚，只是確認了另一個同事是用 Docker 運行的，我怎麼也沒想到他是本地運行了個虛擬機，然後在虛擬機裡面運行 Docker...

當然，後面的源碼分析也不是一點作用都沒有，至少將問題的範圍從 Hyperf 框架縮小到了 Finder 類，再到 RecursiveDirectoryIterator 類。否則直接 Google 搜索「Hyperf 註解失效」是很難找到正確答案的。

在這篇文章中，講述了我排查「Hyperf 註解失效」問題的過程，整個排查過程看似一氣呵成，但實際上要曲折得多，甚至一度覺得這是個玄學問題。

最後，沒有 Bug 的程式是不存在的，不要過度迷信那些看似很可靠的系統。

博客地址：她和她的貓，歡迎關註。