Laravel中如何用Saloon进行API集成

2023-07-04 11:18

短信预约 -IT技能 免费直播动态提醒

今天小编给大家分享一下Laravel中如何用Saloon进行API集成的相关知识点，内容详细，逻辑清晰，相信大部分人都还太了解这方面的知识，所以分享这篇文章给大家参考一下，希望大家阅读完这篇文章后有所收获，下面我们一起来了解一下吧。

像所有伟大的事情一样，它以laravel new 开始并从那里开始，所以让我们开始吧。现在在安装 Laravel 时，你可以使用 laravel installer 或 composer ——这部分由你决定。如果可以的话，我会推荐安装程序，因为它提供了简单的选项来做更多的事情，而不仅仅是创建一个项目。创建一个新项目并在您选择的代码编辑器中打开它。一旦我们在那里，我们就可以开始了。

我们要建造什么？我很高回答这个提问！我们将构建与 GitHub API 的集成，以获取可用于 repo 的工作流列表。现在，如果你像我一样在命令行上花费大量时间，这可能会非常有用。你正在开发一个应用程序，将更改推送到一个分支或创建一个 PR - 它通过一个可能正在运行许多其他事情之一的工作流。了解此工作流程的状态有时会对您接下来的工作产生巨大影响。功能齐全吗？我们的工作流程运行是否存在问题？我们的测试或静态分析是否通过了？所有这些你通常会等待并检查 GitHub 上的 repo 以查看状态。此集成将允许您运行 artisan 命令，获取 repo 的可用工作流列表，并允许你触发新的工作流运行。

所以到现在为止，composer 应该已经完成了它的工作并安装了一个完美的起点，一个 Laravel 应用程序。接下来我们需要安装 Saloon - 但我们要确保安装 laravel 版本，所以在终端中运行以下命令：

composer require sammyjo20/saloon-laravel

就像这样，我们已经离更容易的集成更近了一步。如果你在此阶段有任何问题，请确保检查您正在使用的 Laravel 和 PHP 版本，因为 Saloon 至少需要 Laravel 8 和 PHP 8！

所以，现在我们已经安装了 Saloon，我们需要创建一个新类。在 Saloons 术语中，这些是「连接器」，连接器所做的一切就是创建一种以对象为中心的方式来表达 - 此 API 通过此类连接。有一个方便的 artisan 命令允许您创建这些，因此运行以下 artisan 命令来创建 GitHub 连接器：

php artisan saloon:connector GitHub GitHubConnector

该命令分为两部分，第一个参数是你正在创建的集成，第二个参数是要创建的连接器的名称。这意味着你可以为集成创建多个连接器 - 如果需要的话可以通过多种不同方式进行连接。

这将在 app/Http/Integrations/GitHub/GitHubConnector.php 下为你创建一个新类，让我们看一下，了解发生了什么。

我们看到的第一件事是我们的连接器扩展了「SaloonConnector」，这将使我们能够让我们的连接器在没有大量样板代码的情况下工作。然后我们继承了一个名为「AcceptsJson」的特征。现在，如果我们查看 Saloon 文档，我们知道这是一个插件。这基本上为我们的请求添加了一个标头，告诉第 3 方 API 我们想要接受 JSON 响应。接下来我们看到的是我们有一个方法来定义我们的连接器的基本 URL - 所以让我们添加我们的：

public function defineBaseUrl(): string{    return 'https://api.github.com';}

又好又干净，我们甚至可以更进一步，这样我们就可以处理应用程序中较少的松散字符串 - 所以让我们看看我们如何做到这一点。在您的 config/services.php 文件中添加新的服务记录：

'github' => [    'url' => env('GITHUB_API_URL', 'https://api.github.com'),]

这将允许我们在不同的环境中覆盖它 - 为我们提供更好和更可测试的解决方案。在本地，我们甚至可以使用他们的 OpenAPI 规范模拟 GitHub API，并对其进行测试以确保其正常工作。但是，本教程是关于 Saloon 的，所以我离题了……现在让我们重构我们的基本 URL 方法以使用配置：

public function defineBaseUrl(): string{    return (string) config('services.github.url');}

如你所见，我们现在从配置中获取新添加的记录 - 并将其转换为字符串以确保类型安全 - config() 可能会返回多种不同类型的结果。如果可以的话，我们希望对此进行严格处理。

接下来我们有默认 header 和默认配置，无须担心默认 header 的内容，因为我们将在一段时间内自行处理身份验证。但配置部分是我们可以为集成定义 guzzle 选项的地方，因为 Saloon 在服务引擎下使用了 Guzzle。现在让我们设置超时并继续，我们需要花一些时间配置它：

public function defaultConfig(): array{    return [        'timeout' => 30,    ];}

