跳到主要内容

网关层设计

引用文件

本文引用的文件

目录​

  1. 引言
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能考量
  8. 故障排查指南
  9. 结论
  10. 附录

引言​

本设计文档聚焦于 yudao-cloud 的网关层，系统性阐述网关作为统一入口的关键职责：请求路由、负载均衡、安全认证与日志记录。文档将深入解析网关的启动流程、配置管理与组件初始化过程，梳理请求在网关层的完整处理链路，并给出配置最佳实践与性能优化建议，帮助读者快速理解并高效运维该网关。

项目结构​

网关模块位于 yudao-gateway，采用 Spring Boot + Spring Cloud Gateway 架构，核心文件组织如下：

  • 启动类：GatewayServerApplication
  • 配置：application.yaml 及按环境拆分的 application-{env}.yaml
  • 过滤器：安全认证、跨域、访问日志、灰度负载均衡
  • 工具类：安全框架与 Web 框架工具
  • 依赖：基于 Maven 的模块化 POM，集成 Nacos、监控、RPC、Knife4j 等能力

Mermaid Diagram Code:

graph TB
A["GatewayServerApplication<br/>启动类"] --> B["application.yaml<br/>应用配置"]
B --> C["application-dev.yaml<br/>开发环境配置"]
A --> D["过滤器链<br/>CorsFilter → AccessLogFilter → TokenAuthenticationFilter → GrayReactiveLoadBalancerClientFilter"]
D --> E["SecurityFrameworkUtils<br/>安全工具"]
D --> F["WebFrameworkUtils<br/>Web 工具"]
A --> G["BannerApplicationRunner<br/>启动提示"]
A --> H["pom.xml<br/>依赖与打包"]

图表来源

章节来源

核心组件​

  • 启动类与配置
    • 启动类负责引导 Spring Boot 应用，应用名为 gateway-server，端口默认 48080。
    • 配置通过 spring.config.import 串联本地与 Nacos 配置，支持 dev/prod 环境切换。
  • 过滤器链
    • 跨域过滤器：统一设置 CORS 响应头，处理 OPTIONS 预检。
    • 访问日志过滤器：记录请求/响应上下文、耗时与 JSON 格式化输出。
    • 安全认证过滤器：校验 Authorization Bearer Token，透传用户信息至下游。
    • 灰度负载均衡过滤器：基于自研灰度负载均衡器选择实例。
  • 工具类
    • SecurityFrameworkUtils：提取与注入登录用户信息、移除伪造头。
    • WebFrameworkUtils：租户 ID 透传、客户端 IP 获取、JSON 响应写出。

章节来源

架构总览​

网关整体以 Spring Cloud Gateway 为核心，结合 Nacos 配置中心、监控与 RPC 能力，形成统一入口。请求在进入下游服务前，依次经过跨域、日志、认证与灰度负载均衡等过滤器。

Mermaid Diagram Code:

graph TB
subgraph "客户端"
U["浏览器/移动端/第三方"]
end
subgraph "网关层"
CF["跨域过滤器<br/>CorsFilter"]
ALF["访问日志过滤器<br/>AccessLogFilter"]
TAF["安全认证过滤器<br/>TokenAuthenticationFilter"]
GLB["灰度负载均衡过滤器<br/>GrayReactiveLoadBalancerClientFilter"]
end
subgraph "下游服务"
S1["系统模块服务"]
S2["基础设施模块服务"]
S3["设备/任务/规则等模块服务"]
end
U --> CF --> ALF --> TAF --> GLB --> S1
U --> CF --> ALF --> TAF --> GLB --> S2
U --> CF --> ALF --> TAF --> GLB --> S3

图表来源

详细组件分析​

启动流程与配置管理​

  • 启动流程
    • 启动类加载 Spring Boot 自动装配，随后读取 application.yaml。
    • 配置导入策略：优先加载本地 application-{env}.yaml，再加载 Nacos 上同名配置，最后加载通用配置。
    • 端口与日志：默认端口 48080，日志文件路径可配置。
  • 组件初始化
    • 过滤器自动装配，按 order 顺序参与请求处理。
    • 工具类与 Runner 在容器启动后可用。

Mermaid Diagram Code:

