请求来源验证拦截器 🔒

功能介绍 💡

WARNING

请求来源验证拦截器（Referer Filter）就像网站的门卫，负责检查访问请求的来源是否可信。它能有效防止未经授权的网站盗用API接口，保护您的系统资源。

应用场景 🎯

• ✅ 防止接口盗用 - 限制只允许指定域名的网站调用接口
• ✅ 跨域安全控制 - 管理跨域请求的访问权限
• ✅ 资源保护 - 防止其他网站直接引用您的API资源

详细配置说明 ⚙️

核心参数说明

参数名	类型	必填	默认值	说明
enabled	boolean	否	false	是否启用拦截器
rules	array[object]	是	-	拦截规则配置列表

拦截规则配置详解 (rules)

参数名	类型	必填	说明	示例值
urls	array[string]	是	需要进行来源验证的URL地址列表	/**
hosts	array[string]	是	允许访问的域名列表，支持通配符	*.wueasy.com

域名匹配规则说明 📝

1. 精确匹配

   • www.wueasy.com - 只允许来自此域名的请求

2. 通配符匹配

   • *.wueasy.com - 允许wueasy.com的所有子域名

配置示例 📋

基础配置

# 基础请求来源验证配置
gateway:
  filter:
    referer:
      enabled: true  # 启用来源验证
      rules:  # 拦截规则列表
        - urls: 
            - /** 
          hosts:  # 允许的域名列表
            - "www.example.com"  # 允许指定域名

多规则配置

# 多规则请求来源验证配置
gateway:
  filter:
    referer:
      enabled: true  # 启用来源验证
      rules:  # 拦截规则列表
        - urls:
            - /api/**  # 拦截所有API请求
          hosts:
            - "api.wueasy.com"  # 只允许指定域名
            - "dev.wueasy.com"  # 允许开发环境域名
        - urls:
            - /public/**  # 拦截公共接口
          hosts:
            - "*.wueasy.com"  # 允许所有子域名

完整配置示例

# 完整的请求来源验证配置示例
gateway:
  filter:
    referer:
      enabled: true
      rules:
        # API接口来源验证（严格控制）
        - urls:
            - /api/v1/**
            - /api/v2/**
          hosts:
            - "app.example.com"      # 主应用域名
            - "admin.example.com"    # 管理后台域名
            - "mobile.example.com"   # 移动端域名
        
        # 开放API接口（相对宽松）
        - urls:
            - /open/api/**
          hosts:
            - "*.example.com"        # 允许所有子域名
            - "partner.example.org"  # 合作伙伴域名
        
        # 静态资源访问控制
        - urls:
            - /static/**
            - /assets/**
          hosts:
            - "www.example.com"
            - "cdn.example.com"
            - "*.example.com"
        
        # 第三方集成接口
        - urls:
            - /webhook/**
            - /callback/**
          hosts:
            - "webhook.example.com"
            - "api.partner.com"

不同环境配置

# 不同环境的请求来源验证配置
gateway:
  filter:
    referer:
      enabled: true
      rules:
        # 生产环境配置（严格）
        - urls:
            - /prod/api/**
          hosts:
            - "www.example.com"
            - "app.example.com"
        
        # 测试环境配置（宽松）
        - urls:
            - /test/api/**
          hosts:
            - "*.test.example.com"
            - "localhost"
            - "127.0.0.1"
        
        # 开发环境配置（最宽松）
        - urls:
            - /dev/api/**
          hosts:
            - "*.dev.example.com"
            - "*.local"
            - "localhost"
            - "127.0.0.1"
            - "192.168.*"

业务场景配置

# 不同业务场景的来源验证配置
gateway:
  filter:
    referer:
      enabled: true
      rules:
        # 支付接口（最严格）
        - urls:
            - /payment/**
            - /finance/**
          hosts:
            - "secure.example.com"   # 只允许安全域名
        
        # 用户接口（中等严格）
        - urls:
            - /user/**
            - /profile/**
          hosts:
            - "www.example.com"
            - "app.example.com"
            - "mobile.example.com"
        
        # 内容接口（相对宽松）
        - urls:
            - /content/**
            - /news/**
          hosts:
            - "*.example.com"
            - "partner.*.com"
        
        # 公开接口（最宽松，但仍有限制）
        - urls:
            - /public/**
          hosts:
            - "*.example.com"
            - "*.partner.com"
            - "trusted.third-party.com"

最佳实践 💡

1. 安全性建议

   • 避免使用过于宽松的通配符（如 *）
   • 建议配置具体的子域名范围
   • 生产环境务必启用 HTTPS

2. 配置建议

   • 对不同类型的API设置不同的访问限制
   • 为开发环境和生产环境配置不同的规则
   • 定期审查和更新允许访问的域名列表

常见问题 ❓

1. 请求被拦截

   • 检查请求的Referer头是否存在
   • 验证域名是否在允许列表中
   • 确认URL匹配规则是否正确

2. 配置不生效

   • 确认 enabled 是否设置为 true
   • 检查 urls 配置是否正确匹配请求路径
   • 验证 hosts 配置的域名格式是否正确

3. 跨域问题

   • 配合CORS配置使用
   • 确保允许的域名在两处配置中保持一致

安全提示 ⚠️

CAUTION

1. Referer验证应该作为安全措施的一部分，不能作为唯一的安全手段
2. 某些情况下Referer可能被篡改，建议配合其他安全措施使用
3. 定期检查和更新允许的域名列表，移除不再使用的域名

相关文档 📚

• URL匹配规则说明
• CORS跨域配置