罗罗编程学习记录
本页内容 展开查看

06.5.4.3 Facade 与契约 Contracts

所属:全栈开发面试题库 / 06 后端框架与工程实践 / 06.5 PHP 后端 / 06.5.4 Laravel

覆盖范围

  • Facade 基类、getFacadeAccessor 与静态转发
  • 契约接口清单、先契约后实现
  • 测试替换、fake、实时 Facade 与隔离边界

入门概念见 06.5.1.1 框架架构与生命周期 中的 Facade 与契约基础题;本页聚焦机制与工程取舍。

06.5.4.3-001 Facade 基类如何通过 getFacadeAccessor 定位容器绑定?

一句话结论

每个 Facade 继承 Illuminate\Support\Facades\Facade,重写 getFacadeAccessor() 返回容器绑定标识(别名或抽象名);静态调用时基类用该标识从容器解析出底层实例再转发方法。

概念解释

Facade 自身不持有业务逻辑,只是静态代理层。accessor 返回的字符串对应容器中的绑定键,例如 Cache Facade 返回 cache,解析到缓存管理器实例。

原理流程

  1. 静态方法调用进入 Facade 基类 __callStatic。
  2. 调用子类 getFacadeAccessor() 取绑定标识。
  3. 容器按标识解析底层实例。
  4. 在实例上调用同名方法并返回结果。

代码或图示

use Illuminate\Support\Facades\Facade;

class ReportFacade extends Facade
{
    protected static function getFacadeAccessor(): string
    {
        return 'report.exporter';
    }
}

常见误区

  • 以为 Facade 类里写了静态业务方法:业务逻辑全在底层实例,Facade 只做转发。
  • accessor 返回类名但容器未绑定:解析时抛绑定异常,静态调用失败。

追问

  • accessor 返回的标识在哪里注册?答:在服务提供者 register 中绑定对应抽象/别名,详见 06.5.4.1 服务容器与绑定解析。
  • 同一 accessor 能否指向单例实例?答:可以,底层绑定类型决定复用方式,Facade 不改变实例生命周期。

06.5.4.3-002 __callStatic 如何把静态调用转发到底层实例?

一句话结论

Facade 基类用 __callStatic 魔术方法拦截未定义的静态调用,解析底层实例后以普通方法调用形式转发参数与返回值;这是 Facade “静态语法、动态实例”的实现核心。

概念解释

PHP 静态调用类中不存在的方法时触发 __callStatic。基类在该魔术方法内完成容器解析、方法转发,因此 Facade 子类不需要为每个业务方法写静态包装。

原理流程

  1. 调用 ReportFacade::generate($data),类中无 generate 静态方法。
  2. 触发基类 __callStatic('generate', $args)。
  3. 解析底层实例,调用 $instance->generate(...$args)。
  4. 返回实例方法的返回值。

代码或图示

// 基类转发逻辑等价示意(源码以 Illuminate\Support\Facades\Facade 为准)
public static function __callStatic(string $method, array $args)
{
    $instance = static::getFacadeRoot();
    return $instance->$method(...$args);
}

常见误区

  • 以为转发发生在编译期:实际是运行期魔术方法转发,静态分析看不到底层方法签名。
  • 给 Facade 加静态属性缓存状态:状态属于底层实例,Facade 类静态属性在请求间行为不确定。

追问

  • 实例方法不存在会怎样?答:转发后由 PHP 抛“调用未定义方法”错误,错误指向底层实例类而非 Facade。
  • 转发支持引用参数吗?答:魔术方法转发按参数列表传递;引用传参场景需核对当前版本基类实现。

06.5.4.3-003 Laravel 主要契约(Contracts)有哪些?对应 Facade 是什么关系?

一句话结论

契约位于 Illuminate\Contracts\ 命名空间,是一组接口定义;核心服务都有对应契约,Facade 是容器解析到该服务后的静态外观,二者通过容器绑定关联。

概念解释

常见契约与 Facade 对照(具体接口名以当前版本源码为准):