我们现在已经按照我们的需要配置了我们的连接器，如果我们有需要添加的配置，可以稍后再添加。下一步是开始考虑我们要发送的请求。如果我们查看 GitHub Actions API 的 API 文档，我们有很多选择，我们将从列出特定存储库的工作流开始：/repos/{owner}/{repo}/actions/workflows。运行以下 artisan 命令创建一个新请求：

php artisan saloon:request GitHub ListRepositoryWorkflowsRequest

同样，第一个参数是集成，第二个参数是我们要创建的请求的名称。我们需要确保为我们正在创建的请求命名集成，以便它存在于正确的位置，然后我们需要给它一个名称。我将我的命名为 ListRepositoryWorkflowsRequest，因为我喜欢描述性的命名方法 - 但是，你可以随意调整以适应你喜欢的命名方式。这将创建一个新文件供我们查看：app/Http/Integrations/GitHub/Requests/ListRepositoryWorkflowsRequest.php - 现在让我们看一下。

我们再次在这里扩展了一个库类，这次是预期的 SaloonRequest。这里会包含一个连接器属性和一个方法。如果需要，我们可以修改这个方法 - 但默认的 GET 是我们现在需要的。然后我们有一个定义端点的方法。重构你的请求类，使其类似于以下示例：

 class ListRepositoryWorkflowsRequest extends SaloonRequest{    protected ?string $connector = GitHubConnector::class;    protected ?string $method = Saloon::GET;    public function __construct(        public string $owner,        public string $repo,    ) {}    public function defineEndpoint(): string    {        return "/repos/{$this->owner}/{$this->repo}/actions/workflows";    }}

我们所做的是添加一个构造函数，它接受 repo 和 owner 作为参数，然后我们可以在端点定义方法中使用它们。我们还将连接器设置为我们之前创建的 GitHubConnector。所以我们有一个我们知道可以发送的请求，我们可以从集成中走一小步，转而考虑控制台命令。

如果你之前没有在 Laravel 中创建过控制台命令，请务必查看文档。运行以下 artisan 命令来为此集成创建第一个命令：

php artisan make:command GitHub/ListRepositoryWorkflows

这将创建以下文件：app/Console/Commands/GitHub/ListRespositoryWorkflows.php。我们现在可以开始使用命令来发送请求并获取我们关心的数据。当谈到控制台命令时，我总是做的第一件事就是考虑签名。我希望如何调用它？它需要能够解释它正在做什么，同时具备一定的辨识度。我将会用 github:workflows 作为签名，因为这很好地解释了我想做的事情。我们还可以向控制台命令添加描述，以便在浏览可用命令时更好地解释目的：「通过存储库名称从 GitHub 获取工作流列表」。

最后，我们到了命令的 handle 方法，这部分是我们实际需要做的事情。在我们的例子中，我们将发送一个请求，获取一些数据并以某种方式显示这些数据。然而，在我们能够做到这一点之前，我们还没有完成一件事。那就是身份验证。

对于每一个 API 集成，身份验证都是关键方面之一——我们需要 API 不仅知道我们是谁，而且知道我们实际上被允许发出这个请求。如果你转到你的 GitHub 设置并点击进入开发人员设置和个人访问令牌，在此你可以生成自己的设置。我建议使用这种方法，而不是为此使用完整的 OAuth 应用程序。我们不需要 OAuth，我们只需要用户能够访问他们需要的内容。

获得访问令牌后，我们需要将其添加到我们的 .env 文件中，并确保我们可以通过配置提取它。

GITHUB_API_TOKEN=ghp_loads-of-letters-and-numbers-here

我们现在可以在 github 下的 config/services.php 中扩展我们的服务，添加这个令牌：

'github' => [    'url' => env('GITHUB_API_URL', 'https://api.github.com'),    'token' => env('GITHUB_API_TOKEN'),]

现在我们有了一个加载这个令牌的好方法，我们可以回到我们的控制台命令！我们需要修改我们的签名以允许我们接受所有者和存储库作为参数：

 class ListRepositoryWorkflows extends Command{    protected $signature = 'github:workflows        {owner : The owner or organisation.}        {repo : The repository we are looking at.}    ';    protected $description = 'Fetch a list of workflows from GitHub by the repository name.';    public function handle(): int    {        return 0;    }}

现在我们可以将注意力转移到 handle 方法上：

public function handle(): int{    $request = new ListRepositoryWorkflowsRequest(        owner: $this->argument('owner'),        repo: $this->argument('repo'),    );    return self::SUCCESS;}