sequenceDiagram
participant Boot as "Spring Boot"
participant App as "GatewayServerApplication"
participant Cfg as "application.yaml"
participant Nacos as "Nacos 配置中心"
Boot->>App : 启动应用
App->>Cfg : 读取基础配置
Cfg->>Nacos : 按配置导入顺序拉取配置
Nacos-->>Cfg : 返回配置
Cfg-->>Boot : 注入配置属性
Boot-->>App : 完成 Bean 初始化

图表来源

章节来源

跨域过滤器（CorsFilter）​

  • 功能要点
    • 识别跨域请求，统一设置允许来源、方法、头部与预检缓存。
    • 对 OPTIONS 预检请求直接返回 200。
  • 适用场景
    • 前后端分离、移动端或第三方接入时的跨域场景。

Mermaid Diagram Code:

flowchart TD
Start(["进入 CorsFilter"]) --> Check["检测是否为跨域请求"]
Check --> |否| Pass["直接放行"]
Check --> |是| SetHdr["设置 CORS 响应头"]
SetHdr --> Opt{"请求方法为 OPTIONS ?"}
Opt --> |是| Ok["返回 200 并结束"]
Opt --> |否| Next["继续下一个过滤器"]
Pass --> End(["结束"])
Ok --> End
Next --> End

图表来源

章节来源

访问日志过滤器（AccessLogFilter）​

  • 功能要点
    • 记录请求/响应上下文：URL、方法、查询参数、请求头、请求体、响应体、状态码、耗时。
    • 支持 JSON/Form 请求体读取与响应体合并（解决分段传输）。
    • 输出到控制台，便于排查。
  • 性能注意
    • 对大体积请求/响应体需谨慎开启日志，避免 IO 压力。

Mermaid Diagram Code:

sequenceDiagram
participant Client as "客户端"
participant ALF as "AccessLogFilter"
participant Chain as "过滤器链"
participant Downstream as "下游服务"
Client->>ALF : 发送请求
ALF->>ALF : 记录请求基本信息与请求体
ALF->>Chain : 继续处理
Chain->>Downstream : 转发请求
Downstream-->>Chain : 返回响应
Chain-->>ALF : 响应回传
ALF->>ALF : 记录响应体与耗时
ALF-->>Client : 返回响应

图表来源

章节来源

安全认证过滤器（TokenAuthenticationFilter）​

  • 功能要点
    • 从 Authorization 头提取 Bearer Token，调用系统模块的 Token 校验接口。
    • 成功则将用户信息注入请求头与交换上下文，失败也继续转发（具体鉴权由下游服务完成）。
    • 使用本地缓存加速用户信息解析，避免频繁远程校验。
  • 关键流程

Mermaid Diagram Code:

flowchart TD
Enter(["进入 TokenAuthenticationFilter"]) --> Clean["移除上游可能伪造的 login-user 头"]
Clean --> GetTok["提取 Authorization Bearer Token"]
GetTok --> HasTok{"是否存在 Token ?"}
HasTok --> |否| Chain["继续过滤器链"]
HasTok --> |是| Cache{"本地缓存命中 ?"}
Cache --> |是| Build["构建 LoginUser 并注入上下文与请求头"]
Cache --> |否| Remote["调用远程校验接口"]
Remote --> Parse{"解析结果是否有效 ?"}
Parse --> |否| Chain
Parse --> |是| PutCache["写入缓存并构建 LoginUser"]
PutCache --> Build
Build --> Chain

图表来源

章节来源

灰度负载均衡过滤器（GrayReactiveLoadBalancerClientFilter）​

  • 功能要点
    • 识别以 grayLb 为协议前缀的路由，委托灰度负载均衡器选择实例。
    • 与 Spring Cloud LoadBalancer 集成，支持生命周期事件回调。
  • 适用场景
    • 灰度发布、金丝雀流量、按标签/权重分流。

Mermaid Diagram Code:

sequenceDiagram
participant GW as "Gateway"
participant GLB as "GrayReactiveLoadBalancerClientFilter"
participant LB as "灰度负载均衡器"
participant SI as "服务实例"
GW->>GLB : 请求到达，携带 grayLb : //host/path
GLB->>LB : 选择服务实例
LB-->>GLB : 返回实例
GLB->>SI : 重建 URI 并设置到请求
GLB-->>GW : 继续转发

