PHP Override 属性怎样提前发现方法签名错误

PHP 8.3 引入的 #[\Override] 可以把“这个方法必须来自父类或接口”的意图写进代码。只要目标方法不存在，PHP 就会在编译阶段报错；因此，子类把 handle() 误写成 handel() 时，不会等到某条业务路径被调用才暴露。它不能替代继承方法的签名兼容规则，但能提前抓住重写关系本身写错的问题。

官方手册：https://www.php.net/manual/en/class.override.php

本文只讨论方法级 Override：父类方法和接口方法怎样匹配、签名错误怎样区分，以及把旧 PHP 项目迁移到显式标注时应该检查什么。

先把 Override 的检查范围说清楚

可以把它看成一条声明：当前方法应该覆盖父类同名方法，或实现已实现接口中的同名方法。PHP 官方手册同时说明，找不到匹配目标时会产生编译期错误；构造方法不在这项检查范围内。

给真正的重写方法加上标记

先看一个父类方法被子类覆盖的最小写法。注意属性写在方法声明的上一行，命名空间完整写法是 #[\Override]。

这两处标记表达的是同一个意图：方法不是“碰巧同名”，而是依赖父类或接口的契约。如果把 formatTitle 拼成 formatTtile，或者把 cacheKey 拼错，PHP 会在编译阶段指出没有匹配的父类方法或接口方法。

方法名错误和签名错误不是一回事

标题里常说的“签名错误”容易混在两种问题里。Override 最擅长发现的是重写目标不存在：例如方法名、继承层级或接口实现关系写错。参数类型、返回类型和可见性等签名兼容性，则仍然由 PHP 的继承规则检查；即使没有写 Override，不兼容的重写也可能直接报错。

 $id]; // 基类给出参数和返回值契约。
    }
}

final class AdminGateway extends UserGateway
{
    #[\Override]
    public function find(int $id): array
    {
        return parent::find($id); // 名称和签名都与父类保持一致。
    }
}

// 下面这种写法的核心问题是返回类型不兼容，不能靠 Override 修复。
// public function find(int $id): string { return (string) $id; }

// 下面这种写法则是重写目标不存在，Override 会直接暴露拼写错误。
// #[\Override]
// public function finnd(int $id): array { return []; }

迁移时可以把判断拆成两步：先问“父类或接口里有没有这个同名方法”，再问“参数、返回值和可见性是否满足兼容规则”。第一个问题由 Override 把意图固定下来，第二个问题仍要按照 PHP 的方法签名规则处理。

从旧项目迁移时按这份清单推进

1. 先找继承和接口入口：从基类较多、接口较多的业务层开始，列出明确承担重写职责的方法。
2. 只标记有目标的方法：方法确实来自父类或接口后再添加 Override；工具方法、私有方法和构造方法不要为了整齐而标记。
3. 先修命名，再修签名：如果出现“没有匹配目标”，先检查拼写、父类名称和接口列表；如果目标存在，再处理参数、返回值和可见性。
4. 把 PHP 版本放进回归环境：Override 从 PHP 8.3.0 起可用，旧运行环境不能直接部署带该语法的代码。
5. 保留最小编译检查：迁移后至少加载覆盖核心继承链的类文件，尽早发现属性标记和签名变化带来的错误。

PHP 手册当前还记录了 PHP 8.5 对 Override 属性范围的变化，但本文不把属性重写展开为另一项教程。若项目只处理方法，按方法契约迁移即可；不要因为属性能力扩展而把检查范围扩大到当前任务之外。

两个容易混淆的问题

没有写 Override，方法还能正常覆盖吗？ 可以。Override 是把“我有意覆盖”写成可检查的声明，不是让普通继承失效的开关；旧代码是否能覆盖，仍取决于类关系和签名兼容规则。

把父类方法改名后，子类一定会立刻报错吗？ 只有子类仍保留 #[\Override] 且找不到新的匹配目标时，才会因该声明触发错误。没有 Override 的旧代码可能暂时安静，但原本的重写意图已经失去约束。

因此，PHP Override 的价值不在于替你设计继承结构，而在于把继承关系中的“这必须是重写”明确交给语言检查。先用它锁定方法名，再按原有签名规则做兼容回归，迁移结果才可靠。