中文翻译站
This is not an official quarkus or red hat maintained site. 此站点不是 quarkus / red hat 官方维护站点，官网请浏览 quarkus.io

Quarkus - MicroProfile 健康检查

本指南展示 Quarkus 应用程序如何通过 SmallRye Health extension 实现 MicroProfile Health 规范。

MicroProfile Health 可以让应用程序向外部查看者提供关于他们状态 的信息，这在云端环境中通常是有用的，在这种环境中必须能够自动确定应用程序是否应该丢弃 或重新启动。

必备条件

要完成本指南，您需要：

  • 小于 15 分钟

  • an IDE

  • 用 JAVA_HOME 正确配置安装了JDK 1.8+

  • Apache Maven 3.6.2+

结构

本指南， 我们构建了一个简单的 REST 应用程序，它将按 MicroProfile Health 标准暴露在 /health/live 和 /health/ready 接口。

成果

我们建议您在下面的章节中遵循指示，一步一步创建 应用程序。 但是你也可以直接跳到已完成的例子。

克隆 Git 仓库: git clone https://github.com/quarkusio/quarkus-quickstarts.git, 或下载 压缩包

代码在 microprofile-health-quickstart 目录.

创建Maven项目

第一，我们需要一个新项目。 通过以下命令创建一个新项目：

mvn io.quarkus:quarkus-maven-plugin:1.3.1.Final:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=microprofile-health-quickstart \
    -Dextensions="health"
cd microprofile-health-quickstart

此命令生成一个 Maven 项目，导入了 smallrye-health 扩展 ，Quarkus 用它实现了 MicroProfile Health 标准。

执行健康检查

导入 smallrye-health extension 直接公开了三个 REST 接口：

  • /health/live - 应用程序正运行中。

  • /health/ready - 应用程序已准备好服务请求。

  • /health - 在应用程序中累积所有健康检查程序。

检查 smallrye-health extension 是否如预期那样工作：

所有健康检测 REST 接口都返回了一个简单的 JSON 对象，包含两个字段：

  • status - 所有健康检查程序的总体结果

  • checks —— 一组独立检查

健康检查的一般的 status 是所有 声明的健康检查程序逻辑与的结果。 checks 数组是空的，因为我们还没有指定 任何健康检查程序，所以让我们来定义一些检查程序。

创建您的第一个健康检查

在本节中，我们创建了我们第一个简单的健康检查程序。

创建 org.acme.microprofile.health.SimpleHealthCheck 类：

package org.acme.microprofile.health;

import org.eclipse.microprofile.health.HealthCheck;
import org.eclipse.microprofile.health.HealthCheckResponse;
import org.eclipse.microprofile.health.Liveness;

import javax.enterprise.context.ApplicationScoped;

@Liveness
@ApplicationScoped
public class SimpleHealthCheck implements HealthCheck {

    @Override
    public HealthCheckResponse call() {
        return HealthCheckResponse.up("Simple health check");
    }
}

你可以看到健康检查程序被定义为 实现 HealthCheck 接口，且用一些 CDI 注解过的 CDI beans ︰

  • @Liveness - 可在 /health/live 中检查是否存活

  • @Readiness - 在 /health/ready 中检查是否准备就绪。

HealthCheck 是一个功能接口，其单个方法 call 返回一个 HealthCheckResponse 对象，这个对象可以很容易地通过生成器 API 构造。

当我们以 dev 模式启动 Quarkus 应用程序时，只需通过刷新您的浏览器窗口 就可以重复请求 http://localhost:8080/health/live ， 或使用 curl http://localhost:8080/health/live. Because we defined our health check to be a liveness procedure (with @Liveness qualifier) the new health check procedure is now present in the checks array.

恭喜！ 您已经创建了第一个 Quarkus 健康检查程序。 让我们 继续探索通过 MicroProfile Health 标准可以做些什么。

添加就绪健康检查程序

前一节，我们创建了一个简单的存活检查程序，它的状态表明我们的应用程序有没有运行。 在本节中， 我们将创建一个就绪健康检查，它将能够说明我们的应用程序是否能够处理 请求。

我们将创建另一个健康检查程序，模拟与外部服务连接，例如数据库。 首先，我们将总是返回显示应用程序的响应已就绪。

创建 org.acme.microprofile.health.DatabaseConnectionHealthCheck 类：

package org.acme.microprofile.health;

import org.eclipse.microprofile.health.HealthCheck;
import org.eclipse.microprofile.health.HealthCheckResponse;
import org.eclipse.microprofile.health.Readiness;

import javax.enterprise.context.ApplicationScoped;

@Readiness
@ApplicationScoped
public class DatabaseConnectionHealthCheck implements HealthCheck {

    @Override
    public HealthCheckResponse call() {
        return HealthCheckResponse.up("Database connection health check");
    }
}

如果您现在重新运行在 http://localhost:8080/health/live 上的健康检查，则 checks 将只包含先前定义的 SimpleHealthCheck ，因为它是唯一使用 @Liveness 定义的 检查。 然而， 如果您访问 http://localhost:8080/health/ready (在浏览器或 curl http://localhost:8080/health/ready)，您将只看到 Database connection health check ，因为它是唯一通过 @Readiness 作为准备健康检查程序定义的。

如果您访问 http://localhost:8080/health ，您将得到两个检查。

应该使用哪种健康检查程序的更多信息在 MicroProfile Health 标准中。 一般情况，存活检查 程序决定是否应重新启动应用程序，而就绪检查 程序决定是否能将应用程序与请求联通起来。

Negative health check procedures

在本节中， 我们使用 选项扩展我们的 Database 连接健康检查 ，表示我们的应用程序无法处理请求，因为无法建立底层的 数据库连接。 简单起见， 检测数据库是否可用时只是通过配置属性控制。

