Contracts

未匹配的标注
本文档最新版为 10.x,旧版本可能放弃维护,推荐阅读最新版!

契约

介绍

Laravel 的契约是一组接口,它们由框架提供并定义了核心服务。 例如,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 的实际差别是非常小的。

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

低耦合

首先,让我们看一些缓存实现的高耦合代码。请看下面这段代码:


    <?php

    namespace App\Orders;

    class Repository
    {
        /**
         * 缓存实例
         */
        protected $cache;

        /**
         * 创建一个仓库实例
         *
         * @param  \SomePackage\Cache\Memcached  $cache
         * @return void
         */
        public function __construct(\SomePackage\Cache\Memcached $cache)
        {
            $this->cache = $cache;
        }

        /**
         * 按照 ID 获取订单
         *
         * @param  int  $id
         * @return Order
         */
        public function find($id)
        {
            if ($this->cache->has($id)) {
                //
            }
        }
    }

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

同理,如果我们想要将底层的缓存技术 ( Memcached ) 替换成另一种缓存技术 ( Redis ),我们得再次修改我们的代码库。我们的代码库不应该对谁提供的数据或者数据是怎么提供的有太多了解。

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


    <?php

    namespace App\Orders;

    use Illuminate\Contracts\Cache\Repository as Cache;

    class Repository
    {
        /**
         * 缓存实例
         */
        protected $cache;

        /**
         * 创建一个仓库实例
         *
         * @param  Cache  $cache
         * @return void
         */
        public function __construct(Cache $cache)
        {
            $this->cache = $cache;
        }
    }

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

简明性

当 Laravel 的所有服务都在简单的接口中简洁地定义时,很容易就可以确定给定服务提供的功能。契约是框架功能的简洁文档。

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

如何使用契约

那么,你如何实现契约呢?它实际上非常简单。

Laravel 中的许多类都通过服务容器解析,包括控制器,事件监听器,中间件,队列任务,甚至路由闭包。因此,要获得契约的接口实现,你可以在要解析的类的构造函数中使用「类型提示」接口。

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

    <?php

    namespace App\Listeners;

    use App\Events\OrderWasPlaced;
    use App\User;
    use Illuminate\Contracts\Redis\Factory;

    class CacheOrderInformation
    {
        /**
         * Redis 数据库实现
         */
        protected $redis;

        /**
         * 创建事件处理器实例
         *
         * @param  Factory  $redis
         * @return void
         */
        public function __construct(Factory $redis)
        {
            $this->redis = $redis;
        }

        /**
         * 处理事件
         *
         * @param  OrderWasPlaced  $event
         * @return void
         */
        public function handle(OrderWasPlaced $event)
        {
            //
        }
    }

解析事件侦听器后,服务容器将读取类的构造函数上的类型提示,并注入适当的值。要了解有关在服务容器中注册内容的更多信息,请查看其文档

契约参考

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

契约 参考 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()

本文章首发在 LearnKu.com 网站上。

本译文仅用于学习和交流目的,转载请务必注明文章译者、出处、和本文链接
我们的翻译工作遵照 CC 协议,如果我们的工作有侵犯到您的权益,请及时联系我们。

原文地址:https://learnku.com/docs/laravel/7.x/con...

译文地址:https://learnku.com/docs/laravel/7.x/con...

上一篇 下一篇
《L05 电商实战》
从零开发一个电商项目,功能包括电商后台、商品 & SKU 管理、购物车、订单管理、支付宝支付、微信支付、订单退款流程、优惠券等
《L04 微信小程序从零到发布》
从小程序个人账户申请开始,带你一步步进行开发一个微信小程序,直到提交微信控制台上线发布。
贡献者:5
讨论数量: 2
发起讨论 查看所有版本


KovenZhang
Laravel-7 中文文档-核心加购-Contracts 链接失效
0 个点赞 | 1 个回复 | 问答 | 课程版本 7.x
sunniness
文档中契约参考的链接出现 404
0 个点赞 | 0 个回复 | 问答 | 课程版本 7.x