🚀 路由配置指南

📖 简介

路由配置是网关的核心功能，它决定了请求如何被转发到后端服务。本指南将帮助您了解如何在Go Gateway中配置和使用路由功能。

为什么需要路由配置？

实现请求转发和负载均衡
支持服务发现和动态路由
提供灵活的请求过滤和转换
实现API网关的核心功能

⚙️ 配置结构

网关的配置主要包含以下几个部分：

yaml

# 网关路由配置
gateway:
  routes:  # 路由配置列表
    - id: route-1
      uri: lb://service-1
      predicates:
        - Path=/api/**
      filters:
        - StripPrefix=1

📋 配置参数说明

基本配置项

配置项	类型	必填	说明	示例值
id	string	是	路由的唯一标识符	`api-service`
uri	string	是	路由的目标URI，支持lb://前缀用于负载均衡	`lb://api-service`
predicates	array	是	路由的断言条件列表	`- Path=/api/**`
filters	array	否	路由的过滤器列表	`- StripPrefix=1`

断言配置

断言说明

断言用于判断请求是否匹配当前路由，支持多种匹配方式。合理配置断言可以实现精确的路由控制和灵活的请求分发策略。

📋 断言类型速查表

断言类型	核心功能	配置格式	典型示例	使用场景
Path 🛤️	路径匹配（支持通配符）	`Path=路径1,路径2,...`	`Path=/api/,/rest/`	API接口路由、静态资源分发
Method 🔧	HTTP方法匹配	`Method=方法1,方法2,...`	`Method=GET,POST,PUT`	RESTful接口、操作权限控制
Header 📋	请求头匹配（支持正则）	`Header=名称,正则表达式`	`Header=X-Id,\d+`	认证鉴权、版本控制
Query ❓	查询参数匹配	`Query=参数名,正则表达式`	`Query=name,test`	参数校验、条件过滤
Host 🌐	主机名匹配（支持正则）	`Host=主机名1,主机名2,...`	`Host=demo\.wueasy\.com`	多域名部署、环境隔离
After ⏰	指定时间后生效	`After=ISO时间格式`	`After=2025-04-27T23:30:45+08:00`	定时发布、灰度发布
Before ⏱️	指定时间前生效	`Before=ISO时间格式`	`Before=2025-04-01T23:30:45+08:00`	限时活动、功能下线
Between ⏲️	指定时间范围内生效	`Between=时间1,时间2`	`Between=2025-04-01T23:30:45+08:00,2025-04-27T23:30:45+08:00`	活动窗口、维护时段
Cookie 🍪	Cookie匹配（支持正则）	`Cookie=名称,正则表达式`	`Cookie=sessionId,\w+`	会话管理、用户识别
XForwardedRemoteAddr 🌍	客户端IP匹配（支持CIDR）	`XForwardedRemoteAddr=IP1,IP2,...`	`XForwardedRemoteAddr=192.168.1.0/24`	IP白名单、地域路由

🎯 断言配置最佳实践

🎨 1. 路径匹配（Path）- 最常用

yaml

# 基础路径匹配
Path=/api/user/*           # 匹配 /api/user/123，不匹配 /api/user/123/profile
Path=/api/**               # 匹配 /api/ 下的所有路径
Path=/static/*,/assets/** # 同时匹配多个路径前缀

# 实际应用场景
Path=/api/v1/**           # API版本控制
Path=/admin/*,/manage/**  # 后台管理接口
Path=/public/*            # 公共资源访问

🔐 2. 请求方法控制（Method）

yaml

# RESTful接口设计
Method=GET                # 查询操作
Method=POST               # 创建操作
Method=PUT,PATCH          # 更新操作
Method=DELETE             # 删除操作

# 权限控制组合
Method=GET                # 只读接口
Method=POST,PUT,DELETE    # 写操作接口

📊 3. 请求头匹配（Header）- 认证利器

yaml

# API版本控制
Header=X-API-Version,v1\..*    # v1.x版本
Header=X-API-Version,v2\.\d+   # v2.数字版本

# 认证令牌验证
Header=Authorization,Bearer\s.+ # Bearer Token格式
Header=X-API-Key,\w{32}         # 32位API密钥

# 客户端类型识别
Header=User-Agent,.*Mobile.*    # 移动端请求
Header=Content-Type,application/json # JSON格式请求

🔍 4. 查询参数匹配（Query）

yaml

# 参数存在性检查
Query=debug                    # 只要存在debug参数就匹配
Query=debug,true               # debug参数值必须为true
Query=version,v\d+\.\d+        # version参数格式验证

# 多参数组合
Query=page,\d+                # 分页参数必须是数字
Query=sort,(asc|desc)         # 排序参数只能是asc或desc

🌐 5. 主机名匹配（Host）- 多环境部署

yaml

# 生产环境
Host=api\.wueasy\.com          # 精确匹配

# 测试环境（支持子域名）
Host=.*\.test\.wueasy\.com      # 匹配所有测试子域名
Host=^([a-z]+)\.test\.wueasy\.com$ # 命名捕获组匹配

# 多域名支持
Host=api\.wueasy\.com,api\.wueasy\.cn # 国内外域名

⏰ 6. 时间控制（After/Before/Between）

yaml

# 功能上线时间控制
After=2025-01-01T00:00:00+08:00    # 新年后生效

# 活动截止时间
Before=2025-12-31T23:59:59+08:00    # 年底前有效

# 维护时间窗口
Between=2025-04-01T02:00:00+08:00,2025-04-01T06:00:00+08:00 # 凌晨维护时段

🍪 7. Cookie匹配（Cookie）

yaml

# 会话状态检查
Cookie=sessionId,\w{32}         # 有效的会话ID格式
Cookie=login_status,logged_in    # 已登录状态

# 用户偏好设置
Cookie=theme,(dark|light)        # 主题偏好
Cookie=language,(zh|en|ja)       # 语言偏好

🌍 8. IP地址匹配（XForwardedRemoteAddr）

yaml

# 内网IP白名单
XForwardedRemoteAddr=10\.0\.0\.\d+,192\.168\.\d+\.\d+ # 内网网段

# 办公网络
XForwardedRemoteAddr=192.168.1.0/24              # CIDR格式网段

# 地理区域限制
XForwardedRemoteAddr=^1\d{2}\.                    # 中国IP段（简化示例）
XForwardedRemoteAddr=^(?!1\d{2}\.).*              # 非中国IP段

📚 实际应用示例

🏢 场景1：多环境API路由

yaml

# 开发环境：dev-api.wueasy.com
# 测试环境：test-api.wueasy.com  
# 生产环境：api.wueasy.com
Host=.*api\.wueasy\.com
Path=/api/**
Method=GET,POST,PUT,DELETE
Header=X-API-Version,v\d+\.\d+

🛡️ 场景2：管理后台访问控制

yaml

# 只允许内网IP访问管理后台
Path=/admin/**
XForwardedRemoteAddr=10\.0\.0\.\d+,192\.168\.\d+\.\d+
Header=Authorization,Bearer\s.+  # 需要认证令牌
Cookie=admin_session,\w{32}      # 需要管理员会话

📱 场景3：移动端API适配

yaml

# 移动端专用API端点
Path=/mobile/**
Header=User-Agent,.*(iPhone|Android|Mobile).*  # 移动端User-Agent
Header=X-App-Version,\d+\.\d+\.\d+              # APP版本号格式

⏰ 场景4：限时活动接口

yaml

# 双十一活动接口（仅在活动期间有效）
Path=/promotion/1111/**
Between=2025-11-11T00:00:00+08:00,2025-11-11T23:59:59+08:00
Query=campaign,1111              # 活动标识参数

过滤器配置

过滤器说明

过滤器用于对请求和响应进行修改，支持多种转换操作。

类型	说明	格式	示例
StripPrefix	去除路径前缀	StripPrefix=n	`StripPrefix=1`
PrefixPath	添加路径前缀	PrefixPath=prefix	`PrefixPath=/api`
AddRequestHeader	添加请求头	AddRequestHeader=name,value	`AddRequestHeader=X-Id,123`
RemoveRequestHeader	删除请求头	RemoveRequestHeader=name	`RemoveRequestHeader=X-Id`
SetRequestHeader	设置请求头	SetRequestHeader=name,value	`SetRequestHeader=X-Id,123`
AddResponseHeader	添加响应头	AddResponseHeader=name,value	`AddResponseHeader=X-Id,456`
RemoveResponseHeader	删除响应头	RemoveResponseHeader=name	`RemoveResponseHeader=X-Id`
SetResponseHeader	设置响应头	SetResponseHeader=name,value	`SetResponseHeader=X-Id,456`

说明:

StripPrefix: 去除路径前缀,如/api/user -> /user
PrefixPath: 添加路径前缀,如/user -> /api/user
AddRequestHeader: 添加请求头
RemoveRequestHeader: 删除请求头
SetRequestHeader: 设置请求头
AddResponseHeader: 添加响应头
RemoveResponseHeader: 删除响应头
SetResponseHeader: 设置响应头

所有过滤器均为可选配置。

📝 配置示例

基础路由配置

yaml

# 基础路由配置示例
gateway:
  routes:
    - id: api-service
      uri: lb://api-service
      predicates:
        - Path=/api/**
      filters:
        - StripPrefix=1

高级路由配置

yaml

# 高级路由配置示例 - 包含多种断言和过滤器
gateway:
  routes:
    - id: web-service
      uri: lb://web-service
      predicates:
        - Path=/web/**
        - Method=GET,POST
        - Header=X-Request-Id,\d+
        - Query=name
        - XForwardedRemoteAddr=192.168.1.0/24,10.0.0.*
      filters:
        - StripPrefix=1
        - AddRequestHeader=X-Request-Id,123
        - AddResponseHeader=X-Response-Id,123

基于IP地址的路由配置

yaml

# 基于IP地址的路由配置示例 - 内网和外网分别路由到不同服务
gateway:
  routes:
    # 内网用户路由到内网服务
    - id: internal-api
      uri: lb://internal-api-service
      predicates:
        - Path=/api/**
        - XForwardedRemoteAddr=192.168.0.0/16,10.0.0.0/8,172.16.0.0/12
      filters:
        - StripPrefix=1
        - AddRequestHeader=X-Network-Type,internal
    
    # 外网用户路由到公网服务
    - id: public-api
      uri: lb://public-api-service
      predicates:
        - Path=/api/**
      filters:
        - StripPrefix=1
        - AddRequestHeader=X-Network-Type,public

💡 最佳实践

路由配置建议

路由ID命名规范
- 使用有意义的名称
- 遵循命名规范
- 便于识别和管理
URI配置建议
- 优先使用服务名
- 避免使用具体IP
- 支持动态扩缩容
断言条件建议
- 从精确到模糊
- 避免路由冲突
- 合理使用通配符
IP地址断言建议
- 优先使用CIDR网段
- 合理规划内外网路由
- 注意路由优先级顺序
- 考虑代理和负载均衡器的IP
安全配置建议
- 使用配置中心
- 避免硬编码
- 限制访问范围

❓ 常见问题

1. 路由不生效？

检查清单：

✓ 路由ID是否重复
✓ 断言条件是否正确
✓ 目标服务是否正常
✓ 网关日志是否有错误

2. 性能问题？

优化建议：

✓ 合理设置超时时间
✓ 使用合适的负载均衡策略
✓ 避免过多的过滤器
✓ 定期清理无效路由

3. IP地址断言不匹配？

排查步骤：

✓ 检查客户端真实IP地址
✓ 确认是否经过代理或负载均衡器
✓ 验证CIDR网段格式是否正确
✓ 检查通配符匹配规则
✓ 查看网关日志中的IP匹配信息

🆘 技术支持

如果遇到问题：

检查配置文件
查看网关日志
分析错误信息
联系技术支持

重要提示

定期检查路由配置
及时更新服务信息
注意安全配置
做好监控告警

🚀 路由配置指南 ​

📖 简介 ​

⚙️ 配置结构 ​

📋 配置参数说明 ​

基本配置项 ​

断言配置 ​

📋 断言类型速查表 ​

🎯 断言配置最佳实践 ​

📚 实际应用示例 ​

过滤器配置 ​

📝 配置示例 ​

基础路由配置 ​

高级路由配置 ​

基于IP地址的路由配置 ​

💡 最佳实践 ​

路由配置建议 ​

❓ 常见问题 ​

1. 路由不生效？ ​

2. 性能问题？ ​

3. IP地址断言不匹配？ ​

🆘 技术支持 ​

🚀 路由配置指南

📖 简介

⚙️ 配置结构

📋 配置参数说明

基本配置项

断言配置

📋 断言类型速查表

🎯 断言配置最佳实践

📚 实际应用示例

过滤器配置

📝 配置示例

基础路由配置

高级路由配置

基于IP地址的路由配置

💡 最佳实践

路由配置建议

❓ 常见问题

1. 路由不生效？

2. 性能问题？

3. IP地址断言不匹配？

🆘 技术支持