更新 org.acme.microprofile.health.DatabaseConnectionHealthCheck 类：

package org.acme.microprofile.health;

import org.eclipse.microprofile.config.inject.ConfigProperty;
import org.eclipse.microprofile.health.HealthCheck;
import org.eclipse.microprofile.health.HealthCheckResponse;
import org.eclipse.microprofile.health.HealthCheckResponseBuilder;
import org.eclipse.microprofile.health.Readiness;

import javax.enterprise.context.ApplicationScoped;

@Readiness
@ApplicationScoped
public class DatabaseConnectionHealthCheck implements HealthCheck {

    @ConfigProperty(name = "database.up", defaultValue = "false")
    private boolean databaseUp;

    @Override
    public HealthCheckResponse call() {

        HealthCheckResponseBuilder responseBuilder = HealthCheckResponse.named("Database connection health check");

        try {
            simulateDatabaseConnectionVerification();
            responseBuilder.up();
        } catch (IllegalStateException e) {
            // cannot access the database
            responseBuilder.down();
        }

        return responseBuilder.build();
    }

    private void simulateDatabaseConnectionVerification() {
        if (!databaseUp) {
            throw new IllegalStateException("Cannot contact database");
        }
    }
}
直到现在，我们都使用了一种简化方法，通过 HealthCheckResponse#up(String) 来构建一个 HealthCheckResponse 直接生成响应对象 (还有 HealthCheckResponse#down(String))。 从现在起，我们使用 HealthCheckResponseBuilder 类提供的完整生成器功能。

如果您现在重新运行就绪状态健康检查(在 http://localhost:8080/health/ready) 整个 status 应该是 DOWN 。 您也可以在 http://localhost:8080/health/live 存活检查中看到 status UP ，因为 它不受就绪状态检查的影响。

由于我们不应让应用程序处于 DOWN 状态， 因为我们正在以开发模式运行 Quarkus，您可以在 src/main/resources/application.properties 中添加 database.up=true 并重新运行就绪健康检查 - 它应该再次变成 up.

添加用户特定数据到健康检查响应

在前面的章节中，我们看到了如何创建简单的健康检查，只有最小的 属性， 即健康检查名称及其状态 (UP 或 DOWN )。 然而， MicroProfile 标准也为应用程序提供了一种方式，通过键值对形式发送任意数据到消费端。 可以通过健康检查响应构造 API 的 withData(key, value) 方法实现。

让我们创建一个新的健康检查程序 org.acme.microprofile.health.DataHealthCheck：

package org.acme.microprofile.health;

import org.eclipse.microprofile.health.Liveness;
import org.eclipse.microprofile.health.HealthCheck;
import org.eclipse.microprofile.health.HealthCheckResponse;

import javax.enterprise.context.ApplicationScoped;

@Liveness
@ApplicationScoped
public class DataHealthCheck implements HealthCheck {

    @Override
    public HealthCheckResponse call() {
        return HealthCheckResponse.named("Health check with data")
                .up()
                .withData("foo", "fooValue")
                .withData("bar", "barValue")
                .build();
    }
}

如果您通过访问 /health/live 来重新运行存活检查程序，您可以看到 checks 数组中出现了新的健康检查 Health check with data 里存在 。 这次检查包含一个叫做 data 的新属性，它是一个 JSON 对象，由我们在健康检查程序中定义的属性组成。

这个功能在故障情景中特别有用，您可以通过 在健康检查响应中传入错误内容。

        try {
            simulateDatabaseConnectionVerification();
            responseBuilder.up();
        } catch (IllegalStateException e) {
            // cannot access the database
            responseBuilder.down()
                    .withData("error", e.getMessage()); // pass the exception message
        }

Extension 健康检查

某些扩展可能提供了默认的健康检查，引入扩展将自动注册其健康检查。

例如，用于管理 Quarkus 数据源的 quarkus-agroal 自动注册一个就绪健康检查 来验证每个数据源：Datasource 健康检查 。

您可以通过属性 quarkus.health.extensions.enabled 禁用 extension 健康检查，确保不自动注册。

结论

MicroProfile Health 为您的应用提供了一种方法来传播关于其健康状态的信息 以说明它是否能够正常运作。 存活检查(Liveness) 用来判断应用程序是否应该重新启动， 就绪检查(readiness) 用来判断应用程序是否能够处理请求。

Quarkus 中启用 MicroProfile Health 所有需要做的：

  • 使用 quarkus-maven-plugin 添加 smallrye-health Quarkus extension 到项目:

./mvnw quarkus:add-extension -Dextensions="health"

  • 或只是添加以下Maven 依赖关系：

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-smallrye-health</artifactId>
</dependency>

配置参考

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property

Type

Default

quarkus.health.extensions.enabled

Whether or not extensions published health check should be enabled.

boolean

true

quarkus.smallrye-health.root-path

Root path for health-checking servlets.

string

/health

quarkus.smallrye-health.liveness-path

The relative path of the liveness health-checking servlet.

string

/live

quarkus.smallrye-health.readiness-path

The relative path of the readiness health-checking servlet.

string

/ready

Quarkus is open. All dependencies of this project are available under the Apache Software License 2.0 or compatible license.

This website was built with Jekyll is hosted on Github Pages and is completely open source. If you want to make it better, fork the website and show us what you’ve got.

Navigation
Contribute
Get Help
Quarkus is made of community projects
CC by 3.0 | Privacy Policy Sponsored by
quarkus.pro 是基于 quarkus.io 的非官方中文翻译站 ，最后更新 2020/04 。
沪ICP备19006215号-8
QQ交流群：1055930959
微信群: