README

⚠️ 此包不再维护。考虑使用 Oh Dear。

Laravel API Health

这是一个用于监控应用使用的第一方和第三方服务的包。如果某个服务出现故障（或恢复正常），它可以发送通知，并支持定时任务。您可以为任何要监控的API或服务创建检查器，但也内置了一些检查器，以便您可以快速启动检查器。

赞助此包

我们自豪地通过开发和免费提供Laravel包来支持社区。跟踪问题和拉取请求需要时间，但我们很高兴提供帮助！如果此包为您节省了时间，或者您在专业上依赖它，请考虑支持维护和开发。

要求

支持 Laravel 8.0 和 9.0。
需要 PHP 7.4 或更高版本。
支持包发现。

功能

内置 HTTP 和 SSL 证书检查器
您可以构建自己的检查器
它可以安排检查器
自动重试失败的检查器
发送关于失败的检查器的通知
当失败的检查器恢复时发送通知
缓存检查器的状态
您可以在代码中获取检查器的状态
它可以在控制台中打印检查器的状态
按检查器自定义通知（可选）
能够模拟 ApiHealth 外观以测试您的应用程序

安装

您可以通过 composer 安装此包

composer require pbmedia/laravel-api-health

如果您仍在使用 Laravel 5.6，请使用版本 1.2；对于 Laravel 5.7，请使用版本 2.0；对于 Laravel 5.8，请使用版本 3.0。旧版本不再维护。

使用 Artisan CLI 工具发布翻译资源和配置文件。

php artisan vendor:publish --provider="ProtoneMedia\ApiHealth\ApiHealthServiceProvider"

升级到 v5

命名空间已更改为 ProtoneMedia\ApiHealth。请相应地更新您的代码。

构建您的第一个检查器

让我们创建第一个检查器。假设您想请求一个URL并验证响应的状态码是否在200范围内。您可以使用make:checker命令自行构建这个检查器，但我们已经为您预建了一个。打开终端，让我们创建一个HTTP检查器！

php artisan make:http-checker LaravelDocumentationChecker

在您的app文件夹中，您将找到一个名为Checkers的新文件夹，其中包含您刚创建的检查器。您需要做的只是将$url属性调整为您的需求。

<?php

namespace App\Checkers;

use GuzzleHttp\Client;
use Illuminate\Console\Scheduling\Event;
use ProtoneMedia\ApiHealth\Checkers\AbstractHttpChecker;

class LaravelDocumentationChecker extends AbstractHttpChecker
{
    /*
     * The URL you want to request.
     */
    protected $url = 'https://laravel.net.cn/docs/6.0';

    /*
     * The method you want to use.
     */
    protected $method = 'GET';

    /*
     * Here you can specify the Guzzle HTTP options.
     *
     * @return \ProtoneMedia\ApiHealth\Checkers\AbstractHttpChecker
     */
    public static function create()
    {
        return new static(new Client, [
            // 'headers' => [
            //     'X-Foo' => ['Bar', 'Baz'],
            // ],
            // 'json'    => ['foo' => 'bar'],
            // 'timeout' => 5,
        ]);
    }

    /**
     * Defines the checker's schedule.
     *
     * @param  \Illuminate\Console\Scheduling\Event  $event
     * @return null
     */
    public function schedule(Event $event)
    {
        $event->everyMinute();

        // $event->evenInMaintenanceMode();
        // $event->onOneServer();
    }
}

现在，我们可以使用以下命令在控制台中运行此检查器：

php artisan api-health:check App\\Checkers\\LaravelDocumentationChecker

安排您的检查器

您可以在config/api-health.php文件中的checkers数组中填充您要安排的所有检查器。默认情况下，每个检查器每分钟运行一次。检查器的schedule方法允许您设置与Laravel任务调度器类似的频率。

<?php

return [
    'checkers' => [
        \App\Checkers\LaravelDocumentationChecker::class,
    ],

    //
];

在您的编辑器中打开App\Console\Kernel类，并添加api-health:run-checkers命令，将其设置为everyMinute()。如果您不使用Laravel的任务调度器，也可以手动创建一个每分钟运行一次的cronjob。api-health:run-checkers命令将根据配置的安排确定应该运行哪些检查器，如果您想忽略调度并运行所有检查器，只需使用带有--force选项的命令即可。

<?php

namespace App\Console;

use Illuminate\Console\Scheduling\Schedule;
use Illuminate\Foundation\Console\Kernel as ConsoleKernel;

class Kernel extends ConsoleKernel
{
    //

    protected function schedule(Schedule $schedule)
    {
        $schedule->command('api-health:run-checkers')->everyMinute();
    }

    //
}

