47. Endpoints

Actuator 端点允许您监视应用程序并与之交互。 Spring Boot 包含许多内置端点，您也可以添加自己的端点。例如，health端点提供基本的应用程序运行状况信息。

端点公开的方式取决于您选择的技术类型。大多数应用程序选择 HTTP 监视，其中端点的 IDMap 到 URL。例如，默认情况下，health端点将 Map 到/health。

下列技术不可知的端点可用：

如果您使用的是 Spring MVC，那么还可以使用以下附加端点：

47.1 自定义端点

可以使用 Spring 属性自定义端点。您可以更改端点是否为enabled，端点是否为sensitive甚至是id。

例如，这是一个application.properties，它更改beans端点的敏感度和 id 并启用shutdown。

endpoints.beans.id=springbeans
endpoints.beans.sensitive=false
endpoints.shutdown.enabled=true

默认情况下，除shutdown之外的所有端点均处于启用状态。如果您希望专门启用“启用”端点，则可以使用endpoints.enabled属性。例如，以下将禁用* 以外的所有端点info：

endpoints.enabled=false
endpoints.info.enabled=true

同样，您也可以选择全局设置所有端点的“敏感”标志。默认情况下，敏感标志取决于端点的类型(请参见上表)。例如，将所有端点标记为除info之外的其他敏感端点：

endpoints.sensitive=true
endpoints.info.sensitive=false

47.2ActuatorMVC 端点的超媒体

如果endpoints.hypermedia.enabled设置为true且Spring HATEOAS在 Classpath 上(例如，通过spring-boot-starter-hateoas或如果使用Spring Data REST)，则来自 Actuator 的 HTTP 端点将通过超媒体链接进行增强，并添加一个“发现页面”，其中包含指向所有端点。默认情况下，“发现页面”在/actuator上可用。它作为端点实现，允许使用属性来配置其路径(endpoints.actuator.path)以及是否启用它(endpoints.actuator.enabled)。

配置了自定义 Management 上下文路径后，“发现页面”将自动从/actuator移到 Management 上下文的根目录。例如，如果 Management 上下文路径为/management，则可以从/management访问发现页面。

如果HAL Browser通过其 webjar(org.webjars:hal-browser)或spring-data-rest-hal-browser在 Classpath 中，则还将提供 HAL 浏览器形式的 HTML“发现页面”。

47.3 CORS 支持

跨域资源共享(CORS)是W3C specification，它使您可以灵活地指定授权哪种跨域请求。可以将 Actuator 的 MVC 端点配置为支持此类方案。

默认情况下，CORS 支持是禁用的，只有在设置endpoints.cors.allowed-origins属性后才启用。以下配置允许来自example.com域的GET和POST调用：

endpoints.cors.allowed-origins=http://example.com
endpoints.cors.allowed-methods=GET,POST

47.4 添加自定义端点

如果添加类型@Bean的@Bean，它将通过 JMX 和 HTTP 自动公开(如果有可用的服务器)。通过创建MvcEndpoint类型的 Bean，可以进一步自定义 HTTP 端点。您的MvcEndpoint不是@Controller，但可以使用@RequestMapping(和@Managed*)公开资源。

47.5 健康信息

健康信息可用于检查正在运行的应用程序的状态。监视软件通常使用它来警告生产系统出现故障的人。 health终结点公开的默认信息取决于如何访问它。对于安全应用程序中未经身份验证的连接，将返回简单的“状态”消息，对于经过身份验证的连接，还将显示其他详细信息(有关 HTTP 详细信息，请参阅第 48.7 节“ HTTP 运行状况端点格式和访问限制”)。

健康信息是从ApplicationContext中定义的所有HealthIndicator bean 中收集的。 Spring Boot 包含许多自动配置的HealthIndicators，您也可以编写自己的。默认情况下，最终的系统状态由HealthAggregator派生，该HealthAggregator根据状态的有序列表对每个HealthIndicator的状态进行排序。排序列表中的第一个状态用作整体运行状况。如果没有HealthIndicator返回HealthAggregator已知的状态，则使用UNKNOWN状态。

47.6 健康 Metrics 的安全性