在这里，我们开始通过将参数直接传递到请求本身来构建我们的请求，但是我们可能想要做的是创建一些局部变量来提供一些控制台反馈：

 public function handle(): int{    $owner = (string) $this->argument('owner');    $repo = (string) $this->argument('repo');    $request = new ListRepositoryWorkflowsRequest(        owner: $owner,        repo: $repo,    );    $this->info(        string: "Fetching workflows for {$owner}/{$repo}",    );    return self::SUCCESS;}

所以我们有一些反馈给用户，这对于控制台命令来说总是很重要的。现在我们需要添加我们的身份验证令牌并实际发送请求：

 public function handle(): int{    $owner = (string) $this->argument('owner');    $repo = (string) $this->argument('repo');    $request = new ListRepositoryWorkflowsRequest(        owner: $owner,        repo: $repo,    );    $request->withTokenAuth(        token: (string) config('services.github.token'),    );    $this->info(        string: "Fetching workflows for {$owner}/{$repo}",    );    $response = $request->send();    return self::SUCCESS;}

如果你修改上述内容并在 $response->json() 上执行 dd()，然后运行命令：

php artisan github:workflows laravel laravel

这将获得 laravel/laravel repo 的工作流列表。我们的命令将允许你使用任何公共存储库，如果你希望它更具体，你可以建立一个要检查的存储库选项列表，而不是接受参数 —— 但这部分取决于你个人。对于本教程，我将重点关注更广泛更开放的用例。

现在，我们从 GitHub API 得到的响应非常好且信息丰富，但它需要转换才能显示，如果我们孤立地查看它，则没有上下文。相反，我们将在我们的请求中添加另一个插件，这将允许我们将响应转换为 DTO（域传输对象），这是处理此问题的好方法。它将允许我们放松我们习惯于从 API 获取的灵活数组，并获得更具上下文感知的东西。让我们为工作流创建一个 DTO，创建一个新文件：app/Http/Integrations/GitHub/DataObjects/Workflow.php 并向其中添加以下代码：

 class Workflow{    public function __construct(        public int $id,        public string $name,        public string $state,    ) {}    public static function fromSaloon(array $workflow): static    {        return new static(            id: intval(data_get($workflow, 'id')),            name: strval(data_get($workflow, 'name')),            state: strval(data_get($workflow, 'state')),        );    }    public function toArray(): array    {        return [            'id' => $this->id,            'name' => $this->name,            'state' => $this->state,        ];    }}

我们有一个构造函数，其中包含我们要显示的工作流的重要部分，一个 fromSaloon 方法，它将一个数组从一个 saloon 转换为一个新的 DTO，以及一个用于将 DTO 显示回数组的数组方法当我们需要它时。在我们的ListRepositoryWorkflowsRequest 中，我们需要继承一个新特征并添加一个新方法：

 class ListRepositoryWorkflowsRequest extends SaloonRequest{    use CastsToDto;    protected ?string $connector = GitHubConnector::class;    protected ?string $method = Saloon::GET;    public function __construct(        public string $owner,        public string $repo,    ) {}    public function defineEndpoint(): string    {        return "/repos/{$this->owner}/{$this->repo}/actions/workflows";    }    protected function castToDto(SaloonResponse $response): Collection    {        return (new Collection(            items: $response->json('workflows'),        ))->map(function ($workflow): Workflow {            return Workflow::fromSaloon(                workflow: $workflow,            );        });    }}

我们继承了 CastsToDto trait，它允许这个请求在响应中调用 dto 方法，然后我们添加一个 castToDto 方法，我们可以控制它的转换方式。我们希望它返回一个新的集合，因为有多个工作流，使用响应正文的工作流部分。然后我们映射集合中的每个项目 - 并将其转换为 DTO。现在我们既可以这样做，也可以使用 DTO 构建集合：

protected function castToDto(SaloonResponse $response): Collection{    return new Collection(        items: $response->collect('workflows')->map(fn ($workflow) =>            Workflow::fromSaloon(                workflow: $workflow            ),        )    );}

你可以在这里选择最适合你的方式。我个人更喜欢第一种方法，因为我喜欢逐步了解逻辑，但是这两种方法都没有错——选择权在你。现在回到命令，我们现在需要考虑我们希望如何显示这些信息：

public function handle(): int{    $owner = (string) $this->argument('owner');    $repo = (string) $this->argument('repo');    $request = new ListRepositoryWorkflowsRequest(        owner: $owner,        repo: $repo,    );    $request->withTokenAuth(        token: (string) config('services.github.token'),    );    $this->info(        string: "Fetching workflows for {$owner}/{$repo}",    );    $response = $request->send();    if ($response->failed()) {        throw $response->toException();    }    $this->table(        headers: ['ID', 'Name', 'State'],        rows: $response            ->dto()            ->map(fn (Workflow $workflow) =>                  $workflow->toArray()            )->toArray(),    );    return self::SUCCESS;}

