契约接口是 Laravel 为解耦和可测试性设计的规范，通过类型提示接口而非具体类，实现依赖注入、易 mock 和驱动切换；需在服务提供者中绑定实现，避免手动 new 或混用 Facade/辅助函数。
契约接口（Contract）在 Laravel 中不是语法强制要求，而是框架为解耦和可测试性设计的一套接口规范。它不改变运行逻辑，但直接影响你写代码的方式和后续维护成本。
为什么 Illuminate\Contracts 下的接口比直接依赖具体类更安全
直接 new 一个 MailManager 或依赖 Illuminate\Mail\Mailer 类，会导致：
- 测试时无法轻松 mock 邮件发送行为（得绕过真实 SMTP 或打桩整个类）
- 换邮件驱动（如从 SMTP 切到 Log 或第三方服务）时，需改多处 new 实例或类型提示
- IDE 自动补全可能指向具体实现，掩盖了“我真正需要的是发邮件能力”这一语义
而用 Illuminate\Contracts\Mail\Mailer 接口做类型提示，Laravel 容器会自动注入绑定的实现（默认是 Illuminate\Mail\Mailer），你只声明“我要发邮件”，不关心谁来发。
如何在 Service 类中正确使用 Contract 接口
不要手动 new，也不要硬编码具体类路径。必须通过构造函数或方法参数让容器注入：
use Illuminate\Contracts\Mail\Mailer;
class OrderNotificationService
{
protected $mailer;
public function __construct(Mailer $mailer)
{
$this->mailer = $mailer;
}
public function sendConfirmation($order)
{
$this->mailer->to($order->email)->send(new OrderConfirmed($order));
}
}
关键点：
-
Mailer是接口，不是类；Laravel 在MailServiceProvider中已绑定Illuminate\Contracts\Mail\Mailer→Illuminate\Mail\Mailer - 如果自己写新邮件驱动（比如对接 SendGrid API），只需实现该接口，并在
AppServiceProvider::register()中重绑定：$this->app->bind(Mailer::class, SendGridMailer::class); - 别在构造函数里写
new Mailer(...)—— 这会让依赖脱离容器控制，契约失效
自定义 Contract 接口时，哪些地方最容易出错
自己定义契约不是加个 interface 就完事。常见疏漏：
- 没在
AppServiceProvider或专用服务提供者中调用bind()或singleton()，导致容器找不到实现类，抛出Target [YourContract] is not instantiable - 接口方法签名和实际实现类不一致（比如少一个参数、返回类型不同），PHP 7.4+ 会报
Declaration must be compatible - 把 Contract 放在
app/Contracts/下却忘了在composer.json的"autoload": {"psr-4": {...}}中注册命名空间，导致类找不到 - 在接口里定义了静态方法或属性 —— PHP 接口不允许，会直接报错
建议最小验证步骤：
php artisan tinker >>> app()->make(\App\Contracts\PaymentGateway::class); // 不报错且返回实例，说明绑定成功
Contract 和 Facade、辅助函数之间的关系要不要理清
要，而且得主动切断混淆：
-
Mail::to(...)->send(...)是 Facade，本质是静态代理，底层仍走容器 + Contract；但它隐藏了依赖关系，不利于单元测试和阅读 -
mail()辅助函数是全局函数，内部也是调用容器解析Mailer接口，但完全丢失类型提示和 IDE 支持 - Contract 是唯一能让你在类型系统里明确表达“我需要这个能力”的方式；Facade 和辅助函数适合快速原型或 Blade 模板里简单调用
一个控制器里混用三者，短期省事，长期会让别人（包括未来的你）搞不清这个类到底依赖什么、能不能被替换、mock 时该 stub 哪个点。
Contract 的价值不在“用了就高大上”，而在每次你写 public function __construct(SomeContract $x) 的时候，都在给代码加一层语义锁：这个类只认能力，不认实现。一旦哪天要切数据库、换缓存、接入新支付网关，改的只是绑定，不是业务逻辑本身。
