Micronaut 内置 Endpoints

将管理依赖项添加到您的项目后，默认情况下会启用以下内置端点：

此外，以下内置端点由管理依赖项提供，但默认情况下未启用：

定义 endpoints.all.sensitive: false 可以打开所有端点以进行未经身份验证的访问，但这应该谨慎使用，因为私人和敏感信息将被暴露。

管理端口

默认情况下，所有管理端点都通过与应用程序相同的端口公开。您可以通过指定 endpoints.all.port 设置来更改此行为：

endpoints.all.port=8085

endpoints:
  all:
    port: 8085

[endpoints]
  [endpoints.all]
    port=8085

endpoints {
  all {
    port = 8085
  }
}

{
  endpoints {
    all {
      port = 8085
    }
  }
}

{
  "endpoints": {
    "all": {
      "port": 8085
    }
  }
}

在上面的示例中，管理端点仅通过端口 8085 公开。

JMX

Micronaut 提供了使用 JMX 注册端点的功能。请参阅有关 JMX 的部分以开始使用。

Beans 端点

beans 端点返回有关应用程序中加载的 bean 定义的信息。默认返回的bean数据是一个对象，其中键是bean定义类名，值是关于bean的属性的对象。

要执行 beans 端点，请向 /beans 发送 GET 请求。

配置

要配置 beans 端点，请通过 endpoints.beans 提供配置。

Beans 端点配置示例

endpoints.beans.enabled=Boolean
endpoints.beans.sensitive=Boolean

endpoints:
  beans:
    enabled: Boolean
    sensitive: Boolean

[endpoints]
  [endpoints.beans]
    enabled="Boolean"
    sensitive="Boolean"

endpoints {
  beans {
    enabled = "Boolean"
    sensitive = "Boolean"
  }
}

{
  endpoints {
    beans {
      enabled = "Boolean"
      sensitive = "Boolean"
    }
  }
}

{
  "endpoints": {
    "beans": {
      "enabled": "Boolean",
      "sensitive": "Boolean"
    }
  }
}

自定义

beans 端点由 bean 定义数据收集器和 bean 数据实现组成。 bean 定义数据收集器 (BeanDefinitionDataCollector) 负责返回一个发布者，该发布者返回响应中使用的数据。 bean 定义数据 (BeanDefinitionData) 负责返回有关单个 bean 定义的数据。

要覆盖任一帮助器类的默认行为，要么扩展默认实现（DefaultBeanDefinitionDataCollector、DefaultBeanDefinitionData），要么直接实现相关接口。为确保使用您的实现而不是默认实现，请将 @Replaces 注释添加到您的类中，并将值为默认实现。

信息端点

info 端点从应用程序的状态返回静态信息。公开的信息可以由任意数量的“信息源”提供。

要执行信息端点，请向 /info 发送 GET 请求。

配置

要配置信息端点，请通过 endpoints.info 提供配置。

信息端点配置示例

endpoints.info.enabled=Boolean
endpoints.info.sensitive=Boolean

endpoints:
  info:
    enabled: Boolean
    sensitive: Boolean

[endpoints]
  [endpoints.info]
    enabled="Boolean"
    sensitive="Boolean"

endpoints {
  info {
    enabled = "Boolean"
    sensitive = "Boolean"
  }
}

{
  endpoints {
    info {
      enabled = "Boolean"
      sensitive = "Boolean"
    }
  }
}

{
  "endpoints": {
    "info": {
      "enabled": "Boolean",
      "sensitive": "Boolean"
    }
  }
}

自定义

信息端点由信息聚合器和任意数量的信息源组成。要添加信息源，请创建一个实现 InfoSource 的 bean 类。如果您的信息源需要从 Java 属性文件中检索数据，请扩展 PropertiesInfoSource 接口，该接口为此提供了一个辅助方法。

所有信息源 bean 都与信息聚合器一起收集。要提供您自己的信息聚合器实现，请创建一个实现 InfoAggregator 的类并将其注册为 bean。为确保使用您的实现而不是默认实现，请将 @Replaces 注释添加到您的类中，并将值为默认实现。