因此，我们创建一个带有标题的表，然后对于我们想要响应 DTO 的行，我们将映射返回的集合，将每个 DTO 转换回要显示的数组。从响应数组转换为 DTO 再转换回数组，这似乎违反直觉，但这会强制执行类型，以便 ID、名称和状态在预期时始终存在，并且不会给出任何有趣的结果.它允许正常响应数组可能没有它的一致性，如果我们愿意，我们可以将它转换为一个值对象，我们可以在其中附加行为。如果我们现在运行我们的命令，我们现在应该会看到一个漂亮的表格输出，它比几行字符串更容易阅读：

php artisan github:workflows laravel laravel

Fetching workflows for laravel/laravel+----------+------------------+--------+| ID       | Name             | State  |+----------+------------------+--------+| 12345678 | pull requests    | active || 87654321 | Tests            | active || 18273645 | update changelog | active |+----------+------------------+--------+

最后，仅仅列出这些工作流程是很棒的——但让我们以科学的名义更进一步。假设你正在针对你的一个存储库运行此命令，并且想手动运行更新更改日志？或者，也许你希望使用你的实时生产服务器或你可能想到的任何事件在 cron 上触发它？我们可以将变更日志设置为每天午夜运行一次，这样我们就可以在变更日志中获得每日回顾或任何我们可能想要的内容。让我们创建另一个控制台命令来创建一个新的工作流调度事件：

php artisan saloon:request GitHub CreateWorkflowDispatchEventRequest

在这个新文件 app/Http/Integrations/GitHub/Requests/CreateWorkflowDispatchEventRequest.php 中添加以下代码，以便我们浏览它：

class CreateWorkflowDispatchEventRequest extends SaloonRequest{    use HasJsonBody;    protected ?string $connector = GitHubConnector::class;    public function defaultData(): array    {        return [            'ref' => 'main',        ];    }    protected ?string $method = Saloon::POST;    public function __construct(        public string $owner,        public string $repo,        public string $workflow,    ) {}    public function defineEndpoint(): string    {        return "/repos/{$this->owner}/{$this->repo}/actions/workflows/{$this->workflow}/dispatches";    }}

通过设置连接器，并继承 HasJsonBody 特征以允许我们发送数据。该方法已设置为 POST 请求，因为我们要发送数据。然后我们有一个构造函数，它接受构建端点的 URL 部分。

最后，我们在 defaultData 中有圆顶默认数据，我们可以使用它来设置此发布请求的默认值。与 repo 一样，我们可以在此处传递提交哈希或分支名称 - 所以我将默认设置为 main，因为这就是我通常所说的生产分支。

我们现在可以触发这个端点来调度一个新的工作流事件，所以让我们创建一个控制台命令来控制它，这样我们就可以从我们的 CLI 运行它：

php artisan make:command GitHub/CreateWorkflowDispatchEvent

现在让我们编写具体的逻辑，我们可以了解正在发生的事情：

class CreateWorkflowDispatchEvent extends Command{    protected $signature = 'github:dispatch        {owner : The owner or organisation.}        {repo : The repository we are looking at.}        {workflow : The ID of the workflow we want to dispatch.}        {branch? : Optional: The branch name to run the workflow against.}    ';    protected $description = 'Create a new workflow dispatch event for a repository.';    public function handle(): int    {        $owner = (string) $this->argument('owner');        $repo = (string) $this->argument('repo');        $workflow = (string) $this->argument('workflow');        $request = new CreateWorkflowDispatchEventRequest(            owner: $owner,            repo: $repo,            workflow: $workflow,        );        $request->withTokenAuth(            token: (string) config('services.github.token'),        );        if ($this->hasArgument('branch')) {            $request->setData(                data: ['ref' => $this->argument('branch')],            );        }        $this->info(            string: "Requesting a new workflow dispatch for {$owner}/{$repo} using workflow: {$workflow}",        );        $response = $request->send();        if ($response->failed()) {            throw $response->toException();        }        $this->info(            string: 'Request was accepted by GitHub',        );        return self::SUCCESS;    }}

就像在我们有签名和描述之前一样，这次我们的签名有一个可选的分支，以防我们想要覆盖请求中的默认值。所以在我们的处理方法中，我们可以简单地检查输入是否有参数 branch，如果有，我们可以解析它并为请求设置数据。然后我们向 CLI 提供一些反馈，让用户知道我们在做什么 - 并发送请求。如果此时一切顺利，我们可以简单地输出一条消息，通知用户 GitHub 接受了请求。但是，如果出现问题，我们希望抛出特定的异常，至少在开发过程中是这样。

最后一个请求的主要警告是，我们的工作流程设置为通过在工作流程中添加一个新的 on 项目来由 webhook 触发：