能力 契约接口 常用 Facade
缓存 Contracts\Cache\Factory / Repository Cache
队列 Contracts\Queue\Factory Queue
认证 Contracts\Auth\Guard Auth
事件 Contracts\Events\Dispatcher Event
广播 Contracts\Broadcasting\Broadcaster Broadcast
文件系统 Contracts\Filesystem\Factory Storage
哈希 Contracts\Hashing\Hasher Hash
日志 Contracts\Logging\Log Log
校验 Contracts\Validation\Factory Validator
加密 Contracts\Encryption\Encrypter Crypt

原理流程

  1. 框架服务提供者把契约接口绑定到具体实现。
  2. Facade accessor 返回服务别名,解析到同一实现。
  3. 业务代码可注入契约接口,或经 Facade 静态调用。

代码或图示

use Illuminate\Contracts\Cache\Repository as CacheRepository;

class ReportReader
{
    public function __construct(private readonly CacheRepository $cache) {}
}

常见误区

  • 把 Facade 类当成契约类型提示:Facade 是外观不是接口,类型约束应写 Contracts 接口。
  • 以为契约必须自己实现:框架核心契约已有默认实现,自定义包可替换绑定。

追问

  • 契约接口在哪里查看?答:Illuminate\Contracts 命名空间下按能力分目录,可在框架源码或官方文档 Contracts 章节核对清单。
  • 同一能力有 Factory 与 Repository 两个契约怎么区分?答:Factory 负责按名称创建/获取驱动器,Repository 是具体缓存操作接口;注入时按所需方法选择。

06.5.4.3-004 为什么要先定义契约接口再绑定实现?

一句话结论

先契约后实现让业务依赖稳定抽象,实现可替换、可测试、可多版本演进;接口隔离消费方与装配细节,避免代码直接耦合具体类。

概念解释

契约定义“做什么”,实现决定“怎么做”。消费方只引用接口,更换短信/邮件/推送渠道时不动业务代码;测试时绑定 mock 实现即可替身。

原理流程

  1. 提炼业务所需能力,定义接口方法签名。
  2. 编写一个或多个实现类。
  3. 服务提供者把接口绑定到实现。
  4. 消费方类型提示接口,容器注入实现。

代码或图示

interface NotificationSender
{
    public function send(User $user, string $message): void;
}

class MailSender implements NotificationSender { /* ... */ }

$this->app->bind(NotificationSender::class, MailSender::class);

常见误区

  • 接口只有一个实现就不抽接口:短期省事,后续替换与测试时仍要回头解耦。
  • 接口设计暴露实现细节(具体 DTO、框架类型):契约应保持业务语义,减少对框架类型的依赖。

追问

  • 契约变更如何影响实现?答:接口加方法后所有实现需补齐;破坏性调整应新版本接口并存过渡。
  • 契约与 Facade 谁先写?答:先定义契约与实现,再按需提供 Facade;Facade 不参与接口契约定义。

06.5.4.3-005 Facade swap() 如何在测试中替换底层实例?

一句话结论

Facade::swap($instance) 把给定实例直接写入容器 instances 表并覆盖 Facade 根实例,测试中注入 mock/桩对象后,所有走该 Facade 的静态调用都落到替身。

概念解释

swap 是测试隔离入口:它绕过原绑定工厂,把成品实例登记进容器。测试结束通常需要清除替换,避免 mock 泄漏到其他用例。

原理流程

  1. 测试创建 mock 实现(Mockery/PHPUnit 替身)。
  2. 调用对应 Facade swap($mock)。
  3. 被测代码经 Facade 调用时解析到 mock。
  4. 断言 mock 收到的调用;用例结束清缓存。

代码或图示

use Illuminate\Support\Facades\Queue;

Queue::swap($mock = Mockery::mock(QueueFactory::class));
$mock->shouldReceive('push')->once();

// 被测代码内部 Queue::push(...) 落到 mock

常见误区

  • swap 后不清理:mock 残留在容器单例表,后续用例拿到假实例。
  • swap 的对象未实现底层契约:转发调用时方法不存在报错,替身类型应匹配契约接口。

追问

  • swap 与 instance 绑定区别?答:二者都是登记成品实例;swap 是 Facade 提供的便捷入口,内部等价于容器实例绑定,测试场景语义更直接。
  • 不 swap 如何测 Facade 调用?答:重构为构造注入契约接口,直接传 mock,避免静态依赖。

