Go Gateway

外观

🚀 路由配置指南 ​

📖 简介 ​

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

为什么需要路由配置？

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

⚙️ 配置结构 ​

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

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

📋 配置参数说明 ​

基本配置项 ​

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

断言配置 ​

断言说明

断言用于判断请求是否匹配当前路由，支持多种匹配方式。每个断言都有特定的格式要求和使用场景。

断言类型说明格式示例
Path路径匹配，支持通配符 * 和 **，多个路径用逗号分隔Path=path1,path2,...Path=/api/**,/rest/**
MethodHTTP方法匹配，多个方法用逗号分隔Method=GET,POST,...Method=GET,POST,PUT
Header请求头匹配，支持正则表达式Header=name,regexpHeader=X-Id,\d+
Query查询参数匹配，可指定参数值Query=param[,value]Query=name,test
Host主机名匹配，支持通配符 *，多个主机用逗号分隔Host=host1,host2,...Host=*.example.com,*.test.com
After在指定时间之后生效After=datetimeAfter=2025-04-27T23:30:45+08:00
Before在指定时间之前生效Before=datetimeBefore=2025-04-01T23:30:45+08:00
Between在指定时间范围内生效Between=time1,time2Between=2025-04-01T23:30:45+08:00,2025-04-27T23:30:45+08:00
CookieCookie匹配，支持正则表达式Cookie=name,regexpCookie=sessionId,\w+
XForwardedRemoteAddr远程地址匹配，支持IP地址、CIDR网段和通配符XForwardedRemoteAddr=ip1,ip2,...XForwardedRemoteAddr=192.168.1.0/24,10.0.0.*

使用说明:

  1. Path断言是最常用的断言类型，必须配置。/* 匹配单层路径，/** 匹配多层路径。可以配置多个路径，用逗号分隔
  2. Method断言用于限制请求方法，多个方法间用逗号分隔，不区分大小写
  3. Header和Cookie断言支持正则表达式匹配，格式为"名称,正则表达式"
  4. Query断言可以只匹配参数名，也可以同时匹配参数值
  5. Host断言支持通配符，*.example.com匹配二级域名，**.example.com匹配多级域名。可以配置多个主机名，用逗号分隔
  6. 时间相关断言使用ISO-8601格式，需要包含时区信息
  7. XForwardedRemoteAddr断言用于根据客户端IP地址进行路由匹配，支持多种格式：
    • 精确IP地址：192.168.1.100
    • CIDR网段：192.168.1.0/24 匹配整个网段
    • 通配符：192.168.1.* 匹配IP段
    • 多个地址：用逗号分隔，如 192.168.1.0/24,10.0.0.*,172.16.1.100
  8. 多个断言之间是"与"的关系，全部满足才会匹配成功

过滤器配置 ​

过滤器说明

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

类型说明格式示例
StripPrefix去除路径前缀StripPrefix=nStripPrefix=1
PrefixPath添加路径前缀PrefixPath=prefixPrefixPath=/api
AddRequestHeader添加请求头AddRequestHeader=name,valueAddRequestHeader=X-Id,123
RemoveRequestHeader删除请求头RemoveRequestHeader=nameRemoveRequestHeader=X-Id
SetRequestHeader设置请求头SetRequestHeader=name,valueSetRequestHeader=X-Id,123
AddResponseHeader添加响应头AddResponseHeader=name,valueAddResponseHeader=X-Id,456
RemoveResponseHeader删除响应头RemoveResponseHeader=nameRemoveResponseHeader=X-Id
SetResponseHeader设置响应头SetResponseHeader=name,valueSetResponseHeader=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
        - Host=**.example.com
        - 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

💡 最佳实践 ​

路由配置建议 ​

  1. 路由ID命名规范

    • 使用有意义的名称
    • 遵循命名规范
    • 便于识别和管理

  2. URI配置建议

    • 优先使用服务名
    • 避免使用具体IP
    • 支持动态扩缩容

  3. 断言条件建议

    • 从精确到模糊
    • 避免路由冲突
    • 合理使用通配符

  4. IP地址断言建议

    • 优先使用CIDR网段
    • 合理规划内外网路由
    • 注意路由优先级顺序
    • 考虑代理和负载均衡器的IP

  5. 安全配置建议

    • 使用配置中心
    • 避免硬编码
    • 限制访问范围

❓ 常见问题 ​

1. 路由不生效？ ​

检查清单：

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

2. 性能问题？ ​

优化建议：

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

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

排查步骤：

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

🆘 技术支持 ​

如果遇到问题：

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

重要提示

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

Copyright © 2017-2025 wueasy.com