HealthIndicators返回的信息本质上通常有些敏感。例如，您可能不想将数据库服务器的详细信息发布给全世界。因此，默认情况下，仅健康状态通过未经身份验证的 HTTP 连接公开。如果您希望始终获得完整的健康信息，可以将endpoints.health.sensitive设置为false。

健康响应也被缓存以防止“拒绝服务”攻击。如果要更改默认的缓存时间 1000 毫秒，请使用endpoints.health.time-to-live属性。

47.6.1 自动配置的健康 Metrics

适当时，Spring Boot 会自动配置以下HealthIndicators：

47.6.2 编写自定义健康 Metrics

要提供自定义健康信息，您可以注册实现HealthIndicator接口的 Spring bean。您需要提供health()方法的实现并返回Health响应。 Health响应应包含状态，并且可以选择包含要显示的其他详细信息。

import org.springframework.boot.actuate.health.Health;
import org.springframework.boot.actuate.health.HealthIndicator;
import org.springframework.stereotype.Component;

@Component
public class MyHealthIndicator implements HealthIndicator {

    @Override
    public Health health() {
        int errorCode = check(); // perform some specific health check
        if (errorCode != 0) {
            return Health.down().withDetail("Error Code", errorCode).build();
        }
        return Health.up().build();
    }

}

除了 Spring Boot 的 sched 义Status类型之外，Health还可以返回表示新系统状态的自定义Status。在这种情况下，还需要提供HealthAggregator接口的自定义实现，或者必须使用management.health.status.order配置属性来配置默认实现。

例如，假设在您的HealthIndicator实现中使用的是新的Status代码为FATAL。要配置严重性 Sequences，请在应用程序属性中添加以下内容：

management.health.status.order=FATAL, DOWN, OUT_OF_SERVICE, UNKNOWN, UP

响应中的 HTTP 状态代码反映了总体健康状态(例如UPMap 到 200，OUT_OF_SERVICE或DOWNMap 到 503)。如果通过 HTTP 访问运行状况终结点，则可能还需要向HealthMvcEndpoint注册自定义状态 Map。例如，以下 MapFATAL到 503(服务不可用)：

endpoints.health.mapping.FATAL=503

内置状态的默认状态 Map 为：

47.7 申请信息

应用程序信息公开了从ApplicationContext中定义的所有InfoContributor bean 中收集的各种信息。 Spring Boot 包含许多自动配置的InfoContributors，您也可以编写自己的。

47.7.1 自动配置的信息贡献者

适当时，Spring Boot 会自动配置以下InfoContributors：

47.7.2 自定义应用程序信息信息

您可以通过设置info.* Spring 属性来自定义info终结点公开的数据。 info 键下的所有Environment属性将自动显示。例如，您可以将以下内容添加到application.properties：

info.app.encoding=UTF-8
info.app.java.source=1.8
info.app.java.target=1.8

info.app.encoding[emailprotected]@
info.app.java.source[emailprotected]@
info.app.java.target[emailprotected]@

47.7.3 Git 提交信息

info端点的另一个有用功能是，它可以在项目构建时发布有关git源代码存储库状态的信息。如果GitProperties bean 可用，则将公开git.branch，git.commit.id和git.commit.time属性。

如果要显示完整的 git 信息(即git.properties的完整内容)，请使用management.info.git.mode属性：

management.info.git.mode=full

47.7.4 生成信息

如果BuildProperties bean 可用，则info端点也可以发布有关您的构建的信息。如果META-INF/build-info.properties文件在 Classpath 中可用，则会发生这种情况。

47.7.5 编写自定义 InfoContributor

要提供自定义应用程序信息，您可以注册实现InfoContributor接口的 Spring bean。

下面的示例使用单个值贡献一个example条目：

import java.util.Collections;

import org.springframework.boot.actuate.info.Info;
import org.springframework.boot.actuate.info.InfoContributor;
import org.springframework.stereotype.Component;

@Component
public class ExampleInfoContributor implements InfoContributor {

    @Override
    public void contribute(Info.Builder builder) {
        builder.withDetail("example",
                Collections.singletonMap("key", "value"));
    }

}

如果您点击了info端点，则应该看到包含以下附加条目的响应：

{
    "example": {
        "key" : "value"
    }
}