Micronaut 创建 Endpoints

2023-03-14 14:28 更新

除了内置端点之外,管理依赖项还提供对创建自定义端点的支持。这些可以像内置端点一样启用和配置,并可用于检索和返回任何指标或其他应用程序数据。

端点注解

可以通过使用端点注释对类进行注释并为其提供(至少)端点 ID 来创建端点。

FooEndpoint.java

@Endpoint("foo")
class FooEndpoint {
    ...
}

如果向注解提供了单个字符串参数,则将其用作端点 ID。

可以为注释提供额外的(命名的)参数。 @Endpoint 的其他可能参数如下表所述:

表 1. 端点参数
参数 描述 端点示例

String id

端点 ID(或名称)

@Endpoint(id = "foo")

String prefix

用于配置端点的前缀

@Endpoint(prefix = "foo")

boolean defaultEnabled

设置在未设置配置时是否启用端点

@Endpoint(defaultEnabled = false)

boolean defaultSensitive

如果未设置配置,则设置端点是否敏感

@Endpoint(defaultSensitive = false)

自定义端点示例

以下示例端点类创建一个可在 /date 访问的端点:

CurrentDateEndpoint

 Java Groovy  Kotlin 
import io.micronaut.management.endpoint.annotation.Endpoint;

@Endpoint(id = "date",
          prefix = "custom",
          defaultEnabled = true,
          defaultSensitive = false)
public class CurrentDateEndpoint {

//.. endpoint methods

}
import io.micronaut.management.endpoint.annotation.Endpoint

@Endpoint(id = "date",
          prefix = "custom",
          defaultEnabled = true,
          defaultSensitive = false)
class CurrentDateEndpoint {

//.. endpoint methods

}
import io.micronaut.management.endpoint.annotation.Endpoint

@Endpoint(id = "date", prefix = "custom", defaultEnabled = true, defaultSensitive = false)
class CurrentDateEndpoint {

//.. endpoint methods

}

端点方法

端点响应 GET(“读取”)、POST(“写入”)和 DELETE(“删除”)请求。要从端点返回响应,请使用以下注释之一对其公共方法进行注释:

表 1. 端点方法注解
注解 描述

Read

响应 GET 请求

Write

响应 POST 请求

Delete

响应 DELETE 请求

读取方法

使用 Read 注释注释方法会导致它响应 GET 请求。

CurrentDateEndpoint

 Java Groovy  Kotlin 
import io.micronaut.management.endpoint.annotation.Endpoint;

import io.micronaut.management.endpoint.annotation.Read;

@Endpoint(id = "date",
          prefix = "custom",
          defaultEnabled = true,
          defaultSensitive = false)
public class CurrentDateEndpoint {

private Date currentDate;

@Read
public Date currentDate() {
    return currentDate;
}

}
import io.micronaut.management.endpoint.annotation.Endpoint

import io.micronaut.management.endpoint.annotation.Read

@Endpoint(id = "date",
          prefix = "custom",
          defaultEnabled = true,
          defaultSensitive = false)
class CurrentDateEndpoint {

private Date currentDate

@Read
Date currentDate() {
    currentDate
}

}
import io.micronaut.management.endpoint.annotation.Endpoint

import io.micronaut.management.endpoint.annotation.Read

@Endpoint(id = "date", prefix = "custom", defaultEnabled = true, defaultSensitive = false)
class CurrentDateEndpoint {

private var currentDate: Date? = null

@Read
fun currentDate(): Date? {
    return currentDate
}

}

上述方法响应以下请求:

$ curl -X GET localhost:55838/date

1526085903689

Read 注释接受一个可选的 produces 参数,它设置从方法返回的媒体类型(默认为 application/json):

CurrentDateEndpoint

 Java Groovy  Kotlin 
import io.micronaut.management.endpoint.annotation.Endpoint;

import io.micronaut.management.endpoint.annotation.Read;

import io.micronaut.http.MediaType;
import io.micronaut.management.endpoint.annotation.Selector;

@Endpoint(id = "date",
          prefix = "custom",
          defaultEnabled = true,
          defaultSensitive = false)
public class CurrentDateEndpoint {

private Date currentDate;

@Read(produces = MediaType.TEXT_PLAIN) //(1)
public String currentDatePrefix(@Selector String prefix) {
    return prefix + ": " + currentDate;
}

}
import io.micronaut.management.endpoint.annotation.Endpoint

import io.micronaut.management.endpoint.annotation.Read

import io.micronaut.http.MediaType
import io.micronaut.management.endpoint.annotation.Selector

@Endpoint(id = "date",
          prefix = "custom",
          defaultEnabled = true,
          defaultSensitive = false)
class CurrentDateEndpoint {

private Date currentDate

@Read(produces = MediaType.TEXT_PLAIN) //(1)
String currentDatePrefix(@Selector String prefix) {
    "$prefix: $currentDate"
}

}
import io.micronaut.management.endpoint.annotation.Endpoint

import io.micronaut.management.endpoint.annotation.Read

import io.micronaut.http.MediaType
import io.micronaut.management.endpoint.annotation.Selector

@Endpoint(id = "date", prefix = "custom", defaultEnabled = true, defaultSensitive = false)
class CurrentDateEndpoint {

private var currentDate: Date? = null

@Read(produces = [MediaType.TEXT_PLAIN]) //(1)
fun currentDatePrefix(@Selector prefix: String): String {
    return "$prefix: $currentDate"
}

}
  1. 支持的媒体类型由 MediaType 表示

上述方法响应以下请求:

$ curl -X GET localhost:8080/date/the_date_is

the_date_is: Fri May 11 19:24:21 CDT

写方法

使用 Write 注释对方法进行注释会导致它响应 POST 请求。

CurrentDateEndpoint

 Java Groovy  Kotlin 
import io.micronaut.management.endpoint.annotation.Endpoint;

import io.micronaut.management.endpoint.annotation.Write;

import io.micronaut.http.MediaType;
import io.micronaut.management.endpoint.annotation.Selector;

@Endpoint(id = "date",
          prefix = "custom",
          defaultEnabled = true,
          defaultSensitive = false)
public class CurrentDateEndpoint {

private Date currentDate;

@Write
public String reset() {
    currentDate = new Date();

    return "Current date reset";
}

}
import io.micronaut.management.endpoint.annotation.Endpoint

import io.micronaut.management.endpoint.annotation.Write

import io.micronaut.http.MediaType
import io.micronaut.management.endpoint.annotation.Selector

@Endpoint(id = "date",
          prefix = "custom",
          defaultEnabled = true,
          defaultSensitive = false)
class CurrentDateEndpoint {

private Date currentDate

@Write
String reset() {
    currentDate = new Date()

    return "Current date reset"
}

}
import io.micronaut.management.endpoint.annotation.Endpoint

import io.micronaut.management.endpoint.annotation.Write

import io.micronaut.http.MediaType
import io.micronaut.management.endpoint.annotation.Selector

@Endpoint(id = "date", prefix = "custom", defaultEnabled = true, defaultSensitive = false)
class CurrentDateEndpoint {

private var currentDate: Date? = null

@Write
fun reset(): String {
    currentDate = Date()

    return "Current date reset"
}

}

上述方法响应以下请求:

$ curl -X POST http://localhost:39357/date

Current date reset

Write 注释接受一个可选的 consumes 参数,它设置该方法接受的媒体类型(默认为 application/json):

MessageEndpoint

 Java Groovy  Kotlin 
import io.micronaut.context.annotation.Requires;
import io.micronaut.management.endpoint.annotation.Endpoint;

import io.micronaut.management.endpoint.annotation.Write;

import io.micronaut.http.MediaType;

@Endpoint(id = "message", defaultSensitive = false)
public class MessageEndpoint {

String message;

@Write(consumes = MediaType.APPLICATION_FORM_URLENCODED, produces = MediaType.TEXT_PLAIN)
public String updateMessage(String newMessage) {
    this.message = newMessage;

    return "Message updated";
}

}
import io.micronaut.management.endpoint.annotation.Endpoint

import io.micronaut.management.endpoint.annotation.Write

import io.micronaut.http.MediaType

