IT博客汇 | [译]Laravel 5.0 之命令及处理程序

[译]Laravel 5.0 之命令及处理程序

小李刀刀发表于 2015-03-02 07:57:09

本文中涉及的新功能都是关于 Commands 的，这些特性在 Laravel 旧版本中已经有了，但是在 Laravel 5.0 中变得更加好用了。

本文中将会用到例子来自于我正在开发的一个叫做 SaveMyProposals 的新应用。

什么是 Command, Command handler 和 Command bus?

在 Shawn McCool 的这篇文章中，你可以深入了解 command, command handler, command bus 的概念。但总的来说：

Command 是一个代表信息的简单对象。它只包含你打算做某件事时需要用到的信息。在我们接下来的例子中，它就是 "复制谈话命令(Duplicate Talk Command)", 任何时候当用户要复制一条谈话建议时，我们的系统就会调用它。这个 "重复谈话命令" 会包含复制一个谈话所需要的全部属性集——比如一个序列化的 Talk 对象或者是 TaldId.

Command Handler 则是用于对 Command 做出响应的一个类。Command 可以在一个或多个 Handlers 之间传递，每个 Handler 从 Command 中取出重要的信息并做某些操作来响应。

Command bus 是一套用于调度 Commands 的系统。它把 commands 与对应的 Handlers 进行匹配，并使它们能够一起工作。一般情况下，人们需要编写自己的 command bus, 但 Laravel 内置了一个开箱即用的 Command bus, 所以至少在本文涉及的范围内我们不用担心这个问题。

在 Laravel 中使用 Command

在开始介绍 Laravel 5.0 中使用 Command 的整个结构之前，我们先看看最终的用例是怎样的。假设一个用户访问了系统的某个路由，比如 savemyproposals.com/talks/12345/duplicate, 该路由被解析到 TalkController@duplicate(12345).

下面是处理这个请求的路由和方法：

// Http\Controllers\TalkController
...
    public function duplicate($talkId)
    {
        $talk = Talk::findOrFail($talkId);

        $this->dispatch(new DuplicateTalkCommand($talk));

        // 取决于具体的实现，这两行代码也可能简化为一行代码：
        // $this->dispatch(new DuplicateTalkCommand($talkId));
    }

接下来是 Command 的代码：

// Commands\DuplicateTalkCommand
...

class DuplicateTalkCommand extends Command
{
    public $talk;

    public function __construct(Talk $talk)
    {
        $this->talk = $talk;
    }
}

然后是 Command handler:

// Handlers\Commands\DuplicateTalkCommandHandler
...

class DuplicateTalkCommandHandler
{
    public function handle(DuplicateTalkCommand $command)
    {
        // 对 $command 变量进行某些操作
        dd($command);
    }
}

就如上面的代码所展示的，控制器通过一些必要的信息创建了一个 DuplicateTalkCommand 对象，通过内置的 command bus dispatcher 对齐进行调度，于是该命令的处理程序自动对其进行处理。

体系结构

接下来，我们先来看看这些命令和处理程序存放在什么位置，然后再说说如何生成它们。

文件夹

在 Laravel 5.0 的应用框架中，app/ 目录下有两个新的文件夹：Commands 和 Handlers, Handlers 目录下还有两个子目录：Commands 和 Events(这个目录说明我们还可以期待事件处理的特性).

app/
    Commands/
    Handlers/
        Commands/
        Events/

相信看到目录结构你就能猜到，Commands 的代码存放在 app/Commands 目录下，而 Command handlers 则存放在 app/Handlers/Commands 目录下—— Handler 的文件名与其对应的 Command 保持一致，但是要加上 Handler 后缀。

Artisan

非常值得庆幸的是，你不用自己动手来创建 Command 和 Command Handler。新版本提供了一个全新的 Artisan 生成工具，通过它可以快速生成这些文件：

$ php artisan make:command DuplicateTalkCommand

默认情况下，这条命令会生成一个自处理的命令(不生成单独的 Command handler)，并且该命令不添加到队列。加上 --handler 参数可以同时生成 handler, 加上 --queued 参数可以将其加入到队列。

执行这个 artisan 命令会生成两个文件：命令文件(app/Commands/DuplicateTalkCommand.php) 和处理程序文件(app/Handlers/Commands/DuplicateTalkCommandHandler.php) (假设使用了 --handler 参数)，并且生成的处理程序中的 handle 方法会自动加上与其匹配的命令的类型约束。

基本工作流程

综上所述，要创建一个新的 DuplicateTalkCommand, 你需要执行以下工作：

php artisan make:command DuplicateTalkCommand
编辑 DuplicateTalkCommand, 增加一个 public 属性 $talk 并在构造函数中初始化这个属性。
编辑 DuplicateTalkCommandHandler, 在 handle() 方法中编写具体代码，完成你需要执行的操作。
在控制器或者 Artisan 命令中调度（调用）这个命令。

队列

把命令加入队列

如果希望某个命令在每次被调用时加入到队列中以便异步执行，你需要做的是让该命令实现 ShouldBeQueued 接口。 Laravel 会发现这个接口并把其加入队列等候执行，而不是立即执行。