06.5.4.3-006 clearResolvedInstance / clearResolvedInstances 何时使用?

一句话结论

clearResolvedInstance($name) 清除单个 Facade 对应的已解析实例缓存,clearResolvedInstances() 清空全部;测试隔离、强制重新解析绑定、替换实现后刷新缓存时使用。

概念解释

Facade 底层实例被容器缓存后,重新 bind 不会自动替换已缓存实例;需要先清除解析缓存,下次静态调用才走新绑定。

原理流程

  1. 某 Facade 底层实例已解析并缓存。
  2. 调用清除方法删除对应实例记录。
  3. 下次静态调用重新解析当前绑定规则。
  4. 全量清理用于测试用例间重置容器状态。

代码或图示

use Illuminate\Support\Facades\Cache;

Cache::clearResolvedInstance('cache');
// 或全量
Facade::clearResolvedInstances();

常见误区

  • 重新绑定后不清理缓存:旧实例继续被返回,新绑定看似“不生效”。
  • 在生产请求中频繁全量清理:销毁核心单例缓存,引发重复构造与副作用。

追问

  • 清除方法与容器 forgetInstance 关系?答:Facade 清除方法操作的是 Facade 根实例与容器实例缓存,底层等价于容器实例清理;具体实现以 Facade 源码为准。
  • 单例绑定清除后会重建吗?答:下次解析按绑定规则重新构造并再次缓存。

06.5.4.3-007 实时 Facade(real-time facade)如何把普通类转成 Facade?

一句话结论

实时 Facade 通过给类名加 Facades\ 命名空间前缀,把普通服务类当作静态外观调用;框架在运行期解析该前缀映射到真实类,无需手写 Facade 子类。

概念解释

实时 Facade 是语法糖:Facades\App\Services\ReportService::method() 等价于容器解析 ReportService 后转发方法。适合临时减少注入样板,长期仍建议构造注入。

原理流程

  1. 真实类位于 App\Services\ReportService。
  2. 调用时使用 Facades\App\Services\ReportService 前缀。
  3. 框架解析前缀,从容器取真实服务实例。
  4. 静态调用转发到实例方法。

代码或图示

// 普通服务类
class ReportService
{
    public function generate(string $id): string { /* ... */ }
}

// 实时 Facade 调用(前缀形式以当前版本文档为准)
// Facades\ReportService::generate('r1')

常见误区

  • 把实时 Facade 当长期架构:静态耦合依旧存在,测试隔离与依赖可见性差。
  • 命名空间前缀写错导致类未找到:前缀映射规则需对照当前版本文档核对。

追问

  • 实时 Facade 与手写 Facade 底层差异?答:转发机制相同,区别是实时 Facade 不要求子类声明 accessor,映射由框架按类名完成。
  • 实时 Facade 能 swap 吗?答:测试仍可通过容器替换底层服务;具体静态替换入口以版本实现为准。

06.5.4.3-008 Facade 与构造函数注入各自的适用场景是什么?

一句话结论

横切、低频、无状态的能力(日志、配置、缓存读取)可用 Facade 简化书写;业务服务、需替换测试、依赖明确的类应构造注入契约接口,保持依赖可见与可测。

概念解释

Facade 优势是语法简短,代价是隐藏依赖来源;构造注入把依赖写进签名,IDE 可追踪、测试可替身。分层越深、业务越核心,越应使用注入。

原理流程

  1. 判断依赖性质:横切工具还是业务协作服务。
  2. 业务服务:构造注入契约接口。
  3. 横切能力:代码内可使用 Facade 或注入对应契约。
  4. 评审时检查类中 Facade 调用是否过多。

代码或图示

// 推荐:业务依赖显式注入
class CheckoutService
{
    public function __construct(
        private readonly PaymentGateway $gateway,
        private readonly NotificationSender $notifier,
    ) {}
}

常见误区

  • 在领域服务里大量 Facade 调用:类的真实依赖无法从签名看出,单元测试需全局替身。
  • 为“统一风格”把所有 Facade 改注入:日志等横切场景 Facade 可读性更好,按场景取舍。

追问

  • 控制器中用 Facade 可以吗?答:控制器层使用 Facade 较常见,但核心业务逻辑应下沉到可注入的服务类。
  • Facade 调用能否被静态分析识别?答:部分 IDE 可解析转发,但方法签名与类型推断弱于直接注入。

