正確注釋@return讓PHPstorm動(dòng)態(tài)返回類

simon_chen 發(fā)布于2019-07-01 10:23 / 1713人閱讀

摘要：大意就是和差不多，但是父類方法子類調(diào)用，仍然返回父類。這個(gè)確切的對(duì)象實(shí)例，通常用于表示流暢的界面。這次我才真正意識(shí)到了注釋的重要性。。。最后，因?yàn)椴⒉皇俏乙粋€(gè)人在寫，所以沒有辦法進(jìn)行大刀闊斧地改動(dòng)，只能盡可能地優(yōu)化。

場(chǎng)景是這樣的，有一個(gè)BaseModel（繼承自ActionRecord），所有的其他model都繼承自它，然后其中有一個(gè)方法，簡(jiǎn)單貼下這個(gè)類的代碼，：

class BaseModel extends ActiveRecord
{
    protected $temp_model;
    
    public function getCacheModel()
    {
        return $this->temp_model;
    }
}

這個(gè)方法的作用是取得在做參數(shù)驗(yàn)證時(shí)，從數(shù)據(jù)庫(kù)查出的，緩存下來的實(shí)例對(duì)象。
這個(gè)時(shí)候，問題來了，我在取出這個(gè)對(duì)象的時(shí)候，PHPstorm沒有了提示（如方法提示，屬性提示等），按照一般的情況，只需要在方法前面加上@return注釋就可以了。

/**
 * @return static
 */
public function getCacheModel()
{
    return $this->temp_model;
}

我們繼續(xù)深入研究一下，關(guān)于這個(gè)static的意思，我特地在PHPDoc上查閱了一下，

static
An object of the class where this value was consumed, if inherited it will represent the child class. (see late static binding in the PHP manual).

Google翻譯一下，大意如下：
消耗此值的類的對(duì)象，如果繼承它將表示子類。
（參見PHP手冊(cè)中的后期靜態(tài)綁定）。

大概意思就是就會(huì)返回調(diào)用這個(gè)方法的類，如果是父類方法子類調(diào)用，那么將返回子類。

類似的還有2個(gè)

self
An object of the class where this type was used, if inherited it will still represent the class where it was originally defined.
$this
This exact object instance, usually used to denote a fluent interface.

直譯如下，
self:使用此類型的類的對(duì)象，如果繼承它，它仍將表示最初定義它的類。
大意就是和static差不多，但是父類方法子類調(diào)用，仍然返回父類。
$this:這個(gè)確切的對(duì)象實(shí)例，通常用于表示流暢的界面。
和self差不多。

但是到了這里，我的問題仍然沒有解決，無論我@return的值改成什么，仍然返回的是BaseModel，盡管我在這個(gè)getCacheModel()方法里打印 self::className() 時(shí)，出現(xiàn)的是子類名。

于是我們繼續(xù)往上面看，我是在controller調(diào)用的，controller的代碼如下：

public function actionCommitReward()
{
    $model=$this->goCheck(new TakeRewards(["scenario"=>"commit_reward"]));

    //獲取實(shí)際要修改的數(shù)據(jù)
    $reward = $model->getCacheModel();
}

看起來沒有什么問題，這個(gè)時(shí)候我們要注意了， $model 是由$this->goCheck()調(diào)用得到的，我們?nèi)タ匆幌耮oCheck方法：

//驗(yàn)證參數(shù)是否合法
public function goCheck($model, $dada = "")
{
    $data = $this->postData;//post傳入的數(shù)據(jù)
    if ($model->load($data, "") && $model->validate())//數(shù)據(jù)效驗(yàn)

return $model;

    else (new PublicFunction())->returnWayTip("1001", PublicFunction::getModelError($model));//這里理解成拋異常
}

這里不規(guī)范的地方出現(xiàn)了，由于這里傳入的是model（對(duì)象類型），所以PHPstorm并沒法知道我們具體傳入的是什么類，加上注釋后：

/**
 * @param object $model
 * @param string $dada
 * @return model1|model2
 */

這樣后，問題“勉強(qiáng)解決”。只是每增加一個(gè)表，會(huì)需要在@return里增加表相對(duì)應(yīng)的類名，而且會(huì)有類本來不應(yīng)該存在的屬性被提示。

為什么這里不能用static呢？因?yàn)檫@里是$this調(diào)用的，返回controller類，并沒有什么用，而這個(gè)也導(dǎo)致了后面使用$model->getCacheModel()方法時(shí)，沒有辦法正常識(shí)別應(yīng)該返回的類（返回什么類取決與goCheck的@return注釋是什么）。

當(dāng)然你可以不寫注釋，那么你會(huì)發(fā)現(xiàn)，所以的提示都沒有了。
這次我才真正意識(shí)到了注釋的重要性。。。原來PHPstorm之所以都提示，都是因?yàn)榇蠹野碢HPDoc的規(guī)范寫了注釋啊！

最后可能有同學(xué)會(huì)問了，為什么不把goChekc方法放到BaseModel里呢？對(duì)的，實(shí)際上規(guī)范的做法是應(yīng)該這樣的，但是因?yàn)槲疫@樣把Yii::$app->request->post()賦值在controller里的$this->postData里（雖然這樣方便一丟丟），而且在做token換id的一些操作了進(jìn)行了手動(dòng)賦值，所以沒有辦法，因?yàn)樵趍odel獲取不到這個(gè)postData，當(dāng)然你一定要挪進(jìn)去也是可以的，只不過每次都需要傳參$this->postData，見仁見智吧。

但是，這2個(gè)方法都并不規(guī)范，$this->postData = Yii::$app->request->post(); 把全局的變量變成了一個(gè)局部變量，規(guī)范的做法應(yīng)該是使用Yii::$app->request->post($name,$dafaultValue)來給post數(shù)據(jù)賦值。

最后，因?yàn)椴⒉皇俏乙粋€(gè)人在寫，所以沒有辦法進(jìn)行大刀闊斧地改動(dòng)，只能盡可能地優(yōu)化。BTW，希望大佬們有更好的意見可以說說，因?yàn)閭€(gè)人比較經(jīng)驗(yàn)也比較不足，都是自己摸索。