php接口注释必须用@method显式声明方法签名，参数名、类型和返回值须与接口声明严格一致，继承时需重复父接口的@method并注明重载，禁止包含实现细节或非强制约束。
PHP 接口（interface）本身不包含实现，但注释必须清晰表达契约意图——不是“这段代码做什么”，而是“实现者必须保证什么”。严谨的接口注释核心在于：用 @method 描述可调用行为，用 @param/@return 约束签名，且所有类型必须与实际声明一致。
接口文档必须用 @method 显式声明每个方法
PHP 的 interface 无法在 docblock 中直接写 @param 或 @return 在接口定义处（因为 PHP 解析器不支持），所以必须用 @method 伪指令完整描述每个方法签名。否则 IDE 无法推导类型，静态分析工具（如 PHPStan、Psalm）也会忽略契约约束。
常见错误是只写自然语言描述，例如：
/** * 用户服务接口 * getProfile() 返回用户资料 */
这毫无机器可读性。正确写法是：
立即学习“PHP免费学习笔记（深入）”；
/**
* 用户服务契约
*
* @method array getProfile(int $userId) 获取指定用户的完整资料数组
* @method bool updateUser(int $userId, array $data) 更新用户信息，成功返回 true
*/</p><H3><code>@method</code> 签名必须与实现类严格一致</H3><p><code>@method</code> 不是自由发挥的说明，它会被 PHPStan/IDE 当作真实方法签名来校验。任何偏差都会导致误报或类型丢失：</p><div class="aritcle_card flexRow">
<div class="artcardd flexRow">
<a class="aritcle_card_img" href="/ai/2382" title="AI发型设计"><img
src="https://img.php.cn/upload/ai_manual/001/246/273/176300408412137.png" alt="AI发型设计" onerror="this.onerror='';this.src='/static/lhimages/moren/morentu.png'" ></a>
<div class="aritcle_card_info flexColumn">
<a href="/ai/2382" title="AI发型设计">AI发型设计</a>
<p>虚拟发型试穿工具和发型模拟器</p>
</div>
<a href="/ai/2382" title="AI发型设计" class="aritcle_card_btn flexRow flexcenter"><b></b><span>下载</span> </a>
</div>
</div><ul><li>参数名必须完全匹配（<code>$userId</code> 不能写成 <code>$id</code>）</li><li>类型必须与接口中 <code>function getProfile(int $userId): array;</code> 声明一致（不能省略 <code>int</code> 或写成 <code>integer</code>）</li><li>返回类型必须精确（<code>array</code> ≠ <code>array|string</code>，后者需显式写成联合类型）</li><li>如果方法有可选参数，<code>@method</code> 必须带默认值（如 <code>string $format = 'json'</code>）</li></ul><H3>接口继承时，子接口注释要覆盖父接口并补充新契约</H3><p>当一个接口 <code>extends</code> 另一个接口，子接口的 docblock 必须重新声明所有继承来的方法（包括父接口里的 <code>@method</code>），否则工具会丢失父接口的契约信息。不能只写新增方法。</p><p>例如：</p><pre class="brush:php;toolbar:false;">/**
* 基础存储接口
*
* @method mixed get(string $key)
* @method void set(string $key, mixed $value, int $ttl = 0)
*/
interface CacheInterface {}
<p>/**</p><ul><li>带前缀的缓存接口</li><li></li><li>@method mixed get(string $key) 重载：自动添加命名空间前缀</li><li>@method void set(string $key, mixed $value, int $ttl = 0) 重载：键名自动加前缀</li><li>@method string getPrefix() 返回当前使用的前缀字符串
*/
interface PrefixedCacheInterface extends CacheInterface {}注意：即使只是语义重载，也要重复声明父接口的 @method，并在描述中注明“重载”或“增强”，避免歧义。
别把接口注释写成实现说明
接口注释里禁止出现以下内容：
- 具体实现路径（如
// 使用 RedisDriver） - 内部状态描述（如
// 内部维护一个连接池） - 性能提示（如
// O(1) 时间复杂度—— 这属于实现细节，接口不承诺性能） - 非强制约束（如
// 建议传入非空字符串—— 接口只规定类型和行为，不处理建议）
接口注释的唯一职责是：让实现者一眼看清「必须提供哪些方法」「每个方法接收什么」「必须返回什么」。多一个字，就多一分误解风险。