06.5.4.3-009 Facade 的 fake() 方法如何做测试替身?

一句话结论

部分内置 Facade 提供 fake() 方法,用内存桩实现替换底层服务(如队列、邮件、广播),测试中断言推送/发送行为而不触达真实外部系统。

概念解释

fake() 是框架预置的测试替身工厂,替代手工 mock:调用后底层实例换成桩实现,提供 assertPushed、assertSent 等断言方法。可用范围以各 Facade 文档为准。

原理流程

  1. 测试 setUp 或用例中调用 Queue::fake() / Mail::fake() 等。
  2. 容器底层实例被桩实现替换。
  3. 执行被测代码触发静态调用。
  4. 调用桩提供的断言方法核对调用参数与次数。

代码或图示

use Illuminate\Support\Facades\Queue;

Queue::fake();
dispatch_report_job();

Queue::assertPushed(ReportJob::class, fn ($job) => $job->id === 10);

常见误区

  • 对没有 fake 的 Facade 强行调用 fake():方法不存在,需改用 swap 或 mock。
  • fake 后忘记在多用例间清理:桩实例可能残留,影响后续真实行为测试。

追问

  • fake 与 mock 怎么选?答:内置桩覆盖典型断言时优先 fake,写法简单;复杂交互断言用 Mockery 自定义 mock。
  • fake 替换的是驱动器还是服务?答:替换为内存桩实现,不启动真实队列/邮件传输;具体替换层级以源码为准。

06.5.4.3-010 契约绑定关系在哪个提供者中建立?

一句话结论

框架核心契约绑定由内置服务提供者在引导阶段注册;自定义契约绑定写在应用自身或包的服务提供者 register 方法中,消费方按接口解析。

概念解释

契约与实现的映射属于装配规则,统一在提供者登记。框架默认绑定保证 app(契约接口) 可取到默认实现;替换实现只改绑定处。

原理流程

  1. 内置提供者注册核心契约 → 默认实现映射。
  2. 应用提供者为自定义契约补绑定。
  3. 容器解析接口名时查绑定表。
  4. 未绑定的接口无法自动实例化,抛解析异常。

代码或图示

// App\Providers\AppServiceProvider::register
$this->app->bind(NotificationSender::class, MailSender::class);
$this->app->bind(ReportRepository::class, DbReportRepository::class);

常见误区

  • 在控制器里临时绑定契约:装配逻辑散落,包复用与测试都困难。
  • 只定义接口不绑定:注入接口时容器无法解析。

追问

  • 框架默认绑定在哪里查看?答:内置提供者源码中 bind/singleton 调用,按契约名检索即可定位。
  • 如何全局替换某核心契约实现?答:在应用提供者中重新绑定该接口;单例缓存需注意先清实例或在引导早期覆盖。

06.5.4.3-011 Facade 根命名空间与别名自动加载如何工作?

一句话结论

内置 Facade 类位于 Illuminate\Support\Facades,composer 自动加载按类名映射文件;配置中的别名(aliases)让 Facade 可在全局命名空间直接使用短类名,无需逐个 use。

概念解释

Facade 类本身遵循 PSR-4 自动加载;别名注册把短名指向 Facade 类,PHP 解析未导入类名时经别名映射找到真实类。包自定义 Facade 别名通过自动发现或配置登记。

原理流程

  1. Composer 自动加载按命名空间定位 Facade 类文件。
  2. 框架别名表把短名映射到 Facade 类全名。
  3. 代码中使用短名时经别名解析到类。
  4. 静态调用进入基类转发流程。

代码或图示

// 代码中直接使用短名(别名映射以框架配置为准)
use Illuminate\Support\Facades\Cache;
Cache::put('k', 'v', 60);

常见误区

  • 以为 Facade 别名是容器绑定:别名分两层,类别名解决类名解析,容器别名解决服务标识解析,二者不要混淆。
  • 自定义 Facade 不登记别名:全局短名不可用,需写完整类名或手动 use。

追问

  • 别名缓存失效如何刷新?答:与包发现/配置缓存一起重建;别名清单编译进启动缓存,改动后需刷新。
  • 如何查看某短名对应的真实类?答:在框架别名配置或自动发现缓存中检索短名映射。