...
class DuplicateTalkCommand extends Command implements ShouldBeQueued
{
    //...
}

InteractsWithQueue trait

在你的 Command 类中加上这个 trait, 会让你的 Command 具有在以前版本中用惯了的队列命令（queue commands）所具有的全部特性：$command->release(), $command->delete(), $command->attempts() 等等。

...
class DuplicateTalkCommand extends Command implements ShouldBeQueued, InteractsWithQueue
{
    //...
}

SerializesModels trait

如果你传入一个 Eloquent 模型作为属性，就像前面的例子中那样，并且希望命令放入队列中执行而不是同步执行，那么必须要考虑到 Eloquent 模型的序列化，这可能会给你带来一些麻烦。不过在 Laravel 5.0 版本中，你可以给你的 Command 加一个名为 SerializesModels 的 trait 来解决这个问题。方法很简单，在类的代码块顶部加上即可：

...
class DuplicateTalkCommand extends Command implements ShouldBeQueued
{ 
    use SerializesModels;
    // ...
}

Dispatcher

DispatchesCommands Trait

你可能注意到，在前面的例子中，我们可以直接在控制器中使用 $this->dispatch() 方法。这是控制器的一个语法糖。这个语法糖实际上是通过名为 DispathesCommands 的 trait 来实现的。你可以在控制器之外的任何地方使用这个 trait.

比如，你希望某个服务类可以在方法中使用 $this->dispatch(), 你只要在你的服务类的代码块顶部使用 DispatchesCommands 这个 trait 即可：

...
class MyServiceClass {

    use DispatchesCommands;

    //...
}

注入 bus

如果你希望更直接、更清楚地调用 Command bus 而不是借助于 Laravel 系统提供的 trait, 你可以直接向你的类的构造函数或者是方法注入 Illuminate\Contracts\Bus\Dispatcher 实例（参见 Laravel 5.0 之方法注入）。

...
    public function __construct(\Illuminate\Contracts\Bus\Dispatcher $bus)
    {
        $this->bus = $bus;
    }

    public function doSomething()
    {
        $this->bus->dispatch(new Command);
    }

dispatchFrom(command::class, $request 或任何 arrayAccessible 对象)

在之前的例子中，我们已经看到了调用命令的最简单方式，就是 $bus->dispatch(new Command(params...)). 但有时候由于新建命令的参数列表变得越来越大——比如，当你的命令用于来处理表单输入的时候：

...
class CreateTalkCommand extends Command
{
    public function __construct($title, $description, $outline, $organizer_notes, $length, $type, $level) {
        // ...
    }
}

这时，如果还用之前的方式来实例化命令，代码会变得很难看：

$this->dispatch(new CreateTalkCommand($input['title'], $input['description'],
        $input['outline'], $input['organizer_notes'], $input['length'],
        $input['type'], $input['level']));

通常我们的表单请求会传递与属性相同 key 的数组，从数组或者请求对象中获得具体的值。幸亏 Laravel 5.0 有针对这种情况的解决方案：

$this->dispatch('NameOfCommand', $objectThatImplementsPHPArrayAccessible);

因此我们可以用下面的代码替换上面那长长的一串：

$this->dispatchFrom(CreateTalkCommand::class, $input);

或者这样：

public function doSomethingInController(Request $request)
    {
        $this->dispatchFrom(CreateTalkCommand::class, $request);
        // ...
    }

Laravel 会自动在传入的数组或者 arrayAccessible 对象中去寻找与属性名相同的 key, 取出对应的值来调用命令的构造函数。

自处理命令

如果你嫌每个命令都要创建一个 Command 类和一个 Command handler 类太麻烦的话，你可以创建一个“自处理”的 Command. 这种情况下 Command 只有单一的处理程序，且该处理程序就是 Command 自己。要让一个 Command 变成自处理，只需要给该 command 类加一个 handle() 方法，并让它实现 SelfHandling 接口：

...
class DuplicateTalkCommand extends Command implements SelfHandling
{
    //...
    public function handle()
    {
        //...
    }

其它注意事项

命令处理程序会由 IOC 容器进行解析，因此你可以注入 repositories, service classes 或者任何其它类型到你的命令处理程序的构造函数中，然后在 handle() 方法中调用它们。
几乎所有相关的 trait 和接口都在 Illuminate\Contracts\Bus 或者 Illuminate\Contracts\Queue 命名空间下。比如，Illuminate\Contracts\Bus\SelfHandling.
如果你的命令是放入队列执行，不需要在处理程序的最后执行 $command->delete() 方法。只要你的处理程序没有抛出任何异常，Laravel 会假定它已经正确完成，并自动将其从队列中移除。

写在最后

就这么多了，如果我遗漏了什么，或者某个问题讲得不够清楚，请让我知道。本文涉及到的点还有一些需要补充和替换的地方。暂时来说，我希望本文可以帮助你了解新版 Laravel 中的 Command 的运行机制。此外，Taylor 在 Laracasts 上的视频涵盖了本文的全部内容并且讲得更多。