Laravel如何使用Contracts契约_Laravel 接口注入开发模式【核心】

契约是laravel用于解耦实现、支持多后端切换和可测试性的官方接口集合；应在业务类需屏蔽具体实现、单元测试需Mock、包开发需扩展点时注入Contract而非Facade或具体类。

Contracts 契约不是“必须用”的抽象层，而是当你需要解耦具体实现、支持多版本驱动（比如换缓存/队列/日志后端）、或写可测试代码时，Laravel 提供的官方接口集合。直接依赖 IlluminateSupportFacadesCache 看似简单，但一旦要 mock 或切换底层（如从 redis 换成 DynamoDB 缓存适配器），就会卡住。

什么时候该绑定 Contract 而不是 Facade 或具体类？

核心判断点：你写的类是否应该“不知道”具体用的是哪个实现？

• 业务服务类（如 OrderService）需要读写缓存 → 注入 IlluminateContractsCacheRepository，而不是 Cache::class 或 redisStore
• 通知类要发短信 → 依赖 IlluminateContractsNotificationsDispatcher，而非硬编码 TwilioChannel
• 单元测试中需要替换行为 → 只有 Contract 才能被 Mockery::mock() 或 app()->instance() 安全替换
• 包开发者提供扩展点 → 用 Contract 声明依赖，让用户 bind 自己的实现，不强求 Laravel 默认组件

如何正确注入 Contract 并绑定自定义实现？

Laravel 在容器启动时已自动 bind 大部分 Contract 到默认实现（如 IlluminateContractsCacheRepository → IlluminateCacheRepository）。你只需在构造函数或方法参数中声明类型提示即可使用。

若需替换，必须在 appServiceProvider::register() 中完成：

use IlluminateContractsCacheRepository as CacheContract; use AppCacheMyCustomCache;  public function register() {     $this->app->singleton(CacheContract::class, function ($app) {         return new MyCustomCache($app['cache.store']);     }); }

• 必须用 singleton()，否则每次解析都新建实例，可能破坏缓存一致性
• 不要在 boot() 中 bind，此时容器已冻结，会报 BindingResolutionException
• 自定义实现类必须实现 Contract 全部方法，哪怕只用其中几个 —— 这是契约的意义，不是“按需实现”

常见错误：Contract 注入失败或报错

最常遇到的不是语法问题，而是容器找不到绑定：

• 用了 IlluminateContractshttpKernel 却没意识到它只在 HTTP 生命周期中可用，命令行调用会报 Target [IlluminateContractsHttpKernel] is not instantiable
• 把 IlluminateContractsQueueQueue 当作“发任务”接口注入，其实应使用 IlluminateContractsQueueFactory 或直接 dispatch() 辅助函数
• 在模型的 boot() 静态方法里尝试 app(MyContract::class) —— 此时服务提供者尚未注册，Contract 还未 bind
• Contract 名称拼错，比如 IlluminateContractsAuthGuard 已在 Laravel 5.2+ 废弃，应改用 IlluminateContractsAuthAuthenticatable 或 Auth::user()

Contract 的价值不在“写得多”，而在“换得稳”。很多人过早抽象，结果绑了一堆空接口却从未替换过实现。真正关键的是：当第一次需要 mock 一个外部依赖（比如支付网关回调验证）时，你有没有提前把它声明为 Contract？这才是契约存在的唯一理由。