06.5.4.3-012 调用不存在的 Facade 方法会发生什么?

一句话结论

转发到底层实例后,实例上无该方法会触发 PHP “调用未定义方法”错误;若底层实例解析失败,则先抛容器绑定异常,二者需根据异常类型区分。

概念解释

Facade 基类不做方法存在性校验,方法是否存在完全取决于底层实例。排查时先确认实例是否解析成功,再核对实例类的方法签名。

原理流程

  1. 静态调用进入 __callStatic。
  2. 解析底层实例;绑定缺失则抛 BindingResolutionException。
  3. 实例存在但方法缺失,抛 BadMethodCallException 或未定义方法错误。
  4. 异常消息包含实例类名与方法名。

代码或图示

try {
    Cache::nonExistentMethod();
} catch (Throwable $e) {
    report($e::class . ': ' . $e->getMessage());
}

常见误区

  • 把方法不存在误判成 Facade 配置错误:先打印底层实例类名核对方法清单。
  • 接口存在默认实现但方法签名不匹配:参数类型/数量不符会触发类型错误而非方法缺失。

追问

  • 如何让 Facade 提示可用方法?答:部分 Facade 文档/IDE 插件提供方法补全;准确签名以底层契约接口为准。
  • 转发方法签名不一致怎么排查?答:对比契约接口方法定义与实现类,检查参数顺序、类型与返回值声明。

06.5.4.3-013 契约接口方法签名变更如何影响实现与 Facade?

一句话结论

接口加/改方法后,所有实现类必须同步补齐或调整签名,否则违反接口契约;Facade 转发不校验签名,错误会在运行期调用暴露,因此应靠类型声明与测试提前发现。

概念解释

契约是消费方与实现方的约定。破坏性签名变更需要新版本接口并存;PHP 不会在类定义时强制检查参数兼容(严格类型外),运行期类型不匹配才报错。

原理流程

  1. 修改契约接口方法签名。
  2. 编译器/静态检查提示实现类签名不一致。
  3. 同步更新各实现与测试替身。
  4. Facade 调用方无需改动转发层,仅受业务参数影响。

代码或图示

interface Sender
{
    public function send(User $user, string $message, ?string $channel = null): void;
}

class MailSender implements Sender
{
    public function send(User $user, string $message, ?string $channel = null): void { /* ... */ }
}

常见误区

  • 只改接口不改实现:类仍可加载,但调用缺方法/参数不符时报错。
  • 接口方法返回类型缩小或扩大:需遵守 Liskov 替换原则,返回类型兼容实现方可替换。

追问

  • 如何做兼容式接口演进?答:新方法给默认实现或拆分新接口,旧实现逐步迁移;避免一次性破坏全部实现。
  • Facade 需要随接口改吗?答:不需要,Facade 只转发调用;变更集中在契约与实现。

06.5.4.3-014 Facade 底层实例每次解析还是复用?

一句话结论

复用与否取决于底层绑定类型:singleton/instance 绑定复用缓存实例,bind 绑定每次解析新建;Facade 只是转发层,不自己决定实例生命周期。

概念解释

首次静态调用解析实例后,容器按绑定类型决定是否缓存。后续调用读取缓存或重新构造,行为与直接 app() 解析一致。

原理流程

  1. 首次调用解析底层实例。
  2. 绑定为共享类型则写入 instances 表缓存。
  3. 后续静态调用取缓存实例。
  4. 非共享绑定每次走工厂闭包新建。

代码或图示

$this->app->singleton(ReportService::class);   // 复用
$this->app->bind(StatelessHelper::class);     // 每次新建

常见误区

  • 以为所有 Facade 底层都是单例:核心服务多为共享绑定,但具体以绑定注册为准。
  • 在 Facade 静态调用间依赖实例状态:非共享绑定每次新建,状态不保留。

追问

  • 如何核对某 Facade 底层是否共享?答:解析实例后调用容器 isShared 判断,或查看提供者绑定类型。
  • 常驻模式下共享实例注意什么?答:请求级状态不能存进共享实例,详见 06.5.4.1 服务容器与绑定解析 相关题。

