一次 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 的程式是不存在的，不要過度迷信那些看似很可靠的系統，

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

轉載請註明出處，本文鏈接：https://www.uj5u.com/houduan/547261.html

標籤：PHP

上一篇：在Eclipse中，移動滑鼠懸停到一些標簽時標簽名會暫時消失？

下一篇：fpm模式下讀取到is_cli為何為true