跳到主要内容
版本：5.0.1

执行器 API

DeepSeek V3 中英对照 Actuator API

/gateway 执行器端点允许您监控和与 Spring Cloud Gateway 应用程序进行交互。默认情况下，/gateway 执行器端点的访问权限是禁用的。要启用该端点，您需要在应用程序属性中将访问权限设置为 'read-only' 或 'unrestricted'，并通过 HTTP 或 JMX 将其暴露出来。以下清单展示了如何操作：

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 端点已安全保护。

此端点提供了子执行器端点上可用内容以及每个引用可用方法的概览。返回的响应类似于以下内容：

[
   {
      "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" ]
   }
]

详细执行器格式​

Spring Cloud Gateway 新增了一种更详细的格式。它为每条路由添加了更多细节，让你可以查看与每条路由关联的断言和过滤器，以及任何可用的配置。以下示例配置了 /actuator/gateway/routes：

[
  {
    "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
  }
]

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

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

这将在未来的版本中默认设置为 true。

检索路由过滤器​

本节详细说明如何检索路由过滤器，包括：

全局过滤器​

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

{
  "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）以及该过滤器在链中对应的顺序。

路由过滤器​

要检索应用于路由的 GatewayFilter 工厂，请向 /actuator/gateway/routefilters 发送 GET 请求。返回的响应类似于以下内容：

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

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

刷新路由缓存​

要清除路由缓存，请向 /actuator/gateway/refresh 发送一个 POST 请求。该请求会返回 200 状态码，且没有响应体。

要清除具有特定元数据值的路由，请添加查询参数 metadata，指定要清除的路由应匹配的 key:value 键值对。如果在异步刷新期间产生错误，刷新将不会修改现有路由。

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

[{
  "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" }
}]

检索网关中定义的路由​

要检索网关中定义的路由，请向 /actuator/gateway/routes 发送 GET 请求。返回的响应类似于以下内容：

[{
  "route_id": "first_route",
  "route_object": {
    "predicate": "org.springframework.cloud.gateway.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.gateway.handler.predicate.PathRoutePredicateFactory$$Lambda$432/1736826640@cd8d298",
    "filters": []
  },
  "order": 0
}]

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

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

检索特定路由的信息​

要获取单个路由的信息，请向 /actuator/gateway/routes/{id} 发送 GET 请求（例如 /actuator/gateway/routes/first_route）。

{
  "route_id": "first_route",
  "predicate": "(Paths: [/first], match trailing slash: true && Methods: [GET])",
  "filters": [],
  "uri": "https://www.uri-destination.org",
  "order": 0
}

下表描述了响应的结构：

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

创建和删除特定路由定义​

要创建路由定义，请向 /gateway/routes/{id_route_to_create} 发送一个 POST 请求，并在 JSON 请求体中指定路由的字段（参见检索特定路由的信息）。

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

创建多个路由定义​

要在单个请求中创建多个路由定义，请向 /gateway/routes 发送 POST 请求，并在 JSON 请求体中指定路由的字段，包括路由 ID（参见检索特定路由的信息）。

如果在创建路由时任何路由引发错误，路由定义将被丢弃。

回顾：所有端点的列表​

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

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