你好呀，我的老朋友！我是老寇，欢迎来到老寇IoT云平台！

📌 概述

RouteDefinition 是 Spring Cloud Gateway 中用于定义路由规则的核心对象。本文档描述了 router.json 中的路由配置规范。

---

📋 RouteDefinition 结构

字段	类型	必填	说明
id	String	✅	路由唯一标识符
uri	String	✅	目标服务地址
predicates	Array<PredicateDefinition>	✅	路由断言条件列表
filters	Array<FilterDefinition>	❌	过滤器列表
metadata	Object	❌	路由元数据
order	Integer	❌	路由优先级（数值越小优先级越高）

---

🔗 URI 格式规范

格式	说明	示例
lb://服务名	负载均衡 HTTP 服务	lb://laokou-admin
lb:ws://服务名	负载均衡 WebSocket 服务	lb:ws://laokou-iot-websocket
http://host:port	直连 HTTP 地址	http://localhost:8080
https://host:port	直连 HTTPS 地址	https://api.example.com
ws://host:port	直连 WebSocket 地址	ws://localhost:9000

---

🎯 PredicateDefinition（断言定义）

结构

{
  "name": "断言名称",
  "args": {
    "参数名": "参数值"
  }
}

常用断言类型

断言名称	参数	说明
Path	pattern	路径匹配
Weight	_genkey_0（分组）, _genkey_1（权重）	权重路由
Method	methods	HTTP 方法匹配
Header	header, regexp	请求头匹配
Query	param, regexp	查询参数匹配
Host	patterns	主机名匹配
After	datetime	时间之后生效
Before	datetime	时间之前生效
Between	datetime1, datetime2	时间范围内生效
Cookie	name, regexp	Cookie 匹配
RemoteAddr	sources	远程地址匹配

示例

Path 断言

{
  "name": "Path",
  "args": {
    "pattern": "/admin/**"
  }
}

Weight 断言（权重路由）

{
  "name": "Weight",
  "args": {
    "_genkey_0": "admin",
    "_genkey_1": "100"
  }
}

• _genkey_0：分组名称
• _genkey_1：权重值（0-100）

---

🔧 FilterDefinition（过滤器定义）

结构

{
  "name": "过滤器名称",
  "args": {
    "参数名": "参数值"
  }
}

常用过滤器类型

过滤器名称	参数	说明
StripPrefix	parts	去除路径前缀层数
RewritePath	_genkey_0（正则）, _genkey_1（替换）	路径重写
AddRequestHeader	name, value	添加请求头
AddResponseHeader	name, value	添加响应头
SetStatus	status	设置响应状态码
Retry	retries, statuses	重试配置
CircuitBreaker	name, fallbackUri	熔断器
RateLimiter	replenishRate, burstCapacity	限流器
RequestSize	maxSize	请求大小限制

示例

StripPrefix 过滤器

{
  "name": "StripPrefix",
  "args": {
    "parts": "1"
  }
}

去除请求路径的第一段，如 /admin/user/list → /user/list

RewritePath 过滤器

{
  "name": "RewritePath",
  "args": {
    "_genkey_0": "/admin/(?<path>.*)",
    "_genkey_1": "/$\\{path}"
  }
}

• _genkey_0：正则表达式匹配模式
• _genkey_1：替换模式（$\\{path} 在 JSON 中需要转义）

---

📊 当前路由配置一览

路由 ID	URI	路径模式	权重	说明
laokou-auth	lb://laokou-auth	/auth/**	100	认证服务
laokou-admin	lb://laokou-admin	/admin/**	100	后台管理服务
laokou-iot	lb://laokou-iot	/iot/**	100	IoT 服务
laokou-generator	lb://laokou-generator	/generator/**	100	代码生成服务
laokou-iot-websocket	lb:ws://laokou-iot-websocket	/iot-websocket/**	100	IoT WebSocket 服务

---

📝 完整路由配置示例

HTTP 服务路由

{
  "id": "laokou-admin",
  "uri": "lb://laokou-admin",
  "predicates": [
    {
      "name": "Path",
      "args": {
        "pattern": "/admin/**"
      }
    },
    {
      "name": "Weight",
      "args": {
        "_genkey_0": "admin",
        "_genkey_1": "100"
      }
    }
  ],
  "filters": [
    {
      "name": "StripPrefix",
      "args": {
        "parts": "1"
      }
    },
    {
      "name": "RewritePath",
      "args": {
        "_genkey_0": "/admin/(?<path>.*)",
        "_genkey_1": "/$\\{path}"
      }
    }
  ],
  "metadata": {
    "version": "v1"
  },
  "order": 1
}

WebSocket 服务路由

{
  "id": "laokou-iot-websocket",
  "uri": "lb:ws://laokou-iot-websocket",
  "predicates": [
    {
      "name": "Path",
      "args": {
        "pattern": "/iot-websocket/**"
      }
    },
    {
      "name": "Weight",
      "args": {
        "_genkey_0": "iot-websocket",
        "_genkey_1": "100"
      }
    }
  ],
  "filters": [
    {
      "name": "StripPrefix",
      "args": {
        "parts": "1"
      }
    },
    {
      "name": "RewritePath",
      "args": {
        "_genkey_0": "/iot-websocket/(?<path>.*)",
        "_genkey_1": "/$\\{path}"
      }
    }
  ],
  "metadata": {
    "version": "v1"
  },
  "order": 1
}

---

🔄 请求转换流程

客户端请求                    网关处理                        后端服务
    │                           │                              │
    │  GET /admin/user/list     │                              │
    │ ─────────────────────────►│                              │
    │                           │ 1. Path 断言匹配 /admin/**   │
    │                           │ 2. Weight 断言验证           │
    │                           │ 3. StripPrefix 去除 /admin   │
    │                           │ 4. RewritePath 路径重写      │
    │                           │                              │
    │                           │  GET /user/list              │
    │                           │ ─────────────────────────────►
    │                           │                              │

---

🆕 新增路由模板

如需新增路由，可参考以下模板：

{
  "id": "laokou-xxx",
  "uri": "lb://laokou-xxx",
  "predicates": [
    {
      "name": "Path",
      "args": {
        "pattern": "/xxx/**"
      }
    },
    {
      "name": "Weight",
      "args": {
        "_genkey_0": "xxx",
        "_genkey_1": "100"
      }
    }
  ],
  "filters": [
    {
      "name": "StripPrefix",
      "args": {
        "parts": "1"
      }
    },
    {
      "name": "RewritePath",
      "args": {
        "_genkey_0": "/xxx/(?<path>.*)",
        "_genkey_1": "/$\\{path}"
      }
    }
  ],
  "metadata": {
    "version": "v1"
  },
  "order": 1
}

---

⚠️ 注意事项

1. 路由 ID 唯一性：每个路由的 id 必须唯一
2. 路径匹配顺序：order 值越小优先级越高
3. JSON 转义：$\\{path} 在 JSON 中需要双反斜杠转义
4. WebSocket 路由：使用 lb:ws:// 协议前缀
5. 权重配置：同一分组的权重总和建议为 100
6. 服务名称：uri 中的服务名需与 Nacos 注册的服务名一致

我是老寇，我们下次再见啦！