检查器的结果将被缓存，但每次在控制台中运行检查器时都会刷新。这样，您可以在PHP代码中获取缓存的結果。这对于检查服务是否在线而不必等待结果非常棒。

例如，您可能在应用程序中使用支付网关。如果您通过调度器每分钟检查一次网关的状态，您可以在UI中非常准确地响应该状态。您可以使用ApiHealth外观获取检查器的状态。如果您不想使用缓存，可以使用fresh方法来忽略存储的状态。

use App\Checkers\LaravelDocumentationChecker;
use ProtoneMedia\ApiHealth\Facades\ApiHealth;

ApiHealth::isFailing(LaravelDocumentationChecker::class);
ApiHealth::isPassing(LaravelDocumentationChecker::class);

ApiHealth::fresh()->isFailing(LaravelDocumentationChecker::class);
ApiHealth::fresh()->isPassing(LaravelDocumentationChecker::class);

创建您自己的检查器

构建检查器非常简单。运行make:checker命令，并将检查器的名称作为参数传递。

php artisan make:checker GetIpAddressByHost

您需要填写两个方法。create方法用作工厂，用于构建和配置您的检查器实例。在这种情况下，它非常简单，但这是收集和配置依赖的地方。run方法执行实际的检查，如果出现问题，必须抛出\ProtoneMedia\ApiHealth\Checkers\CheckerHasFailed异常。以下是一个示例：

<?php

namespace App\Checkers;

use Illuminate\Console\Scheduling\Event;
use ProtoneMedia\ApiHealth\Checkers\AbstractChecker;
use ProtoneMedia\ApiHealth\Checkers\CheckerHasFailed;

class GetIpAddressByHost extends AbstractChecker
{
    public static function create()
    {
        return new static;
    }

    public function schedule(Event $event)
    {
        $event->everyMinute();
    }

    public function run()
    {
        $ip = gethostbyname('www.protone.media');

        if (!filter_var($ip, FILTER_VALIDATE_IP)) {
            throw new CheckerHasFailed("Host www.protone.media did not return a valid IP Address.");
        }
    }
}

事件

此包派发了不同的事件

ProtoneMedia\ApiHealth\Events\CheckerHasFailed
ProtoneMedia\ApiHealth\Events\CheckerHasRecovered
ProtoneMedia\ApiHealth\Events\CheckerIsStillFailing

其他内置检查器

make:ssl-certificate-checker - SSL证书验证（使用spatie/ssl-certificate！)

通知选项

配置文件有一个通知部分，允许您配置通道并更改可通知类。有两个默认通知，CheckerHasFailed和CheckerHasRecovered，您可以在配置文件中用您自己的通知替换它们。还有一个选项在几分钟后重新发送CheckerHasFailed通知。

<?php

return [
    //

    'notifications' => [
        /**
         *  Number of minutes until send the failed notification again.
         */
        'resend_failed_notification_after_minutes' => 60,

        /**
         * Class name of the failed notification.
         */
        'default_failed_notification' => \ProtoneMedia\ApiHealth\Notifications\CheckerHasFailed::class,

        /**
         * Class name of the recovered notification.
         */
        'default_recovered_notification' => \ProtoneMedia\ApiHealth\Notifications\CheckerHasRecovered::class,
    ],

    //
]

您还可以按检查器设置这些通知选项（针对每个检查器）。只需修改您检查器的这些属性，软件包就会完成剩余工作

<?php

class MyChecker extends AbstractChecker
{
    protected $resendFailedNotificationAfterMinutes = 30;

    protected $failedNotificationClass = \App\Notifications\Whoops::class;

    protected $recoveredNotificationClass \App\Notifications\Yay::class;
}

自动重试

您可以在检查器进入失败状态之前指定重试次数。当发生重试时，一个作业会被发送到队列，该队列将再次运行检查器。在配置文件中，您可以设置重试次数、要分发的作业（我们已经为您创建了一个！）以及重试作业的配置，例如连接、延迟和队列。

例如，如果您将allowed_retries设置为3，将delay设置为20，检查器将总共运行四次，并在一分钟内失败（从您第一次运行检查器的时间开始计算）。

<?php

// config/api-health.php

return [
    //

    'retries' => [
        /**
         * The number of allowed retries.
         */
        'allowed_retries' => 0,

        /**
         * Here you can specify the configuration of the retry job.
         */
        'job' => [
            'job' => \ProtoneMedia\ApiHealth\Jobs\RetryChecker::class,

            'connection' => null,

            'delay' => null,

            'queue' => null,
        ],
    ],

    //
]

就像通知选项一样，您可以按检查器设置允许的重试次数和作业的类。如果您想在作业被发送到队列之前与之交互，可以使用withRetryJob方法。此方法接收作业，允许您在实际发送作业之前调用其任何方法