06.5.4.3-015 如何为自定义服务编写配套 Facade?

一句话结论

新建继承 Facade 的子类,实现 getFacadeAccessor() 返回容器绑定标识;在提供者中绑定该标识对应的服务,必要时在别名清单登记短名即可使用。

概念解释

自定义 Facade 三步:定 accessor、绑服务、(可选)登记别名。Facade 类不写业务方法,方法转发由基类完成。

原理流程

  1. 编写服务类并在容器绑定。
  2. 编写 Facade 子类,accessor 返回绑定标识。
  3. 需要短名时登记别名。
  4. 代码中经 Facade 静态调用服务方法。

代码或图示

// 提供者绑定
$this->app->bind('report.exporter', CsvExporter::class);

// Facade 子类
class Report extends Facade
{
    protected static function getFacadeAccessor(): string
    {
        return 'report.exporter';
    }
}

常见误区

  • accessor 返回的标识与绑定标识不一致:解析不到服务。
  • Facade 子类里重复定义业务静态方法:绕过转发,实例替换时静态方法不生效。

追问

  • 自定义 Facade 需要契约接口吗?答:Facade 不强制,但服务本身建议依赖契约;Facade 只是外观层。
  • Facade 文件放在哪?答:通常置于 App\Facades 命名空间,遵循项目自动加载约定。

06.5.4.3-016 Facade 与静态类、单例静态方法的本质区别是什么?

一句话结论

Facade 是“静态语法代理动态实例”,底层对象由容器创建可替换;静态类/单例静态方法把逻辑与类本身绑定,实例化与依赖不可控,也难以替身。

概念解释

三者写法相似但耦合层级不同:Facade 转发到容器实例,可 swap、可换绑定;纯静态类无实例概念;静态单例方法全局共享一份状态。

原理流程

  1. Facade:静态调用 → 容器实例 → 转发方法。
  2. 静态类:方法直接定义在类上,无实例注入点。
  3. 静态单例:类内部持有静态实例,外部无法替换依赖。

代码或图示

// Facade:底层可替换
Report::generate($id);

// 纯静态类:依赖硬编码
class StaticReport
{
    public static function generate(string $id): string { /* ... */ }
}

常见误区

  • 把 Facade 当静态类理解:Facade 底层仍是动态对象,具备实例状态与替换空间。
  • 用静态单例模拟 Facade:失去容器装配与测试隔离能力。

追问

  • 静态类有适用场景吗?答:纯函数工具(无依赖、无状态)适合静态方法;有协作依赖的服务应实例化注入。
  • 单例静态方法如何改造?答:抽取实例方法与契约,改容器绑定,保留静态入口仅作兼容门面。

06.5.4.3-017 测试中不 swap 时如何隔离 Facade 状态?

一句话结论

不使用 swap 时,可在测试间清除已解析实例缓存、隔离配置与缓存驱动,或把被测代码重构为注入契约接口;最彻底的隔离是消除对 Facade 的静态依赖。

概念解释

Facade 状态隔离难点在容器缓存与外部驱动器(缓存、队列、文件)。测试可通过内存驱动、缓存清除、实例清理三层处理;代码层面注入契约则天然可替身。

原理流程

  1. 每个用例后清除 Facade 解析实例。
  2. 配置测试环境使用内存/本地驱动器。
  3. 必要时重置缓存与临时目录。
  4. 核心业务重构为构造注入,测试直接传 mock。

代码或图示

protected function tearDown(): void
{
    Facade::clearResolvedInstances();
    parent::tearDown();
}

常见误区

  • 多个用例共享真实缓存/队列:前一用例数据影响后一用例断言。
  • 只清 Facade 不清底层驱动状态:缓存键残留仍会干扰结果。

追问

  • 数据库状态如何隔离?答:用事务回滚或迁移刷新机制,与 Facade 隔离分属不同层;具体测试基类机制以项目测试配置为准。
  • 注入契约后还需要 Facade 清理吗?答:被测类不经过 Facade,容器替身由测试直接传入,无需清理静态缓存。

06.5.4.3-018 契约在队列任务与广播事件序列化中起什么作用?

一句话结论

队列任务与广播事件序列化的是数据与类名,执行端按类名重新实例化;契约保证消费端调用的方法签名一致,避免序列化后对象行为与预期不符。

