介绍

Laravel 的契约是一组由框架提供,定义了核心服务的 interface 集合。比如, Illuminate\Contracts\Queue\Queue 契约定义了队列任务所需方法,而 Illuminate\Contracts\Mail\Mailer 契约定义了发送邮件所需方法。

每个契约都拥有相应的框架提供的实现。比如,Laravel 提供了多种驱动的队列实现,并且使用 SwiftMailer 实现了邮件契约。

所有 Laravel 契约都在 它们各自的 GitHub 仓库。这为所有可用的契约以及扩展包开发者们可能用到的单个、解耦的包,提供了一个快速参考入口。

契约 Vs. Facades

Laravel 的 Facades 和辅助函数提供了一种简便方式来使用 Laravel 服务而无需用到类型提示,也可在服务容器外部解析契约。多数情况下,每个 Facade 都有一个等效的契约。

和 Facades (不须要在你类中的构造函数去引用依赖)不同的是,契约允许你给自己的类定义明确的依赖。一些开发者更喜欢依赖被明确地定义出来,所以更倾向于使用契约,而其他开发者则享受于 Facades 带来的方便。

{tip} 在大多数应用中,无论你更喜欢 Facades 还是契约,都是没问题的。然而如果你在搭建扩展包,那你应该强烈考虑使用契约,因为他们更便于在包的上下文中做测试。

何时使用契约

综上所述,使用契约还是 Facades 很大程度上取决于你个人或者团队的喜好。契约和 Facades 均可以用来构建健壮的、充分测试过的 Laravel 应用。只要你保持类的职责单一,你会发现使用契约和 Facades 的实际差别是非常小的。

然而,你以也许仍有许多关于契约的问题。比方说,为啥都用 interface ?用 interface 不是更复杂吗?让我们在接下来的内容(「低耦合」与「简明性」)中,提炼出原因。

低耦合

首先,让我们来看一些缓存实现的高耦合代码。假设有下面代码:

  1. <?php
  2. namespace App\Orders;
  3. class Repository
  4. {
  5. /**
  6. * 缓存实例.
  7. */
  8. protected $cache;
  9. /**
  10. * 创建一个新的仓库实例.
  11. *
  12. * @param \SomePackage\Cache\Memcached $cache
  13. * @return void
  14. */
  15. public function __construct(\SomePackage\Cache\Memcached $cache)
  16. {
  17. $this->cache = $cache;
  18. }
  19. /**
  20. * 根据 ID 获取订单.
  21. *
  22. * @param int $id
  23. * @return Order
  24. */
  25. public function find($id)
  26. {
  27. if ($this->cache->has($id)) {
  28. //
  29. }
  30. }
  31. }

在这个类中,代码与给定的缓存实现形成高度耦合。它的高度耦合是因为我们依赖了一个扩展包中具体的缓存类。如果该扩展包的 API 变了,那么我们的代码也将必须做出修改。

同理,如果我们想要将底层的缓存技术 ( Memcached ) 替换成另一种缓存技术 ( Redis ),我们得再次修改我们的代码库。我们的代码库并不需要知道是谁提供的数据或者数据是怎么提供的。

我们可以通过依赖一个简单的与扩展包无关的 interface 来改进我们的代码,来替代之前的实现方式:

  1. <?php
  2. namespace App\Orders;
  3. use Illuminate\Contracts\Cache\Repository as Cache;
  4. class Repository
  5. {
  6. /**
  7. * 缓存实例.
  8. */
  9. protected $cache;
  10. /**
  11. * 创建一个新的仓库实例.
  12. *
  13. * @param Cache $cache
  14. * @return void
  15. */
  16. public function __construct(Cache $cache)
  17. {
  18. $this->cache = $cache;
  19. }
  20. }

现在的代码不与任何特定的扩展包耦合了,甚至与 Laravel 都是无关的。由于契约扩展包不包含任何实现和依赖,你可以轻松地为给定的契约编写替代实现的代码,从而可以在不修改任何缓存代码的情况下替换缓存的实现。

简单

当 Laravel 的所有服务都在简单的接口中整齐定义时,很容易通过给定的服务确定提供的功能。契约充当框架功能的简洁性文档

此外,当你依赖简单的接口时,你的代码更容易理解和维护。你可以参考一个简单,干净的接口,而不是在大型复杂的的类中跟踪哪些方法是可用的。

如何使用契约

因此,你如何去实现一个契约呢?它实际上很简单。

Laravel 中的许多类型的类通过 服务容器 来解析,包括控制器,事件侦听,中间件,队列作业,甚至路由闭包等。因此,要获取一个合同的实现,你只需在解析的类的构造方法中键入『类型提示』的接口。

例如,看看这个事件侦听器:

  1. <?php
  2. namespace App\Listeners;
  3. use App\User;
  4. use App\Events\OrderWasPlaced;
  5. use Illuminate\Contracts\Redis\Factory;
  6. class CacheOrderInformation
  7. {
  8. /**
  9. * Redis 工厂实现。
  10. */
  11. protected $redis;
  12. /**
  13. * 创建一个新的事件处理器实例。
  14. *
  15. * @param Factory $redis
  16. * @return void
  17. */
  18. public function __construct(Factory $redis)
  19. {
  20. $this->redis = $redis;
  21. }
  22. /**
  23. * 处理事件。
  24. *
  25. * @param OrderWasPlaced $event
  26. * @return void
  27. */
  28. public function handle(OrderWasPlaced $event)
  29. {
  30. //
  31. }
  32. }