<?php

class MyChecker extends AbstractChecker
{
    protected $allowedRetries = 2;

    protected $retryJob = \App\Jobs\RetryChecker::class;

    public function withRetryJob($job)
    {
        $job->delay(now()->addMinutes(3));
    }
}

高级

每个检查器都应该能够识别自己以便存储状态。《AbstractChecker》有一个《id》方法，它简单地返回类的名称，在大多数情况下，您不需要担心标识符，但有一种场景需要您重写此方法。比如说，您想使用不同的参数重复使用一个检查器。在这个例子中有一个《Server》模型，它有一个《isOnline》方法。

class Server extends Model
{
    public function isOnline(): bool
    {
        //
    }
}

我们使用《make:checker ServerChecker》命令生成了这个检查器，并添加了一个自定义的《id》方法。

<?php

namespace App\Checkers;

use App\Models\Server;
use ProtoneMedia\ApiHealth\Checkers\AbstractChecker;
use ProtoneMedia\ApiHealth\Checkers\CheckerHasFailed;

class ServerChecker extends AbstractChecker
{
    public $server;

    public function __construct(Server $server)
    {
        $this->server = $server;
    }

    public static function create(Server $server)
    {
        return new static($server);
    }

    public function id(): string
    {
        return 'server_' . $this->server->id;
    }

    public function run()
    {
        if (!$this->server->isOnline()) {
            throw new CheckerHasFailed("Server {$this->server->name} is offline.");
        }
    }
}

现在，如果您想验证多个服务器的状态，可以轻松地做类似这样的事情

<?php

use App\Models\Server;
use ProtoneMedia\ApiHealth\Runner;

$serverA = Server::whereIpAddress('1.1.1.1')->first();
$serverB = Server::whereIpAddress('8.8.8.8')->first();

$runner = new Runner([$serverA, $serverB]);

// or

$runner = new Runner(Server::all());

$onlineServers = $runner->passes();
$offlineServers = $runner->failed();

编写测试

ApiHealth外观有fake方法，该方法将绑定实例与一个假实例交换。这允许您强制检查器的状态。请注意，这仅在外观上有效，检查器本身将不受影响。

<?php

namespace App\Tests;

use App\Checkers\FailingChecker;
use App\Checkers\PassingChecker;
use ProtoneMedia\ApiHealth\Facades\ApiHealth;

class MyTest extends TestCase
{
    /** @test */
    public function it_can_make_the_passing_checker_fail()
    {
        ApiHealth::fake();

        ApiHealth::mustFail(PassingChecker::class);
        ApiHealth::mustPass(FailingChecker::class);

        $this->assertTrue(ApiHealth::isFailing(PassingChecker::class));
        $this->assertTrue(ApiHealth::isPassing(FailingChecker::class));
    }
}

测试

composer test

其他Laravel包

Laravel Analytics Event Tracking：一个Laravel包，可以轻松地将事件发送到Google Analytics。
Laravel Blade On Demand：一个Laravel包，用于在内存中编译Blade模板。
Laravel Cross Eloquent Search：一个Laravel包，可以搜索多个Eloquent模型。
Laravel Eloquent Scope as Select：停止在PHP中重复Eloquent查询范围和约束。此包允许您通过添加子查询来重复使用您的查询范围和约束。
Laravel Eloquent Where Not：此Laravel包允许您翻转/反转Eloquent范围或任何查询约束。
Laravel FFMpeg：此包为Laravel提供了与FFmpeg的集成。文件的存储由Laravel的文件系统处理。
Laravel Form Components：使用 Tailwind CSS 自定义表单和 Bootstrap 4 快速构建表单的 Blade 组件。支持验证、模型绑定、默认值、多语言支持，包括默认供应商样式和完全可自定义！
Laravel Mixins：一系列 Laravel 精美工具。
Laravel Paddle：支持 webhooks/events 的 Laravel 与 Paddle.com API 集成。
Laravel Verify New Email：此包增加了对新邮箱地址的验证支持：当用户更新其邮箱地址时，只有在新邮箱地址被验证后，才会替换旧的邮箱地址。
Laravel WebDAV：Laravel 文件系统中的 WebDAV 驱动。

变更日志

请参阅 CHANGELOG 了解最近的变化。

贡献

请参阅 CONTRIBUTING 了解详细信息。

安全

如果您发现任何安全相关的问题，请通过邮箱 code@protone.media 反馈，而不是使用问题跟踪器。

致谢

许可证

MIT 许可证（MIT）。请参阅许可证文件获取更多信息。

pbmedia / laravel-api-health

维护者

详细信息