默认信息聚合器返回一个映射，其中包含所有信息源返回的组合属性。该地图以 JSON 形式从 /info 端点返回。

提供的信息来源

配置信息源

ConfigurationInfoSource 返回 info 键下的配置属性。除了字符串、整数和布尔值之外，更复杂的属性可以在 JSON 输出中作为映射公开（如果配置格式支持的话）。

Info Source Example (application.groovy)

info.demo.string = "demo string"
info.demo.number = 123
info.demo.map = [key: 'value', other_key: 123]

上面的配置导致来自 info 端点的以下 JSON 响应：

{
  "demo": {
    "string": "demo string",
    "number": 123,
    "map": {
      "key": "value",
      "other_key": 123
    }
  }
}

配置

可以使用 endpoints.info.config.enabled 属性禁用配置信息源。

Git 信息源

如果 git.properties 文件在类路径上可用，则 GitInfoSource 会在 git 键下公开该文件中的值。生成 git.properties 文件必须配置为构建的一部分。 Gradle 用户的一个简单选择是 Gradle Git Properties Plugin。 Maven 用户可以使用 Maven Git Commit ID Plugin。

配置

要指定属性文件的备用路径或名称，请在 endpoints.info.git.location 属性中提供自定义值。

可以使用 endpoints.info.git.enabled 属性禁用 git 信息源。

构建信息源

如果 META-INF/build-info.properties 文件在类路径上可用，则 BuildInfoSource 会在构建键下公开该文件中的值。生成 build-info.properties 文件必须配置为构建的一部分。 Gradle 用户的一个简单选择是 Gradle 构建信息插件。 Maven 用户的一个选项是 Spring Boot Maven 插件

配置

要指定属性文件的备用路径/名称，请在 endpoints.info.build.location 属性中提供自定义值。

可以使用 endpoints.info.build.enabled 属性禁用构建信息源。

健康端点

健康端点返回有关应用程序“健康”的信息，该信息由任意数量的“健康指标”决定。

要执行健康端点，请向 /health 发送 GET 请求。此外，health 端点公开了 /health/liveness 和 /health/readiness 健康指标。

配置

要配置健康端点，请通过 endpoints.health 提供配置。

Health Endpoint Configuration Example

endpoints.health.enabled=Boolean
endpoints.health.sensitive=Boolean
endpoints.health.details-visible=String
endpoints.health.status.http-mapping=Map<String, HttpStatus>

endpoints:
  health:
    enabled: Boolean
    sensitive: Boolean
    details-visible: String
    status:
      http-mapping: Map<String, HttpStatus>

[endpoints]
  [endpoints.health]
    enabled="Boolean"
    sensitive="Boolean"
    details-visible="String"
    [endpoints.health.status]
      http-mapping="Map<String, HttpStatus>"

endpoints {
  health {
    enabled = "Boolean"
    sensitive = "Boolean"
    detailsVisible = "String"
    status {
      httpMapping = "Map<String, HttpStatus>"
    }
  }
}

{
  endpoints {
    health {
      enabled = "Boolean"
      sensitive = "Boolean"
      details-visible = "String"
      status {
        http-mapping = "Map<String, HttpStatus>"
      }
    }
  }
}

{
  "endpoints": {
    "health": {
      "enabled": "Boolean",
      "sensitive": "Boolean",
      "details-visible": "String",
      "status": {
        "http-mapping": "Map<String, HttpStatus>"
      }
    }
  }
}

• details-visible 是 DetailsVisibility 之一

details-visible 设置控制是否向未通过身份验证的用户公开健康详细信息。

例如，设置：

Using details-visible

endpoints.health.details-visible=ANONYMOUS

endpoints:
  health:
    details-visible: ANONYMOUS

[endpoints]
  [endpoints.health]
    details-visible="ANONYMOUS"

endpoints {
  health {
    detailsVisible = "ANONYMOUS"
  }
}