当事件侦听器被解析时,服务容器将读取类的构造方法上的类型提示,并注入合适的值。要了解更多有关在服务容器中注册的内容,查看 服务容器文档

合约参考

此表提供了所有 Laravel 契约及其等效 facades 的一个快速参考:

Contract References Facade
Illuminate\Contracts\Auth\Access\Authorizable
Illuminate\Contracts\Auth\Access\Gate Gate
Illuminate\Contracts\Auth\Authenticatable
Illuminate\Contracts\Auth\CanResetPassword
Illuminate\Contracts\Auth\Factory Auth
Illuminate\Contracts\Auth\Guard Auth::guard()
Illuminate\Contracts\Auth\PasswordBroker Password::broker()
Illuminate\Contracts\Auth\PasswordBrokerFactory Password
Illuminate\Contracts\Auth\StatefulGuard
Illuminate\Contracts\Auth\SupportsBasicAuth
Illuminate\Contracts\Auth\UserProvider
Illuminate\Contracts\Bus\Dispatcher Bus
Illuminate\Contracts\Bus\QueueingDispatcher Bus::dispatchToQueue()
Illuminate\Contracts\Broadcasting\Factory Broadcast
Illuminate\Contracts\Broadcasting\Broadcaster Broadcast::connection()
Illuminate\Contracts\Broadcasting\ShouldBroadcast
Illuminate\Contracts\Broadcasting\ShouldBroadcastNow
Illuminate\Contracts\Cache\Factory Cache
Illuminate\Contracts\Cache\Lock
Illuminate\Contracts\Cache\LockProvider
Illuminate\Contracts\Cache\Repository Cache::driver()
Illuminate\Contracts\Cache\Store
Illuminate\Contracts\Config\Repository Config
Illuminate\Contracts\Console\Application
Illuminate\Contracts\Console\Kernel Artisan
Illuminate\Contracts\Container\Container App
Illuminate\Contracts\Cookie\Factory Cookie
Illuminate\Contracts\Cookie\QueueingFactory Cookie::queue()
Illuminate\Contracts\Database\ModelIdentifier
Illuminate\Contracts\Debug\ExceptionHandler
Illuminate\Contracts\Encryption\Encrypter Crypt
Illuminate\Contracts\Events\Dispatcher Event
Illuminate\Contracts\Filesystem\Cloud Storage::cloud()
Illuminate\Contracts\Filesystem\Factory Storage
Illuminate\Contracts\Filesystem\Filesystem Storage::disk()
Illuminate\Contracts\Foundation\Application App
Illuminate\Contracts\Hashing\Hasher Hash
Illuminate\Contracts\Http\Kernel
Illuminate\Contracts\Mail\MailQueue Mail::queue()
Illuminate\Contracts\Mail\Mailable
Illuminate\Contracts\Mail\Mailer Mail
Illuminate\Contracts\Notifications\Dispatcher Notification
Illuminate\Contracts\Notifications\Factory Notification
Illuminate\Contracts\Pagination\LengthAwarePaginator
Illuminate\Contracts\Pagination\Paginator
Illuminate\Contracts\Pipeline\Hub
Illuminate\Contracts\Pipeline\Pipeline
Illuminate\Contracts\Queue\EntityResolver
Illuminate\Contracts\Queue\Factory Queue
Illuminate\Contracts\Queue\Job
Illuminate\Contracts\Queue\Monitor Queue
Illuminate\Contracts\Queue\Queue Queue::connection()
Illuminate\Contracts\Queue\QueueableCollection
Illuminate\Contracts\Queue\QueueableEntity
Illuminate\Contracts\Queue\ShouldQueue
Illuminate\Contracts\Redis\Factory Redis
Illuminate\Contracts\Routing\BindingRegistrar Route
Illuminate\Contracts\Routing\Registrar Route
Illuminate\Contracts\Routing\ResponseFactory Response
Illuminate\Contracts\Routing\UrlGenerator URL
Illuminate\Contracts\Routing\UrlRoutable
Illuminate\Contracts\Session\Session Session::driver()
Illuminate\Contracts\Support\Arrayable
Illuminate\Contracts\Support\Htmlable
Illuminate\Contracts\Support\Jsonable
Illuminate\Contracts\Support\MessageBag
Illuminate\Contracts\Support\MessageProvider
Illuminate\Contracts\Support\Renderable
Illuminate\Contracts\Support\Responsable
Illuminate\Contracts\Translation\Loader
Illuminate\Contracts\Translation\Translator Lang
Illuminate\Contracts\Validation\Factory Validator
Illuminate\Contracts\Validation\ImplicitRule
Illuminate\Contracts\Validation\Rule
Illuminate\Contracts\Validation\ValidatesWhenResolved
Illuminate\Contracts\Validation\Validator Validator::make()
Illuminate\Contracts\View\Engine
Illuminate\Contracts\View\Factory View
Illuminate\Contracts\View\View View::make()

1.