图表来源

章节来源

工具类（SecurityFrameworkUtils、WebFrameworkUtils）​

  • SecurityFrameworkUtils
    • 提供 Authorization 头解析、登录用户注入/移除、请求头 login-user 的序列化与编码。
  • WebFrameworkUtils
    • 提供租户 ID 透传、客户端 IP 获取、统一 JSON 响应写出。

章节来源

依赖关系分析​

  • 模块依赖
    • 网关模块依赖 yudao-module-system-api（用于 OAuth2 Token 校验）、Spring Cloud Gateway、Nacos 注册/配置中心、监控与 RPC 负载均衡。
  • 根 POM
    • 根 POM 定义了多环境 Profile 与仓库镜像，确保依赖拉取稳定。

Mermaid Diagram Code:

graph LR
Root["根 POM<br/>pom.xml根"] --> GW["网关模块<br/>yudao-gateway/pom.xml"]
GW --> SysAPI["yudao-module-system-api"]
GW --> SG["spring-cloud-starter-gateway"]
GW --> LB["spring-cloud-starter-loadbalancer"]
GW --> NacosD["spring-cloud-starter-alibaba-nacos-discovery"]
GW --> NacosC["spring-cloud-starter-alibaba-nacos-config"]
GW --> Mon["yudao-spring-boot-starter-monitor"]
GW --> Knife4j["knife4j-gateway-spring-boot-starter"]

图表来源

章节来源

性能考量​

  • 过滤器顺序与开销
    • 访问日志过滤器顺序靠前，建议仅在调试/生产审计场景启用，避免对高并发造成额外 IO 压力。
    • 跨域过滤器成本低，建议保持开启。
  • 认证与缓存
    • Token 校验采用本地缓存，建议合理设置缓存失效时间与容量，避免热点失效导致抖动。
  • 负载均衡
    • 灰度负载均衡器需关注实例健康与标签一致性，避免错误路由引发下游压力。
  • 配置与网络
    • Nacos 地址与命名空间需稳定，避免频繁重连影响启动与运行。
  • 监控与可观测性
    • 结合 yudao-spring-boot-starter-monitor 与链路追踪，定位瓶颈与异常。

故障排查指南​

  • 启动阶段
    • 若端口占用或 Nacos 连接失败，检查 application.yaml 中 server.port 与 spring.cloud.nacos.* 配置。
    • 启动完成后，BannerApplicationRunner 会在控制台输出文档与教程链接，便于快速定位资源。
  • 认证失败
    • 确认 Authorization 头格式为 Bearer Token，且系统模块 Token 校验接口可达。
    • 检查本地缓存是否命中，必要时清理缓存或缩短缓存时间。
  • 跨域问题
    • 确认 CorsFilter 是否生效，OPTIONS 预检是否返回 200。
  • 日志缺失
    • 确认 AccessLogFilter 是否处于过滤器链首位，且日志级别允许输出。
  • 灰度路由无效
    • 确认路由 URL 使用 grayLb 协议前缀，灰度负载均衡器是否正确选择实例。

章节来源

结论​

yudao-cloud 网关层以 Spring Cloud Gateway 为基础，结合 Nacos 配置中心、监控与 RPC 能力，提供了完善的统一入口能力。通过跨域、日志、认证与灰度负载均衡等过滤器，实现了高内聚、低耦合的请求处理链路。建议在生产环境中合理配置过滤器与缓存策略，配合监控与可观测性体系，持续优化性能与稳定性。

附录​

  • 配置最佳实践
    • 环境隔离：使用 spring.profiles.active 与 Nacos 命名空间区分 dev/prod。
    • 安全：强制使用 Bearer Token，避免明文密码；跨域仅暴露必要来源与方法。
    • 日志：仅在必要场景开启访问日志，控制日志级别与输出介质。
    • 负载均衡：灰度路由明确协议前缀，实例标签与权重清晰，定期校验健康状态。
  • 性能优化建议
    • 减少过滤器链深度与 IO 操作，优先使用本地缓存。
    • 合理设置 Nacos 连接超时与重试策略，避免阻塞启动。
    • 使用链路追踪与指标监控，定位慢请求与异常节点。
用户文档
AI 助手
Agent 列表
请选择一个 Agent 开始对话
AI 问答