@Endpoint(id = "message", defaultSensitive = false)
class MessageEndpoint {

String message

@Write(consumes = MediaType.APPLICATION_FORM_URLENCODED, produces = MediaType.TEXT_PLAIN)
String updateMessage(String newMessage) {  //(1)
    message = newMessage

    return "Message updated"
}

}
import io.micronaut.context.annotation.Requires
import io.micronaut.management.endpoint.annotation.Endpoint

import io.micronaut.management.endpoint.annotation.Write

import io.micronaut.http.MediaType

@Endpoint(id = "message", defaultSensitive = false)
class MessageEndpoint {

internal var message: String? = null

@Write(consumes = [MediaType.APPLICATION_FORM_URLENCODED], produces = [MediaType.TEXT_PLAIN])
fun updateMessage(newMessage: String): String {  //(1)
    this.message = newMessage

    return "Message updated"
}

}

上述方法响应以下请求:

$ curl -X POST http://localhost:65013/message -H 'Content-Type: application/x-www-form-urlencoded' -d newMessage=A new message'

Message updated

删除方法

使用 Delete 注释对方法进行注释会导致它响应 DELETE 请求。

MessageEndpoint

 Java Groovy  Kotlin 
import io.micronaut.context.annotation.Requires;
import io.micronaut.management.endpoint.annotation.Endpoint;

import io.micronaut.management.endpoint.annotation.Delete;

@Endpoint(id = "message", defaultSensitive = false)
public class MessageEndpoint {

String message;

@Delete
public String deleteMessage() {
    this.message = null;

    return "Message deleted";
}

}
import io.micronaut.management.endpoint.annotation.Endpoint

import io.micronaut.management.endpoint.annotation.Delete

@Endpoint(id = "message", defaultSensitive = false)
class MessageEndpoint {

String message

@Delete
String deleteMessage() {
    message = null

    return "Message deleted"
}

}
import io.micronaut.context.annotation.Requires
import io.micronaut.management.endpoint.annotation.Endpoint

import io.micronaut.management.endpoint.annotation.Delete

@Endpoint(id = "message", defaultSensitive = false)
class MessageEndpoint {

internal var message: String? = null

@Delete
fun deleteMessage(): String {
    this.message = null

    return "Message deleted"
}

}

上述方法响应以下请求:

$ curl -X DELETE http://localhost:65013/message

Message deleted

端点敏感度

可以通过端点注释和配置来控制整个端点的端点敏感性。但是,各个方法可以独立于端点作为一个整体进行配置。 @Sensitive 注释可以应用于方法以控制它们的敏感性。

AlertsEndpoint

 Java Groovy  Kotlin 
import io.micronaut.http.MediaType;
import io.micronaut.management.endpoint.annotation.Delete;
import io.micronaut.management.endpoint.annotation.Endpoint;
import io.micronaut.management.endpoint.annotation.Read;
import io.micronaut.management.endpoint.annotation.Sensitive;
import io.micronaut.management.endpoint.annotation.Write;

import java.util.List;
import java.util.concurrent.CopyOnWriteArrayList;

@Endpoint(id = "alerts", defaultSensitive = false) // (1)
public class AlertsEndpoint {

    private final List<String> alerts = new CopyOnWriteArrayList<>();

    @Read
    List<String> getAlerts() {
        return alerts;
    }

    @Delete
    @Sensitive(true)  // (2)
    void clearAlerts() {
        alerts.clear();
    }

    @Write(consumes = MediaType.TEXT_PLAIN)
    @Sensitive(property = "add.sensitive", defaultValue = true) // (3)
    void addAlert(String alert) {
        alerts.add(alert);
    }
}
import io.micronaut.http.MediaType
import io.micronaut.management.endpoint.annotation.Delete
import io.micronaut.management.endpoint.annotation.Endpoint
import io.micronaut.management.endpoint.annotation.Read
import io.micronaut.management.endpoint.annotation.Sensitive
import io.micronaut.management.endpoint.annotation.Write

import java.util.concurrent.CopyOnWriteArrayList

@Endpoint(id = "alerts", defaultSensitive = false) // (1)
class AlertsEndpoint {

    private final List<String> alerts = new CopyOnWriteArrayList<>();

