Spring Docs

主题

Actuator API ​

/gateway Actuator 端点允许你监控 Spring Cloud Gateway 应用程序并与之交互。

默认情况下，/gateway 端点是禁用的。要启用该端点，你需要在应用程序属性中将其访问权限设置为 read-only（只读）或 unrestricted（不受限），并将其 通过 HTTP 或 JMX 暴露。

以下清单显示了如何进行配置：

application.properties

properties
management.endpoint.gateway.access=read-only
management.endpoints.web.exposure.include=gateway

警告

建议你将 management.endpoint.gateway.access 设置为 read-only。这将禁用刷新、创建和删除路由的能力。如果你需要通过 Actuator 端点创建、刷新和删除路由，则需要将 management.endpoint.gateway.access 设置为 unrestricted 或设置 management.endpoint.gateway.enabled=true。 如果你启用了通过 Actuator 端点创建、删除和刷新路由的功能，则应采取适当措施确保 Actuator 端点的安全性。

该端点提供了子 Actuator 端点及其可用方法的概览。响应结果类似于以下内容：

json
[
   {
      "href":"/actuator/gateway/",
      "methods":[ "GET" ]
   },
   {
      "href":"/actuator/gateway/routedefinitions",
      "methods":[ "GET" ]
   },
   {
      "href":"/actuator/gateway/globalfilters",
      "methods":[ "GET" ]
   },
   {
      "href":"/actuator/gateway/routefilters",
      "methods":[ "GET" ]
   },
   {
      "href":"/actuator/gateway/routes",
      "methods":[ "POST", "GET" ]
   },
   {
      "href":"/actuator/gateway/routepredicates",
      "methods":[ "GET" ]
   },
   {
      "href":"/actuator/gateway/refresh",
      "methods":[ "POST" ]
   },
   {
      "href":"/actuator/gateway/routes/route-id-1/combinedfilters",
      "methods":[ "GET" ]
   },
   {
      "href":"/actuator/gateway/routes/route-id-1",
      "methods":[ "POST", "DELETE", "GET" ]
   }
]

1. 详细 Actuator 格式 (Verbose Actuator Format) ​

Spring Cloud Gateway 添加了一种新的、更详细的格式。它为每条路由添加了更多细节，允许你查看与每条路由相关的断言（Predicates）和过滤器（Filters），以及任何可用的配置。

以下是 /actuator/gateway/routes 的示例输出：

json
[
  {
    "predicate": "(Hosts: [**.addrequestheader.org] && Paths: [/headers], match trailing slash: true)",
    "route_id": "add_request_header_test",
    "filters": [
      "[[AddResponseHeader X-Response-Default-Foo = 'Default-Bar'], order = 1]",
      "[[AddRequestHeader X-Request-Foo = 'Bar'], order = 1]",
      "[[PrefixPath prefix = '/httpbin'], order = 2]"
    ],
    "uri": "lb://testservice",
    "order": 0
  }
]

此功能默认启用。要禁用它，请设置以下属性：

application.properties

properties
spring.cloud.gateway.actuator.verbose.enabled=false

在未来的版本中，此属性的默认值将保持为 true。

2. 获取路由过滤器 (Retrieving Route Filters) ​

本节详细介绍了如何检索路由过滤器，包括：

  • 全局过滤器
  • 路由过滤器

全局过滤器 (Global Filters) ​

要获取应用于所有路由的全局过滤器，请向 /actuator/gateway/globalfilters 发送 GET 请求。响应结果类似于以下内容：

json
{
  "org.springframework.cloud.gateway.filter.ReactiveLoadBalancerClientFilter@77856cc5": 10100,
  "org.springframework.cloud.gateway.filter.RouteToRequestUrlFilter@4f6fd101": 10000,
  "org.springframework.cloud.gateway.filter.NettyWriteResponseFilter@32d22650": -1,
  "org.springframework.cloud.gateway.filter.ForwardRoutingFilter@106459d9": 2147483647,
  "org.springframework.cloud.gateway.filter.NettyRoutingFilter@1fbd5e0": 2147483647,
  "org.springframework.cloud.gateway.filter.ForwardPathFilter@33a71d23": 0,
  "org.springframework.cloud.gateway.filter.AdaptCachedBodyGlobalFilter@135064ea": 2147483637,
  "org.springframework.cloud.gateway.filter.WebsocketRoutingFilter@23c05889": 2147483646
}

响应包含已就绪的全局过滤器的详细信息。对于每个全局过滤器，都有该过滤器对象的字符串表示形式（例如 org.springframework.cloud.gateway.filter.ReactiveLoadBalancerClientFilter@77856cc5）以及在过滤器链中相应的顺序 (Order)。

路由过滤器 (Route Filters) ​

要检索应用于路由的 GatewayFilter 工厂，请向 /actuator/gateway/routefilters 发起 GET 请求。其结果类似于如下响应：

json
{
  "[AddRequestHeaderGatewayFilterFactory@570ed9c configClass = AbstractNameValueGatewayFilterFactory.NameValueConfig]": null,
  "[SecureHeadersGatewayFilterFactory@fceab5d configClass = Object]": null,
  "[SaveSessionGatewayFilterFactory@4449b273 configClass = Object]": null
}

该响应包含应用于特定路由的 GatewayFilter 工厂的详细信息。对每个工厂，都有对应对象的字符串表示（如 [SecureHeadersGatewayFilterFactory@fceab5d configClass = Object]）。注意 null 值是由于端点控制器的实现不完整（它试图设置对象在过滤器链中的顺序，而这并不适用于 GatewayFilter 工厂对象）。