{
  endpoints {
    health {
      details-visible = "ANONYMOUS"
    }
  }
}

{
  "endpoints": {
    "health": {
      "details-visible": "ANONYMOUS"
    }
  }
}

向匿名未经身份验证的用户公开有关应用程序健康状态的各种健康指标的详细信息。

endpoints.health.status.http-mapping 设置控制为每个健康状态返回哪些状态代码。下表描述了默认值：

您可以在配置文件中提供自定义映射（例如 application.yml）：

Custom Health Status Codes

endpoints.health.status.http-mapping.DOWN=200

endpoints:
  health:
    status:
      http-mapping:
        DOWN: 200

[endpoints]
  [endpoints.health]
    [endpoints.health.status]
      [endpoints.health.status.http-mapping]
        DOWN=200

endpoints {
  health {
    status {
      httpMapping {
        DOWN = 200
      }
    }
  }
}

{
  endpoints {
    health {
      status {
        http-mapping {
          DOWN = 200
        }
      }
    }
  }
}

{
  "endpoints": {
    "health": {
      "status": {
        "http-mapping": {
          "DOWN": 200
        }
      }
    }
  }
}

即使 HealthStatus 为 DOWN，上面的代码也会返回 OK (200)。

自定义

健康端点由健康聚合器和任意数量的健康指标组成。要添加健康指示器，请创建一个实现 HealthIndicator 的 bean 类。建议同时使用 @Liveness 或 @Readiness 限定符。如果不使用限定符，则健康指标将成为 /health 和 /health/readiness 端点的一部分。基类 AbstractHealthIndicator 可用于子类化以简化该过程。

所有健康指示器 bean 都与健康聚合器一起收集。要提供您自己的健康聚合器实现，请创建一个实现 HealthAggregator 的类并将其注册为 bean。为确保使用您的实现而不是默认实现，请将 @Replaces 注释添加到您的类中，并将值为默认实现 DefaultHealthAggregator。

默认运行状况聚合器返回根据指标的运行状况计算的总体状态。健康状况由几条信息组成。

“最差”状态作为整体状态返回。选择非运行状态而不是运行状态。选择较高的严重性而不是较低的严重性。

提供的指标

Micronaut 提供的所有健康指标都暴露在 /health 和 /health/readiness 端点上。

磁盘空间

提供了一个健康指标，它根据可用磁盘空间量确定应用程序的健康状况。可以在 endpoints.health.disk-space 键下提供磁盘空间健康指示器的配置。

Disk Space Indicator Configuration Example

endpoints.health.disk-space.enabled=Boolean
endpoints.health.disk-space.path=String
endpoints.health.disk-space.threshold=String | Long

endpoints:
  health:
    disk-space:
      enabled: Boolean
      path: String
      threshold: String | Long

[endpoints]
  [endpoints.health]
    [endpoints.health.disk-space]
      enabled="Boolean"
      path="String"
      threshold="String | Long"

endpoints {
  health {
    diskSpace {
      enabled = "Boolean"
      path = "String"
      threshold = "String | Long"
    }
  }
}

{
  endpoints {
    health {
      disk-space {
        enabled = "Boolean"
        path = "String"
        threshold = "String | Long"
      }
    }
  }
}

{
  "endpoints": {
    "health": {
      "disk-space": {
        "enabled": "Boolean",
        "path": "String",
        "threshold": "String | Long"
      }
    }
  }
}

• path 指定用于确定磁盘空间的路径

• 阈值指定最小可用空间量

阈值可以作为字符串提供，例如“10MB”或“200KB”，或字节数。

JDBC

JDBC 健康指标根据在应用程序上下文中成功创建到数据源的连接的能力来确定应用程序的健康状况。唯一支持的配置选项是通过 endpoints.health.jdbc.enabled 键启用或禁用指示器。

Discovery Client

如果您的应用程序使用服务发现，则会包含一个健康指示器来监控发现客户端的健康状况。返回的数据可以包括可用服务的列表。

指标端点

