Facade 类注释应使用 @mixin 而非 @return，因其仅为静态代理，真实逻辑在目标类中；@mixin 可使 IDE 正确识别方法跳转、补全与类型推导，而 @return 会误导工具并削弱代理效果。
Facade 类注释要写 @mixin 而不是 @return
ThinkPHP 的 Facade 是静态代理，本身不实现业务逻辑，真实方法在被代理的类里。直接写 @return 会误导 IDE 和静态分析工具，认为返回的是 Facade 自身或 void，导致方法跳转失败、自动补全缺失。
正确做法是在 Facade 类的 DocBlock 中用 @mixin 声明它“混入”了目标类的行为：
/**
* @mixin \think\Cache
*/
class Cache extends Facade
{
// ...
}这样 PHPStorm、VS Code（配合 Intelephense）就能把 Cache::get() 当作 \think\Cache::get() 处理，类型推导、跳转、补全全部正常。
别在 Facade 方法上单独加 @return
Facade 类里的方法（比如 getFacadeClass()）只是框架调用的钩子，你不该也不需要调用它们。给这些方法加返回值注释不仅没用，还会干扰 IDE 对 @mixin 的识别逻辑。
立即学习“PHP免费学习笔记（深入）”；
常见错误写法（应避免）：
/**
* @return string
*/
protected static function getFacadeClass()
{
return 'cache';
}这会让部分分析器误以为该 Facade 类自身有返回值语义，反而削弱 @mixin 的效果。
如果要提示链式调用，得靠目标类自身的注释
比如 Db::table('user')->where('id', 1)->find() 能链式调用，靠的不是 Db Facade 上写了什么，而是 \think\Db 或其返回的查询对象（如 Query）本身有正确的 @return $this 或具体类型注释。
所以重点检查：
-
\think\Db::table()是否返回Query实例且注释为@return \think\Query -
\think\Query::where()是否返回$this或\think\Query
Facade 层不需要、也不应该重复声明这些返回类型 —— 它只负责“转发”，类型信息必须由实际执行者提供。
自定义 Facade 时，@mixin 必须指向真实类的完整命名空间
手写 Facade 时最容易出错：路径写错、类名拼错、用了别名没展开。例如：
❌ 错误：@mixin Cache（没命名空间，IDE 找不到）
❌ 错误：@mixin think\Cache（缺反斜杠）
✅ 正确：@mixin \think\Cache
另外注意：如果目标类本身没有完善注释（比如没写 @method 或方法缺少 @return），即使 @mixin 写对了，IDE 也补全不出方法。这时候得去补目标类，而不是在 Facade 上硬加。
