Contracts · laravel 5.5 中文文檔

# 契約 (Contracts) - [簡介](#introduction) - [契約 VS Facades](#contracts-vs-facades) - [何時使用契約](#when-to-use-contracts) - [低耦合](#loose-coupling) - [簡單性](#simplicity) - [如何使用契約](#how-to-use-contracts) - [契約參考](#contract-reference) <a name="introduction"></a> ## 簡介 Laravel 的契約是一組定義框架提供的核心服務的接口。例如，`Illuminate\Contracts\Queue\Queue` 契約定義了隊列任務所需的方法，而 `Illuminate\Contracts\Mail\Mailer` 契約定義了發送電子郵件所需的方法。框架對每個契約都提供了相應的實現。例如，Laravel 提供了具有各種驅動的隊列實現和由 [SwiftMailer](http://swiftmailer.org/) 提供支持的郵件驅動實現。所有的 Laravel 契約都有他們自己的 [GitHub 庫](https://github.com/illuminate/contracts)。這為所有可用的契約提供了一個快速參考指南，同時也可單獨作為低耦合的擴展包給其他包開發者使用。 <a name="contracts-vs-facades"></a> ### 契約 VS Facades Laravel [Facades](/docs/{{version}}/facades) 和輔助函數提供了一種使用 Laravel 服務的簡單方法，即不需要通過類型提示并從服務容器中解析契約。在大多數情況下，每個 Facades 都有一個等效的契約。不像 Facades，不需要你在類的構造函數中類型提示，契約則需要你在類中明顯地定義依賴項。一些開發者傾向于以契約這種方式明確地定義它們的依賴項，而其它開發者則更喜歡 Facades 帶來的便捷。 > {tip} 對于大多數應用程序來說不管是使用門面還是契約都可以。但是，如果你正在構建一個擴展包，為了方便測試，你應該強烈考慮契約。 <a name="when-to-use-contracts"></a> ## 何時使用契約綜上所述，使用契約或是 Facades 很大程度上歸結于個人或者開發團隊的喜好。不管是契約還是 Facades 都可以創建出健壯的、易測試的 Laravel 應用程序。如果你長期關注類的單一職責，你會注意到使用契約還是 Facades 其實沒多少實際意義上的區別。然而，你可能還是會有幾個關于契約的問題。例如，為什么要使用接口？不使用接口會比較復雜嗎？下面讓我們談下使用接口的原因：低耦合和簡單性。 <a name="loose-coupling"></a> ### 低耦合首先，讓我們來看一些高耦合緩存實現的代碼。如下: <?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 ），那又得再次修改這個 `repository` 類。而 `repository` 類不應該了解太多關于誰提供了這些數據或是如何提供的等等。 **比起上面的做法，我們可以使用一個簡單的、與擴展包無關的接口來改進我們的代碼：** <?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 耦合。而契約擴展包不包含任何實現和依賴項，你可以輕松地寫任何給定契約的替代實現，來實現不修改任何關于緩存消耗的代碼就可以替換緩存實現。 <a name="simplicity"></a> ### 簡單性當所有 Laravel 的服務都使用簡潔的接口定義，就很容易判斷給定服務提供的功能。 **可以將契約視為說明框架功能的簡潔文檔。** 除此之外，當依賴的接口足夠簡潔時，代碼的可讀性和可維護性會大大提高。比起搜索一個大型復雜的類中有哪些可用的方法，不如檢索一個簡單、干凈的接口來參考更妥當。 <a name="how-to-use-contracts"></a> ## 如何使用契約那么，如何獲得一個契約的實現呢？這其實很簡單～ Laravel 中的許多類型的類都是通過 [服務容器](/docs/{{version}}/container) 解析出來的，包括控制器、事件監聽器、中間件、任務隊列，甚至路由閉包。所以說，要獲得一個契約的實現，你只需要被解析的類的構造函數中添加「類型提示」即可。例如，看看這個事件監聽器： <?php namespace App\Listeners; use App\User; use App\Events\OrderWasPlaced; use Illuminate\Contracts\Redis\Database; class CacheOrderInformation { /** * Redis 數據庫實現。 */ protected $redis; /** * 創建事件處理器實例。 * * @param Database $redis * @return void */ public function __construct(Database $redis) { $this->redis = $redis; } /** * 處理事件。 * * @param OrderWasPlaced $event * @return void */ public function handle(OrderWasPlaced $event) { // } } 當事件監聽器被解析時，服務容器會讀取類的構造函數上的類型提示，并注入對應的值。想了解更多關于服務容器的注冊，請查看 [其文檔](/docs/{{version}}/container)。 <a name="contract-reference"></a> ## 契約參考下表提供了所有 Laravel 契約及其對應的 Facade： Contract | References Facade ------------- | ------------- [Illuminate\Contracts\Auth\Factory](https://github.com/illuminate/contracts/blob/{{version}}/Auth/Factory.php) | Auth [Illuminate\Contracts\Auth\PasswordBroker](https://github.com/illuminate/contracts/blob/{{version}}/Auth/PasswordBroker.php) | Password [Illuminate\Contracts\Bus\Dispatcher](https://github.com/illuminate/contracts/blob/{{version}}/Bus/Dispatcher.php) | Bus [Illuminate\Contracts\Broadcasting\Broadcaster](https://github.com/illuminate/contracts/blob/{{version}}/Broadcasting/Broadcaster.php) |   [Illuminate\Contracts\Cache\Repository](https://github.com/illuminate/contracts/blob/{{version}}/Cache/Repository.php) | Cache [Illuminate\Contracts\Cache\Factory](https://github.com/illuminate/contracts/blob/{{version}}/Cache/Factory.php) | Cache::driver() [Illuminate\Contracts\Config\Repository](https://github.com/illuminate/contracts/blob/{{version}}/Config/Repository.php) | Config [Illuminate\Contracts\Container\Container](https://github.com/illuminate/contracts/blob/{{version}}/Container/Container.php) | App [Illuminate\Contracts\Cookie\Factory](https://github.com/illuminate/contracts/blob/{{version}}/Cookie/Factory.php) | Cookie [Illuminate\Contracts\Cookie\QueueingFactory](https://github.com/illuminate/contracts/blob/{{version}}/Cookie/QueueingFactory.php) | Cookie::queue() [Illuminate\Contracts\Encryption\Encrypter](https://github.com/illuminate/contracts/blob/{{version}}/Encryption/Encrypter.php) | Crypt [Illuminate\Contracts\Events\Dispatcher](https://github.com/illuminate/contracts/blob/{{version}}/Events/Dispatcher.php) | Event [Illuminate\Contracts\Filesystem\Cloud](https://github.com/illuminate/contracts/blob/{{version}}/Filesystem/Cloud.php) |   [Illuminate\Contracts\Filesystem\Factory](https://github.com/illuminate/contracts/blob/{{version}}/Filesystem/Factory.php) | File [Illuminate\Contracts\Filesystem\Filesystem](https://github.com/illuminate/contracts/blob/{{version}}/Filesystem/Filesystem.php) | File [Illuminate\Contracts\Foundation\Application](https://github.com/illuminate/contracts/blob/{{version}}/Foundation/Application.php) | App [Illuminate\Contracts\Hashing\Hasher](https://github.com/illuminate/contracts/blob/{{version}}/Hashing/Hasher.php) | Hash [Illuminate\Contracts\Logging\Log](https://github.com/illuminate/contracts/blob/{{version}}/Logging/Log.php) | Log [Illuminate\Contracts\Mail\MailQueue](https://github.com/illuminate/contracts/blob/{{version}}/Mail/MailQueue.php) | Mail::queue() [Illuminate\Contracts\Mail\Mailer](https://github.com/illuminate/contracts/blob/{{version}}/Mail/Mailer.php) | Mail [Illuminate\Contracts\Queue\Factory](https://github.com/illuminate/contracts/blob/{{version}}/Queue/Factory.php) | Queue::driver() [Illuminate\Contracts\Queue\Queue](https://github.com/illuminate/contracts/blob/{{version}}/Queue/Queue.php) | Queue [Illuminate\Contracts\Redis\Factory](https://github.com/illuminate/contracts/blob/{{version}}/Redis/Factory.php) | Redis [Illuminate\Contracts\Routing\Registrar](https://github.com/illuminate/contracts/blob/{{version}}/Routing/Registrar.php) | Route [Illuminate\Contracts\Routing\ResponseFactory](https://github.com/illuminate/contracts/blob/{{version}}/Routing/ResponseFactory.php) | Response [Illuminate\Contracts\Routing\UrlGenerator](https://github.com/illuminate/contracts/blob/{{version}}/Routing/UrlGenerator.php) | URL [Illuminate\Contracts\Support\Arrayable](https://github.com/illuminate/contracts/blob/{{version}}/Support/Arrayable.php) |   [Illuminate\Contracts\Support\Jsonable](https://github.com/illuminate/contracts/blob/{{version}}/Support/Jsonable.php) |   [Illuminate\Contracts\Support\Renderable](https://github.com/illuminate/contracts/blob/{{version}}/Support/Renderable.php) |   [Illuminate\Contracts\Validation\Factory](https://github.com/illuminate/contracts/blob/{{version}}/Validation/Factory.php) | Validator::make() [Illuminate\Contracts\Validation\Validator](https://github.com/illuminate/contracts/blob/{{version}}/Validation/Validator.php) |   [Illuminate\Contracts\View\Factory](https://github.com/illuminate/contracts/blob/{{version}}/View/Factory.php) | View::make() [Illuminate\Contracts\View\View](https://github.com/illuminate/contracts/blob/{{version}}/View/View.php) |   ## 譯者署名 | 用戶名 | 頭像 | 職能 | 簽名 | |---|---|---|---| | [@iwzh](https://github.com/iwzh) | <img class="avatar-66 rm-style" src="https://dn-phphub.qbox.me/uploads/avatars/3762_1456807721.jpeg?imageView2/1/w/200/h/200"> | 翻譯 | 碼不能停 [@iwzh](https://github.com/iwzh) at Github | | [@JokerLinly](https://laravel-china.org/users/5350) | <img class="avatar-66 rm-style" src="https://dn-phphub.qbox.me/uploads/avatars/5350_1481857380.jpg"> | Review | Stay Hungry. Stay Foolish. | --- > {note} 歡迎任何形式的轉載，但請務必注明出處，尊重他人勞動共創開源社區。 > > 轉載請注明：本文檔由 Laravel China 社區 [laravel-china.org](https://laravel-china.org) 組織翻譯，詳見 [翻譯召集帖](https://laravel-china.org/topics/5756/laravel-55-document-translation-call-come-and-join-the-translation)。 > > 文檔永久地址： https://d.laravel-china.org