Contracts

简介

Laravel 的 Contracts 是一组定义了框架核心服务的接口( php class interfaces )。例如,Illuminate\Contracts\Queue\Queue contract 定义了队列任务所需要的方法,而 Illuminate\Contracts\Mail\Mailer contract 定义了寄送 e-mail 需要的方法。

框架对于每个 contract 都有提供对应的实现,例如,Laravel 提供各种驱动程序的队列实现,以及由 SwiftMailer 提供的 mailer 实现。

Laravel 所有的 contracts 都放在 各自的 GitHub 代码库。除了提供给所有可用的 contracts 一个快速的参考,也可以单独作为一个低耦合的扩展包来让其他扩展包开发者使用。

Contracts Vs. Facades

Laravel 的 facades 提供一个简单的方法来使用服务,而不需要使用类型提示和在服务容器之外解析 contracts。然而,使用 contracts 可以明显地定义出类的依赖,对大部分应用进程而言,使用 facade 就足够了,然而,若你实在需要特别的低耦合,使用 contracts 可以做到这一点,来让我们继续往下看!

为何要用 Contracts?

你可能有很多关于 contracts 的问题。像是为什么要使用接口?使用接口会不会变的更复杂?

让我们用下面的标题来解释为什么要使用接口:低耦合和简单性。

低耦合

首先,让我们来查看这一段和缓存功能有高耦合的代码,如下:

  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 ),又一次的我们必须修改这个 Repository 类。我们的 Repository 类不应该知道这么多关于谁提供了数据,或是如何提供等细节。

比起上面的做法,我们可以使用一个简单、和扩展包无关的接口来改进代码:

  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。既然 contracts 扩展包没有包含实现和任何依赖,你就可以很简单的对任何 contract 进行实现,你可以很简单的写一个替换的实现,甚至是替换 contracts,让你可以替换缓存实现而不用修改任何用到缓存的代码。

简单性

当所有的 Laravel 服务都使用简洁的接口定义,就能够很容易决定一个服务需要提供的功能。 可以将 contracts 视为说明框架特色的简洁文档。

除此之外,当依赖的接口足够简洁时,代码的可读性和可维护性大大提高。比起搜索一个大型复杂的类里有哪些可用的方法,你有一个简单,干净的接口可以参考。

Contract 参考

以下是大部分 Laravel Contracts 的参考,以及相对应的「facade」:

Contract 对应的 Facade
Illuminate\Contracts\Auth\Factory Auth
Illuminate\Contracts\Auth\PasswordBroker Password
Illuminate\Contracts\Bus\Dispatcher Bus
Illuminate\Contracts\Broadcasting\Broadcaster  
Illuminate\Contracts\Cache\Repository Cache
Illuminate\Contracts\Cache\Factory Cache::driver()
Illuminate\Contracts\Config\Repository Config
Illuminate\Contracts\Container\Container App
Illuminate\Contracts\Cookie\Factory Cookie
Illuminate\Contracts\Cookie\QueueingFactory Cookie::queue()
Illuminate\Contracts\Encryption\Encrypter Crypt
Illuminate\Contracts\Events\Dispatcher Event
Illuminate\Contracts\Filesystem\Cloud  
Illuminate\Contracts\Filesystem\Factory File
Illuminate\Contracts\Filesystem\Filesystem File
Illuminate\Contracts\Foundation\Application App
Illuminate\Contracts\Hashing\Hasher Hash
Illuminate\Contracts\Logging\Log Log
Illuminate\Contracts\Mail\MailQueue Mail::queue()
Illuminate\Contracts\Mail\Mailer Mail
Illuminate\Contracts\Queue\Factory Queue::driver()
Illuminate\Contracts\Queue\Queue Queue
Illuminate\Contracts\Redis\Database Redis
Illuminate\Contracts\Routing\Registrar Route
Illuminate\Contracts\Routing\ResponseFactory Response
Illuminate\Contracts\Routing\UrlGenerator URL
Illuminate\Contracts\Support\Arrayable  
Illuminate\Contracts\Support\Jsonable  
Illuminate\Contracts\Support\Renderable  
Illuminate\Contracts\Validation\Factory Validator::make()
Illuminate\Contracts\Validation\Validator  
Illuminate\Contracts\View\Factory View::make()
Illuminate\Contracts\View\View  

如何使用 Contracts

要如何使用一个 contract 呢?实际上非常的简单。

很多 Laravel 的类都是经由 服务容器 来解析,包含控制器,事件监听,中间件,队列任务,甚至是路由闭包。所以,要实现一个 contract,你可以在类的构造器使用「类型提示」解析类。

例如,我们来看看这个事件监听程序:

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

当事件监听被解析时,服务容器会经由类构造器参数的类型提示,注入适当的值。要知道怎么注册更多服务容器,参考 这份文档.


{note} 欢迎任何形式的转载,但请务必注明出处,尊重他人劳动共创开源社区。

转载请注明:本文档由 Laravel China 社区 [laravel-china.org] 组织翻译。

文档永久地址: http://d.laravel-china.org