Micronaut 可以通过与 Micrometer 集成来公开应用程序指标。

使用 CLI

如果您使用 Micronaut CLI 创建您的项目，请提供其中一个千分尺功能以启用指标并在您的项目中预配置选定的注册表。例如：

$ mn create-app my-app --features micrometer-atlas

指标端点返回有关应用程序“指标”的信息。要执行指标端点，请向 /metrics 发送 GET 请求。这将返回可用指标名称的列表。

您可以使用 /metrics/[name] 获取特定指标，例如 /metrics/jvm.memory.used。

刷新端点

刷新端点刷新应用程序状态，导致上下文中的所有 Refreshable bean 被销毁并在进一步请求时重新实例化。这是通过在 Application Context 中发布 RefreshEvent 来完成的。

要执行刷新端点，请将 POST 请求发送到 /refresh。

$ curl -X POST http://localhost:8080/refresh

在没有正文的情况下执行时，端点首先刷新环境并执行差异以检测任何更改，然后仅在检测到更改时才执行刷新。要跳过此检查并刷新所有 @Refreshable bean 而不管环境更改（例如，强制刷新来自第三方服务的缓存响应），请在 POST 请求正文中添加一个 force 参数。

$ curl -X POST http://localhost:8080/refresh -H 'Content-Type: application/json' -d '{"force": true}'

配置

要配置刷新端点，请通过 endpoints.refresh 提供配置。

Beans Endpoint Configuration Example

endpoints.refresh.enabled=Boolean
endpoints.refresh.sensitive=Boolean

endpoints:
  refresh:
    enabled: Boolean
    sensitive: Boolean

[endpoints]
  [endpoints.refresh]
    enabled="Boolean"
    sensitive="Boolean"

endpoints {
  refresh {
    enabled = "Boolean"
    sensitive = "Boolean"
  }
}

{
  endpoints {
    refresh {
      enabled = "Boolean"
      sensitive = "Boolean"
    }
  }
}

{
  "endpoints": {
    "refresh": {
      "enabled": "Boolean",
      "sensitive": "Boolean"
    }
  }
}

路由端点

routes 端点返回有关可供您的应用程序调用的 URI 的信息。默认情况下，返回的数据包括 URI、允许的方法、生成的内容类型以及有关将要执行的方法的信息。

要执行路由端点，请向 /routes 发送 GET 请求。

配置

要配置路由端点，请通过 endpoints.routes 提供配置。

Routes Endpoint Configuration Example

endpoints.routes.enabled=Boolean
endpoints.routes.sensitive=Boolean

endpoints:
  routes:
    enabled: Boolean
    sensitive: Boolean

[endpoints]
  [endpoints.routes]
    enabled="Boolean"
    sensitive="Boolean"

endpoints {
  routes {
    enabled = "Boolean"
    sensitive = "Boolean"
  }
}

{
  endpoints {
    routes {
      enabled = "Boolean"
      sensitive = "Boolean"
    }
  }
}

{
  "endpoints": {
    "routes": {
      "enabled": "Boolean",
      "sensitive": "Boolean"
    }
  }
}

自定义

路由端点由路由数据收集器和路由数据实现组成。路由数据收集器（RouteDataCollector）负责返回一个发布者，该发布者返回响应中使用的数据。路线数据（RouteData）负责返回有关单个路线的数据。

要覆盖任一帮助器类的默认行为，请扩展默认实现（DefaultRouteDataCollector、DefaultRouteData），或直接实现相关接口。为确保使用您的实现而不是默认实现，请将 @Replaces 注释添加到您的类中，并将值为默认实现。

记录器端点

记录器端点返回有关应用程序中可用记录器的信息，并允许配置它们的日志级别。

默认情况下禁用记录器端点，必须使用设置 endpoints.loggers.enabled=true 显式启用。

要按名称及其配置的有效日志级别获取所有记录器的集合，请向 /loggers 发送 GET 请求。这也提供了可用日志级别的列表。

$ curl http://localhost:8080/loggers