3. 刷新路由缓存 (Refreshing the Route Cache) ​

要清除路由缓存，请请求 /actuator/gateway/refresh 的 POST 方法。该请求返回 200 响应，且不带响应体。

要清除具有特定元数据值的路由，可以提供 Query 参数 metadata 来指定要匹配的路由对应的 key:value 键值对。如果在异步刷新过程中产生错误，刷新操作将不会修改现有路由。

发送 POST /actuator/gateway/refresh?metadata=group:group-1 的请求将只刷新 group 元数据为 group-1 的路由：first_route 和 third_route。

json
[{
  "route_id": "first_route",
  "route_object": {
    "predicate": "...",
  },
  "metadata": { "group": "group-1" }
},
{
  "route_id": "second_route",
  "route_object": {
    "predicate": "...",
  },
  "metadata": { "group": "group-2" }
},
{
  "route_id": "third_route",
  "route_object": {
    "predicate": "...",
  },
  "metadata": { "group": "group-1" }
}]

4. 获取网关中定义的路由 ​

要检索网关中定义的路由，请向 /actuator/gateway/routes 发起 GET 请求。响应结果如下所示：

json
[{
  "route_id": "first_route",
  "route_object": {
    "predicate": "org.springframework.cloud.handler.predicate.PathRoutePredicateFactory$$Lambda$432/1736826640@1e9d7e7d",
    "filters": [
      "OrderedGatewayFilter{delegate=org.springframework.cloud.gateway.filter.factory.PreserveHostHeaderGatewayFilterFactory$$Lambda$436/674480275@6631ef72, order=0}"
    ]
  },
  "order": 0
},
{
  "route_id": "second_route",
  "route_object": {
    "predicate": "org.springframework.cloud.handler.predicate.PathRoutePredicateFactory$$Lambda$432/1736826640@cd8d298",
    "filters": []
  },
  "order": 0
}]

响应包含了网关中定义的所有路由的详细信息。下表描述了响应中每个元素（每条路由）的结构：

路径类型描述
route_idString路由 ID。
route_object.predicateObject路由断言。
route_object.filtersArray应用于路由的 GatewayFilter 工厂。
orderNumber路由顺序。

5. 获取特定路由的信息 ​

要获取单条路由的信息，请向 /actuator/gateway/routes/{id} 发起 GET 请求（例如 /actuator/gateway/routes/first_route）。响应结果如下：

json
{
  "id": "first_route",
  "predicates": [{
    "name": "Path",
    "args": {"_genkey_0":"/first"}
  }],
  "filters": [],
  "uri": "https://www.uri-destination.org",
  "order": 0
}

下表描述了响应的结构：

路径类型描述
idString路由 ID。
predicatesArray路由断言集合。每项定义了给定断言的名称和参数。
filtersArray应用于路由的过滤器集合。
uriString路由的目标 URI。
orderNumber路由顺序。

6. 创建和删除特定的路由定义 ​

要创建路由定义，请向 /gateway/routes/{id_route_to_create} 发起 POST 请求，并带有指定路由字段的 JSON 正文（参见获取特定路由的信息）。

要删除路由定义，请向 /gateway/routes/{id_route_to_delete} 发起 DELETE 请求。

7. 创建多个路由定义 ​

要在单个请求中创建多个路由定义，请向 /gateway/routes 发起 POST 请求，并带有指定路由字段（包括路由 ID）的 JSON 正文。

如果在创建路由的过程中有任何一条路由报错，所有的路由定义都将被丢弃。

8. 总结：所有端点列表 ​

下表总结了 Spring Cloud Gateway 的 Actuator 端点（注意每个端点都以 /actuator/gateway 为基础路径）：

IDHTTP 方法描述
globalfiltersGET显示应用于路由的全局过滤器列表。
routefiltersGET显示应用于特定路由的 GatewayFilter 工厂列表。
refreshPOST清除并刷新路由缓存。
routesGET显示网关中定义的路由列表。
routes/{id}GET显示特定路由的信息。
routes/{id}POST向网关添加一条新路由。
routes/{id}DELETE从网关移除一条现有路由。

补充教学 —— 为什么要用 Actuator 管理网关？ ​

1. 实时洞察力 在复杂的微服务环境中，如果你不确定网关到底生效了哪些路由，或者想看看过滤器链的执行顺序，Actuator 是最好的“显微镜”。通过 /actuator/gateway/routes，你可以清楚地看到当前内存中运行的所有路由详情。

2. 零停机维护 (热刷新) 我们在配置文件中修改了路由后，可以使用 /actuator/gateway/refresh 接口让网关实时加载新配置，而不需要重启整个网关服务。这在生产环境中是实现“高可用”的关键。

3. 轻量级的控制台 虽然有很多可视化管理界面，但 Actuator 提供的 REST 接口是基础。你可以通过简单的 curl 命令（POST/DELETE）直接在运行时增删路由。这特别适合与一些自动化运维脚本集成。

安全红线 (重要！) Actuator 的网关端点权限极大（可以删除所有路由导致全站报 404）。

  • 严禁 在生产环境将其直接暴露到公网。
  • 必须 配合 Spring Security 进行认证授权。
  • 建议 将 management.endpoint.gateway.access 设置为 read-only，除非确实需要动态修改能力。

Based on Spring Framework.

Copyright © 2024 Spring 中文社区