路由元数据配置 (Route Metadata Configuration)

可以通过 metadata 为每个路由配置额外的参数，如下所示：

application.yml

spring:
  cloud:
    gateway:
      routes:
      - id: route_with_metadata
        uri: https://example.org
        metadata:
          optionName: "OptionValue"
          compositeObject:
            name: "value"
          iAmNumber: 1

你可以从 exchange 中获取所有元数据属性，如下所示：

Route route = exchange.getAttribute(GATEWAY_ROUTE_ATTR);
// 获取所有元数据属性
route.getMetadata();
// 获取单个元数据属性
route.getMetadata("optionName");

补充教学 —— 元数据 (Metadata) 有什么用？

metadata 是网关设计中非常灵活的一个扩展点。它允许你你在配置层面为路由打上各种“标签”或“备注”，然后在代码层面（如自定义过滤器）读取这些信息来执行特定的逻辑。

常见应用场景：

1. 接口分组与文档生成：

   • 你可以给路由打上 group: user-service, version: v1 等标签。
   • Swagger/OpenAPI 聚合工具可以读取这些元数据，将网关后的 API 自动归类展示。

2. 自定义鉴权/权限控制：

   • metadata: { roles: ["admin", "editor"] }
   • 编写一个全局过滤器，读取当前路由的 roles 元数据，再对比当前用户的权限，实现基于路由配置的动态鉴权，而不需要把权限逻辑写死在代码里。

3. 灰度发布/Canary 标记：

   • metadata: { canary: true, weight: 10 }
   • 自定义负载均衡器读取这些标记，决定流量分发策略。

4. 超时时间/重试策略的动态覆盖：

   • 虽然官方有 ConnectTimeout 配置，但有时你需要更灵活的自定义控制逻辑，可以将特定参数放在 metadata 中，由自定义过滤器读取并应用到 Netty Client。

总结：Metadata 就是路由对象的“背包”，你可以往里面塞任何键值对，供后续环节使用。