{
    "levels": [
        "ALL", "TRACE", "DEBUG", "INFO", "WARN", "ERROR", "OFF", "NOT_SPECIFIED"
    ],
    "loggers": {
        "ROOT": {
            "configuredLevel": "INFO",
            "effectiveLevel": "INFO"
        },
        "io": {
            "configuredLevel": "NOT_SPECIFIED",
            "effectiveLevel": "INFO"
        },
        "io.micronaut": {
            "configuredLevel": "NOT_SPECIFIED",
            "effectiveLevel": "INFO"
        },
        // etc...
    }
}

要获取特定记录器的日志级别，请在 GET 请求中包含记录器名称。例如，要访问记录器“io.micronaut.http”的日志级别：

$ curl http://localhost:8080/loggers/io.micronaut.http

{
    "configuredLevel": "NOT_SPECIFIED",
    "effectiveLevel": "INFO"
}

如果指定的记录器不存在，则会使用未指定（即 NOT_SPECIFIED）配置的日志级别创建它（其有效日志级别通常是根记录器的级别）。

要更新单个记录器的日志级别，请向指定的记录器 URL 发送 POST 请求，并包含一个提供要配置的日志级别的正文。

$ curl -i -X POST \
       -H "Content-Type: application/json" \
       -d '{ "configuredLevel": "ERROR" }' \
       http://localhost:8080/loggers/ROOT

HTTP/1.1 200 OK

$ curl http://localhost:8080/loggers/ROOT

{
    "configuredLevel": "ERROR",
    "effectiveLevel": "ERROR"
}

配置

要配置记录器端点，请通过 endpoints.loggers 提供配置。

Loggers Endpoint Configuration Example

endpoints.loggers.enabled=Boolean
endpoints.loggers.sensitive=Boolean

endpoints:
  loggers:
    enabled: Boolean
    sensitive: Boolean

[endpoints]
  [endpoints.loggers]
    enabled="Boolean"
    sensitive="Boolean"

endpoints {
  loggers {
    enabled = "Boolean"
    sensitive = "Boolean"
  }
}

{
  endpoints {
    loggers {
      enabled = "Boolean"
      sensitive = "Boolean"
    }
  }
}

{
  "endpoints": {
    "loggers": {
      "enabled": "Boolean",
      "sensitive": "Boolean"
    }
  }
}

默认情况下，端点不允许未经授权的用户更改日志级别（即使 sensitive 设置为 false）。要允许这样做，您必须将 endpoints.loggers.write-sensitive 设置为 false。

自定义

记录器端点由两个可自定义的部分组成：LoggersManager 和 LoggingSystem。有关自定义日志系统的信息，请参阅文档的日志记录部分。

LoggersManager 负责检索和设置日志级别。如果默认实现不足以满足您的用例，只需提供您自己的实现并将 DefaultLoggersManager 替换为 @Replaces 注释。

缓存端点

缓存端点文档可在 micronaut-cache 项目中获得。

服务器停止端点

停止端点关闭应用程序服务器。

要执行停止端点，请向 /stop 发送 POST 请求。

配置

要配置停止端点，请通过 endpoints.stop 提供配置。

Stop Endpoint Configuration Example

endpoints.stop.enabled=Boolean
endpoints.stop.sensitive=Boolean

endpoints:
  stop:
    enabled: Boolean
    sensitive: Boolean

[endpoints]
  [endpoints.stop]
    enabled="Boolean"
    sensitive="Boolean"

endpoints {
  stop {
    enabled = "Boolean"
    sensitive = "Boolean"
  }
}

{
  endpoints {
    stop {
      enabled = "Boolean"
      sensitive = "Boolean"
    }
  }
}

{
  "endpoints": {
    "stop": {
      "enabled": "Boolean",
      "sensitive": "Boolean"
    }
  }
}

默认情况下，停止端点被禁用，必须明确启用才能使用。

环境端点

环境端点返回有关环境及其 PropertySources 的信息。

配置

要启用和配置环境端点，请通过 endpoints.env 提供配置。

