🚀 路由配置指南

📖 简介

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

为什么需要路由配置？

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

⚙️ 配置结构

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

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=path1,path2,...	Path=/api/,/rest/
Method	HTTP方法匹配，多个方法用逗号分隔	Method=GET,POST,...	Method=GET,POST,PUT
Header	请求头匹配，支持正则表达式	Header=name,regexp	Header=X-Id,\d+
Query	查询参数匹配，可指定参数值	Query=param[,value]	Query=name,test
Host	主机名匹配，支持通配符 *，多个主机用逗号分隔	Host=host1,host2,...	Host=.example.com,.test.com
After	在指定时间之后生效	After=datetime	After=2025-04-27T23:30:45+08:00
Before	在指定时间之前生效	Before=datetime	Before=2025-04-01T23:30:45+08:00
Between	在指定时间范围内生效	Between=time1,time2	Between=2025-04-01T23:30:45+08:00,2025-04-27T23:30:45+08:00
Cookie	Cookie匹配，支持正则表达式	Cookie=name,regexp	Cookie=sessionId,\w+

使用说明:

1. Path断言是最常用的断言类型，必须配置。/* 匹配单层路径，/** 匹配多层路径。可以配置多个路径，用逗号分隔
2. Method断言用于限制请求方法，多个方法间用逗号分隔，不区分大小写
3. Header和Cookie断言支持正则表达式匹配，格式为"名称,正则表达式"
4. Query断言可以只匹配参数名，也可以同时匹配参数值
5. Host断言支持通配符，*.example.com匹配二级域名，**.example.com匹配多级域名。可以配置多个主机名，用逗号分隔
6. 时间相关断言使用ISO-8601格式，需要包含时区信息
7. 多个断言之间是"与"的关系，全部满足才会匹配成功

过滤器配置

过滤器说明

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

类型	说明	格式	示例
StripPrefix	去除路径前缀	StripPrefix=n	StripPrefix=1
PrefixPath	添加路径前缀	PrefixPath=prefix	PrefixPath=/api
AddReqHeader	添加请求头	AddReqHeader=name,value	AddReqHeader=X-Id,123
RemoveReqHeader	删除请求头	RemoveReqHeader=name	RemoveReqHeader=X-Id
SetReqHeader	设置请求头	SetReqHeader=name,value	SetReqHeader=X-Id,123
AddRespHeader	添加响应头	AddRespHeader=name,value	AddRespHeader=X-Id,456
RemoveRespHeader	删除响应头	RemoveRespHeader=name	RemoveRespHeader=X-Id
SetRespHeader	设置响应头	SetRespHeader=name,value	SetRespHeader=X-Id,456

说明:

• StripPrefix: 去除路径前缀,如/api/user -> /user
• PrefixPath: 添加路径前缀,如/user -> /api/user
• AddReqHeader: 添加请求头
• RemoveReqHeader: 删除请求头
• SetReqHeader: 设置请求头
• AddRespHeader: 添加响应头
• RemoveRespHeader: 删除响应头
• SetRespHeader: 设置响应头

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

📝 配置示例

基础路由配置

gateway:
  routes:
    - id: api-service
      uri: lb://api-service
      predicates:
        - Path=/api/**
      filters:
        - StripPrefix=1

高级路由配置

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
      filters:
        - StripPrefix=1
        - AddRequestHeader=X-Request-Id, 123
        - AddResponseHeader=X-Response-Id, 123

💡 最佳实践

路由配置建议

1. 路由ID命名规范

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

2. URI配置建议

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

3. 断言条件建议

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

4. 安全配置建议

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

❓ 常见问题

1. 路由不生效？

检查清单：

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

2. 性能问题？

优化建议：

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

🆘 技术支持

如果遇到问题：

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

重要提示

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