概念解释

入队对象被序列化,取出后由容器/反序列化重建。依赖契约的服务在执行时解析实现;事件载荷应只含可序列化数据(ID、标量、数组),不携带不可序列化资源。

原理流程

  1. 任务/事件类定义属性与契约方法。
  2. 序列化数据入队或广播。
  3. 消费端反序列化重建对象,经容器解析协作服务。
  4. 按契约方法签名执行业务逻辑。

代码或图示

class SendReportJob implements ShouldQueue
{
    public function __construct(public readonly int $reportId) {}

    public function handle(NotificationSender $sender): void
    {
        // 执行端按契约注入发送器
    }
}

常见误区

  • 任务构造函数注入服务实例:服务不可序列化,入队失败或取出后状态丢失。
  • 事件载荷携带 Eloquent 模型整对象:序列化体积大且可能过期,优先传 ID 再查询。

追问

  • 模型如何安全入队?答:实现可队列化模型约定(如 SerializesModels 特征),序列化主键与类名,取出时重新查询;具体机制以版本源码为准。
  • 契约方法在消费端找不到实现怎么办?答:消费端应用需注册对应绑定,否则执行时抛解析异常。

06.5.4.3-019 哪些能力建议走契约而非直接依赖 Facade?

一句话结论

业务协作服务、多实现可替换渠道、核心领域逻辑应依赖契约接口;日志、配置、读缓存等横切工具可直接用 Facade,但服务层内部仍优先注入契约。

概念解释

判断标准:是否有多种实现、是否需要测试替身、是否属于业务核心。满足任一项即走契约;纯工具型、无状态、全局一致的能力可保留 Facade 调用。

原理流程

  1. 列出类的协作依赖。
  2. 业务/可替换依赖标注契约接口。
  3. 横切工具保留 Facade 或注入对应契约。
  4. 评审检查服务层签名中的接口覆盖率。

代码或图示

// 服务层:依赖契约
class OrderProcessor
{
    public function __construct(
        private readonly PaymentGateway $gateway,
        private readonly InventoryRepository $inventory,
    ) {}
}

常见误区

  • 把所有依赖都包成接口:纯数据转换、无替换必要的内部类不必过度抽象。
  • 契约接口与实现一一对应却不写注入:接口价值在替换与测试,需配合容器使用。

追问

  • 框架核心服务也要注入契约吗?答:服务层调用核心能力时注入对应 Contracts 更利于测试;控制器/脚本中使用 Facade 可接受。
  • 接口过多如何治理?答:按业务边界划分模块,契约随模块内聚,跨模块调用才暴露公共接口。

06.5.4.3-020 Facade 解析异常(容器无绑定)如何排查?

一句话结论

解析异常说明 accessor 返回的标识在容器 bindings/instances 中不存在;排查顺序为:核对 accessor 标识 → 确认提供者已注册并执行 register → 检查启动缓存是否旧清单 → 用容器 bound 验证。

概念解释

常见原因:提供者未登记、延迟提供者未触发、绑定标识拼写不一致、包发现缓存过期、别名未注册。异常通常为 BindingResolutionException 或容器未找到服务错误。

原理流程

  1. 读取异常消息中的抽象标识。
  2. 在提供者源码检索该标识的 bind/singleton 注册。
  3. 确认提供者已加入应用清单或自动发现缓存。
  4. 清除启动缓存后复现,用 app()->bound($name) 验证。

代码或图示

if (app()->bound('report.exporter')) {
    $service = app('report.exporter');
} else {
    report('绑定缺失:report.exporter');
}

常见误区

  • 只检查 Facade 子类:问题多在容器绑定与提供者注册,不在 Facade 转发层。
  • 缓存未刷新就反复改代码:旧清单导致新绑定不出现,先清缓存再判断。

追问

  • 如何列出 Facade accessor 对应绑定?答:在 Facade 子类读取 getFacadeAccessor 返回值,再到容器绑定清单检索;调试时可临时调用根实例方法打印类名。
  • 延迟提供者导致绑定缺失怎么处理?答:确认目标抽象已列入 provides(),触发首次解析后再验证;不应延迟的服务改为常规提供者。