    @Read
    List<String> getAlerts() {
        alerts
    }

    @Delete
    @Sensitive(true) // (2)
    void clearAlerts() {
        alerts.clear()
    }

    @Write(consumes = MediaType.TEXT_PLAIN)
    @Sensitive(property = "add.sensitive", defaultValue = true) // (3)
    void addAlert(String alert) {
        alerts << alert
    }
}
import io.micronaut.http.MediaType
import io.micronaut.management.endpoint.annotation.Delete
import io.micronaut.management.endpoint.annotation.Endpoint
import io.micronaut.management.endpoint.annotation.Read
import io.micronaut.management.endpoint.annotation.Sensitive
import io.micronaut.management.endpoint.annotation.Write
import java.util.concurrent.CopyOnWriteArrayList

@Endpoint(id = "alerts", defaultSensitive = false) // (1)
class AlertsEndpoint {

    private val alerts: MutableList<String> = CopyOnWriteArrayList()

    @Read
    fun getAlerts(): List<String> {
        return alerts
    }

    @Delete
    @Sensitive(true)  // (2)
    fun clearAlerts() {
        alerts.clear()
    }

    @Write(consumes = [MediaType.TEXT_PLAIN])
    @Sensitive(property = "add.sensitive", defaultValue = true)  // (3)
    fun addAlert(alert: String) {
        alerts.add(alert)
    }
}
  1. 端点默认不敏感,使用端点的默认前缀。

  2. 无论任何其他因素如何,此方法始终是敏感的

  3. 属性值附加到前缀和 id 以查找配置值

如果设置了配置键 endpoints.alerts.add.sensitive,则该值决定了 addAlert 方法的敏感度。

  1. 端点是第一个标记,因为它是端点注释中前缀的默认值,并且未在此示例中明确设置。

  2. alerts 是下一个标记,因为那是端点 ID

  3. add.sensitive 是下一个标记,因为它是为 @Sensitive 注释的属性成员设置的值。

如果未设置配置键,则使用 defaultValue(默认为 true)。

端点配置

具有 endpoints 前缀的端点可以通过其默认端点 ID 进行配置。如果存在 ID 为 foo 的端点,则可以通过 endpoints.foo 对其进行配置。此外,可以通过 all 前缀提供默认值。

例如,考虑以下端点。

FooEndpoint.java

@Endpoint("foo")
class FooEndpoint {
    ...
}

默认情况下,端点已启用。要禁用它,请将 endpoints.foo.enabled 设置为 false。如果未设置 endpoints.foo.enabled 且 endpoints.all.enabled 为 false,则端点将被禁用。

端点的配置值覆盖所有端点的配置值。如果 endpoints.foo.enabled 为 true 而 endpoints.all.enabled 为 false,端点将被启用。

对于所有端点,可以设置以下配置值。

 Properties Yaml  Toml  Groovy  Hocon  JSON 
endpoints.<any endpoint id>.enabled=Boolean
endpoints.<any endpoint id>.sensitive=Boolean
endpoints:
  <any endpoint id>:
    enabled: Boolean
    sensitive: Boolean
[endpoints]
  sensitive="Boolean"
endpoints {
  <any endpoint id> {
    enabled = "Boolean"
    sensitive = "Boolean"
  }
}
{
  endpoints {
    <any endpoint id> {
      enabled = "Boolean"
      sensitive = "Boolean"
    }
  }
}
{
  "endpoints": {
    "<any endpoint id>": {
      "enabled": "Boolean",
      "sensitive": "Boolean"
    }
  }
}

默认情况下,所有端点的基本路径都是 /。如果您希望端点在不同的基本路径下可用,请配置 endpoints.all.path。例如,如果该值设置为 /endpoints/,则可以在 /endpoints/foo 相对于上下文路径访问 foo 端点。请注意,除非设置了 micronaut.server.context-path,否则 endpoints.all.path 需要前导和尾随 /,在这种情况下,前导 / 不是必需的。


以上内容是否对您有帮助:
在线笔记
App下载
App下载

扫描二维码

下载编程狮App

公众号
微信公众号

编程狮公众号