Environment Endpoint Configuration Example

endpoints.env.enabled=Boolean
endpoints.env.sensitive=Boolean

endpoints:
  env:
    enabled: Boolean
    sensitive: Boolean

[endpoints]
  [endpoints.env]
    enabled="Boolean"
    sensitive="Boolean"

endpoints {
  env {
    enabled = "Boolean"
    sensitive = "Boolean"
  }
}

{
  endpoints {
    env {
      enabled = "Boolean"
      sensitive = "Boolean"
    }
  }
}

{
  "endpoints": {
    "env": {
      "enabled": "Boolean",
      "sensitive": "Boolean"
    }
  }
}

• 启用默认为 false，敏感默认为 true

默认情况下，端点将屏蔽所有值。要自定义此屏蔽，您需要提供一个实现 EnvironmentEndpointFilter 的 Bean。

第一个示例将屏蔽所有值，但前缀为 safe 的值除外

First example of environment masking

@Singleton
public class OnlySafePrefixedEnvFilter implements EnvironmentEndpointFilter {
    private static final Pattern SAFE_PREFIX_PATTERN = Pattern.compile("safe.*", Pattern.CASE_INSENSITIVE);

    @Override
    public void specifyFiltering(@NotNull EnvironmentFilterSpecification specification) {
        specification
                .maskAll() // All values will be masked apart from the supplied patterns
                .exclude(SAFE_PREFIX_PATTERN);
    }
}

也可以使用 maskNone-- 允许纯文本中的所有值，然后指定将被屏蔽的名称模式，即：

Deny instead of allow

@Singleton
public class AllPlainExceptSecretOrMatchEnvFilter implements EnvironmentEndpointFilter {
    // Mask anything starting with `sekrt`
    private static final Pattern SECRET_PREFIX_PATTERN = Pattern.compile("sekrt.*", Pattern.CASE_INSENSITIVE);

    // Mask anything exactly matching `exact-match`
    private static final String EXACT_MATCH = "exact-match";

    // Mask anything that starts with `private.`
    private static final Predicate<String> PREDICATE_MATCH = name -> name.startsWith("private.");

    @Override
    public void specifyFiltering(@NotNull EnvironmentFilterSpecification specification) {
        specification
                .maskNone() // All values will be in plain-text apart from the supplied patterns
                .exclude(SECRET_PREFIX_PATTERN)
                .exclude(EXACT_MATCH)
                .exclude(PREDICATE_MATCH);
    }
}

可以通过调用 legacyMasking-- 方法来应用合理的默认值。这将显示除名称中任何位置包含密码、凭据、证书、密钥、秘密或令牌的单词之外的所有值。

获取有关环境的信息

要执行端点，请向 /env 发送 GET 请求。

获取有关特定 PropertySource 的信息

要执行端点，请向 /env/{propertySourceName} 发送 GET 请求。

ThreadDump 端点

threaddump 端点返回有关应用程序中运行的线程的信息。

要执行 threaddump 端点，请向 /threaddump 发送 GET 请求。

配置

要配置 threaddump 端点，请通过 endpoints.threaddump 提供配置。

Threaddump Endpoint Configuration Example

endpoints.threaddump.enabled=Boolean
endpoints.threaddump.sensitive=Boolean

endpoints:
  threaddump:
    enabled: Boolean
    sensitive: Boolean

[endpoints]
  [endpoints.threaddump]
    enabled="Boolean"
    sensitive="Boolean"

endpoints {
  threaddump {
    enabled = "Boolean"
    sensitive = "Boolean"
  }
}

{
  endpoints {
    threaddump {
      enabled = "Boolean"
      sensitive = "Boolean"
    }
  }
}

{
  "endpoints": {
    "threaddump": {
      "enabled": "Boolean",
      "sensitive": "Boolean"
    }
  }
}

自定义

线程转储端点委托给 ThreadInfoMapper)，它负责将 java.lang.management.ThreadInfo 对象转换为任何其他要发送以进行序列化的对象。