网关基础设施与异常处理.md 29 KB

网关基础设施与异常处理

本文引用的文件

  • GatewayApplication.java
  • CorsConfig.java
  • WebClientConfig.java
  • RequestIdFilter.java
  • GatewayErrorHandler.java
  • StickyUnavailableException.java
  • StickyRouteFilter.java
  • LoginRequestFilter.java
  • LoginResponseFilter.java
  • TokenResolver.java
  • UserRouteService.java
  • GatewayAttributes.java
  • gateway.sql
  • pom.xml
  • README.md

目录

  1. 引言
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 关键组件详细分析
  6. 依赖关系分析
  7. 性能与 Netty/WebFlux 注意事项
  8. 503 错误语义与排障清单
  9. 结论

引言

本仓库的 ai-gateway 模块是一个基于 Spring Cloud Gateway、WebFlux 和 Netty 的用户粘性转发网关。它的核心职责不是复制后端业务逻辑,而是保证“同一用户的请求始终落到同一台 ai-server 节点”。这是因为案件数据源、附件、Agent 记忆等数据落在各节点的本地磁盘或 JVM 内存中,普通无状态负载均衡会把请求打散到没有数据的机器上。

网关的基础设施层由应用入口、跨域配置、响应式 WebClient 配置、请求 ID 注入、全局异常处理和统一错误语义组成;业务转发则由登录预处理、登录响应后处理、令牌解析、用户路由缓存以及粘性路由过滤器共同支撑。

项目结构

网关模块采用按职责分层的组织方式:

  • config:Spring 配置类,负责 CORS、WebClient、属性扫描。
  • support:横切基础设施,包括请求 ID、全局异常处理器、统一错误语义。
  • route:粘性路由主流程,包括登录请求预处理、登录响应后处理、令牌解析、用户路由服务、粘性路由过滤器。
  • registry:服务与节点注册表、健康检查、配置仓库(用于粘性决策)。
  • admin:管理接口及鉴权。
  • sql/gateway.sql:启动时自动执行的幂等建表脚本。

    graph TB
    subgraph "网关基础设施"
        App["GatewayApplication"]
        Cors["CorsConfig"]
        Wc["WebClientConfig"]
        Rid["RequestIdFilter"]
        Err["GatewayErrorHandler"]
        Sue["StickyUnavailableException"]
    end
    
    subgraph "粘性路由"
        Lrf["LoginRequestFilter"]
        Lrpf["LoginResponseFilter"]
        Tr["TokenResolver"]
        Urs["UserRouteService"]
        Srf["StickyRouteFilter"]
    end
    
    App --> Cors
    App --> Wc
    App --> Rid
    App --> Err
    App --> Srf
    Srf --> Lrf
    Srf --> Lrpf
    Srf --> Tr
    Srf --> Urs
    Err --> Sue
    

图示来源

  • GatewayApplication.java:1-23
  • CorsConfig.java:1-39
  • WebClientConfig.java:1-26
  • RequestIdFilter.java:1-34
  • GatewayErrorHandler.java:1-98
  • StickyUnavailableException.java:1-25
  • StickyRouteFilter.java:1-180
  • LoginRequestFilter.java:1-120
  • LoginResponseFilter.java:1-176
  • TokenResolver.java:1-100
  • UserRouteService.java:1-117

章节来源

  • pom.xml:1-148
  • README.md:1-157

核心组件

本节聚焦文档目标中的六个基础设施组件,并说明它们如何共同支撑粘性路由、管理接口和业务转发。

组件 主要职责 对粘性路由的影响
GatewayApplication 应用启动入口,启用调度与配置属性扫描 提供网关运行上下文,使注册表、过滤器、错误处理器等 Bean 生效
CorsConfig 可选网关层跨域处理 默认关闭,避免与后端跨域头重复;开启时可暴露 X-Gateway-Node 等头部
WebClientConfig 为探活专用 WebClient 设置连接超时与响应超时 不承载业务转发,只影响节点健康检查
RequestIdFilter 透传或生成 X-Request-Id 让一次完整请求在网关、后端、日志中可串联追踪
GatewayErrorHandler 统一捕获并转换异常为 JSON 错误体 把粘性不可用、上游失败、内部错误映射到明确 HTTP 状态码
StickyUnavailableException 表示粘性路由无法继续处理 携带自定义 HTTP 状态码,通常对应 503,但不切换节点

章节来源

  • GatewayApplication.java:1-23
  • CorsConfig.java:1-39
  • WebClientConfig.java:1-26
  • RequestIdFilter.java:1-34
  • GatewayErrorHandler.java:1-98
  • StickyUnavailableException.java:1-25

架构总览

网关的请求路径大致分为三类:

  1. 登录请求:先由 LoginRequestFilter 解析用户名并标记为登录请求,再由 StickyRouteFilter 决定是命中已有绑定还是轮询候选节点;成功后由 LoginResponseFilter 写入用户路由和 token 缓存。
  2. 业务请求:通过 x-token 解析 userId,再查用户路由缓存或数据库,最终粘到已绑定的节点;若未绑定且存在默认节点,则尝试兜底绑定。
  3. 管理请求:走 /gateway/admin/**,由管理员鉴权和 IP 白名单控制,变更服务、节点、用户路由后会刷新注册表。

    sequenceDiagram
    participant Client as "客户端"
    participant Gw as "网关"
    participant LoginReq as "LoginRequestFilter"
    participant Sticky as "StickyRouteFilter"
    participant Backend as "ai-server 节点"
    participant LoginResp as "LoginResponseFilter"
    
    Client->>Gw: POST /js/a/auth/login
    Gw->>LoginReq: 解析 username,标记登录请求
    LoginReq-->>Gw: 原样转发请求
    Gw->>Sticky: 选择绑定节点或候选节点
    Sticky-->>Backend: 流式转发
    Backend-->>Sticky: 登录响应
    Sticky-->>Gw: 透传响应
    Gw->>LoginResp: 捕获成功登录结构
    LoginResp->>Gw: 写用户绑定与 token 缓存
    LoginResp-->>Client: 返回原始登录响应
    

图示来源

  • LoginRequestFilter.java:1-120
  • StickyRouteFilter.java:1-180
  • LoginResponseFilter.java:1-176

关键组件详细分析

GatewayApplication:应用入口

GatewayApplication 使用 @SpringBootApplication 装配 Spring Boot,并通过 @EnableScheduling 启用定时任务,例如健康检查轮询和实例间对账。@ConfigurationPropertiesScan 会扫描配置属性,供 GatewayProperties 等配置类读取。

它本身不包含业务逻辑,但决定了整个网关容器的启动范围:过滤器、错误处理器、注册表、管理控制器、调度器都会在这个上下文中生效。

章节来源

  • GatewayApplication.java:1-23

CorsConfig:跨域配置

CorsConfig 默认关闭,只有当 gateway.cors.enabled=true 时才注册 CorsWebFilter。默认关闭的原因是后端已经实现了全局跨域处理;如果网关也输出 Access-Control-Allow-Origin,浏览器会收到重复响应头并拒绝响应。

当需要网关收口跨域时,该配置允许所有方法和所有请求头,允许凭证模式为关闭,并显式暴露以下响应头:

  • X-Gateway-Node:当前转发的后端节点标识
  • Content-Disposition:用于附件下载等场景
  • X-Request-Id:便于前端和链路日志关联

    flowchart TD
    Start["是否启用 gateway.cors.enabled"] -->|否| Passthrough["透传后端跨域响应头"]
    Start -->|是| Build["构建网关层 CorsWebFilter"]
    Build --> AllowOrigins["允许来源模式"]
    Build --> AllowHeaders["允许全部请求头"]
    Build --> AllowMethods["允许全部方法"]
    Build --> Credentials["不允许凭据跨域"]
    Build --> Expose["暴露 X-Gateway-Node / Content-Disposition / X-Request-Id"]
    AllowOrigins --> End["注册 /** 规则"]
    AllowHeaders --> End
    AllowMethods --> End
    Credentials --> End
    Expose --> End
    

图示来源

  • CorsConfig.java:1-39

章节来源

  • CorsConfig.java:1-39
  • README.md:28-33

WebClientConfig:探活专用 WebClient

WebClientConfig 创建的是 healthWebClient,专用于节点健康检查。它从 GatewayProperties 读取探活超时时间,并设置为 Reactor Netty 的 TCP 连接超时和 WebClient 响应超时。

需要注意:这个 WebClient 并不承载业务转发。业务请求走 Spring Cloud Gateway 内部的 HttpClient;这里只是避免健康检查复用业务通道,从而让探活行为可控、可观测。

章节来源

  • WebClientConfig.java:1-26

RequestIdFilter:请求 ID 注入

RequestIdFilter 是一个 WebFilter,在所有其他过滤器之前执行。它优先使用客户端传来的 X-Request-Id;如果没有,就生成一个 UUID。请求 ID 同时写入:

  • ServerWebExchange 的属性键 gateway.requestId
  • 响应头 X-Request-Id

这样,粘性路由过滤器、全局异常处理器、后端日志都可以用同一个请求 ID 串联排查。

flowchart TD
    Enter["进入 RequestIdFilter"] --> Read["读取请求头 X-Request-Id"]
    Read --> Has{"是否存在非空白值?"}
    Has -->|是| UseExisting["使用客户端提供的请求 ID"]
    Has -->|否| Generate["生成 UUID 作为请求 ID"]
    UseExisting --> SetAttr["写入 exchange 属性 gateway.requestId"]
    Generate --> SetAttr
    SetAttr --> SetHeader["设置响应头 X-Request-Id"]
    SetHeader --> Next["继续过滤器链"]

图示来源

  • RequestIdFilter.java:1-34
  • GatewayAttributes.java:1-31

章节来源

  • RequestIdFilter.java:1-34
  • GatewayAttributes.java:1-31

GatewayErrorHandler:全局异常处理

GatewayErrorHandler 实现 ErrorWebExceptionHandler,优先级高于多数 Spring 默认错误处理器。它根据异常类型决定 HTTP 状态码和消息:

异常类型 状态码 含义
StickyUnavailableException 来自异常的 HTTP 状态码,默认 503 粘性路由不可用,不切换节点
ResponseStatusException 使用其状态码,5xx 记录警告日志 框架或业务主动抛出的响应状态异常
上游连接错误或超时 502 后端节点连接失败、TCP 超时、Netty 连接超时
通用 TimeoutException 502 上层响应超时
其他异常 500 网关内部错误

它还会判断响应是否已提交。对于 SSE 等长连接,一旦开始写入响应体,就不应强行改写状态码;此时只记录日志,让底层 Netty 按既有连接语义断开。

flowchart TD
    Enter["handle(异常)"] --> Committed{"响应是否已提交?"}
    Committed -->|是| Rethrow["抛出异常,交由 Netty 断开连接"]
    Committed -->|否| Classify["分类异常类型"]
    Classify --> Sticky{"StickyUnavailableException?"}
    Sticky -->|是| Map503["映射 sticky 状态码,默认 503"]
    Sticky -->|否| Rse{"ResponseStatusException?"}
    Rse -->|是| MapRse["映射其状态码,5xx 记警告日志"]
    Rse -->|否| Upstream{"上游连接错误或超时?"}
    Upstream -->|是| Map502Upstream["返回 502 连接失败"]
    Upstream -->|否| Timeout{"TimeoutException?"}
    Timeout -->|是| Map502Timeout["返回 502 响应超时"]
    Timeout -->|否| Map500["返回 500 内部错误"]
    Map503 --> WriteJson["写 JSON {code,message,data}"]
    MapRse --> WriteJson
    Map502Upstream --> WriteJson
    Map502Timeout --> WriteJson
    Map500 --> WriteJson

图示来源

  • GatewayErrorHandler.java:1-98

章节来源

  • GatewayErrorHandler.java:1-98

StickyUnavailableException:统一错误语义

StickyUnavailableException 是一个运行时异常,封装了自定义 HTTP 状态码和人类可读消息。工厂方法 serviceUnavailable 默认返回 503。

它的设计目标是表达“粘性路由不可用”,而不是普通的网络故障。粘性路由不可用的一个重要语义是:不自动切换到其他节点。因为不同节点拥有不同的本地数据和内存状态,盲目切换只会把请求送到没有该用户数据的机器。

章节来源

  • StickyUnavailableException.java:1-25

依赖关系分析

粘性路由的核心依赖链如下:

classDiagram
    class GatewayApplication
    class CorsConfig
    class WebClientConfig
    class RequestIdFilter
    class GatewayErrorHandler
    class StickyUnavailableException
    class StickyRouteFilter
    class LoginRequestFilter
    class LoginResponseFilter
    class TokenResolver
    class UserRouteService
    class GatewayAttributes

    GatewayApplication --> StickyRouteFilter : "启动后启用"
    GatewayApplication --> GatewayErrorHandler : "启动后启用"
    StickyRouteFilter --> StickyUnavailableException : "抛出粘性不可用"
    StickyRouteFilter --> LoginRequestFilter : "依赖登录标记"
    StickyRouteFilter --> LoginResponseFilter : "依赖登录响应后处理"
    StickyRouteFilter --> TokenResolver : "解析 x-token"
    StickyRouteFilter --> UserRouteService : "查询/绑定用户路由"
    StickyRouteFilter --> GatewayAttributes : "读写内部属性"
    LoginRequestFilter --> GatewayAttributes : "写入 LOGIN_REQUEST / LOGIN_USERNAME"
    LoginResponseFilter --> GatewayAttributes : "读取 SERVICE_ID / LOGIN_CHOSEN_NODE_ID"
    GatewayErrorHandler --> StickyUnavailableException : "识别粘性异常"
    RequestIdFilter --> GatewayAttributes : "写入 REQUEST_ID"

图示来源

  • GatewayApplication.java:1-23
  • StickyRouteFilter.java:1-180
  • LoginRequestFilter.java:1-120
  • LoginResponseFilter.java:1-176
  • TokenResolver.java:1-100
  • UserRouteService.java:1-117
  • GatewayAttributes.java:1-31
  • GatewayErrorHandler.java:1-98
  • StickyUnavailableException.java:1-25

性能与 Netty/WebFlux 注意事项

网关运行在 Spring WebFlux 和 Netty 之上,因此必须遵循响应式编程和非阻塞原则。

避免阻塞 IO

  • 所有数据库访问都通过 JDBC + ReactiveStringRedisTemplate 配合 Schedulers.boundedElastic() 完成,避免在 Netty 事件循环线程上执行阻塞 SQL。
  • 登录响应解析、token 解析、用户路由缓存写入等 CPU 或 Redis 操作尽量使用响应式 API;阻塞部分放在 boundedElastic 调度器。
  • 健康检查使用专用的 WebClient,避免和业务转发共享同一通道。

合理使用调度器

  • TokenResolver 调用 StpUtil.getLoginIdByToken 时使用 boundedElastic,因为 sa-token 可能涉及阻塞 Redis 访问。
  • UserRouteService 的数据库回源和绑定操作也使用 boundedElastic。
  • LoginResponseFilter 的解析和绑定以 fire-and-forget 方式订阅,避免客户端断连取消传播中断数据库写操作。

SSE 心跳与长连接兼容性

  • GatewayErrorHandler 在响应已提交时不再改写状态码,而是抛出异常,让 Netty 按既有连接语义断开。这对 SSE、流式响应、Range 下载很重要。
  • 登录响应捕获不会改变业务响应内容;即使绑定失败,也只记录日志,不影响前端收到的登录结果。
  • 跨域配置暴露 Content-Disposition,便于附件下载和长连接场景中正确识别响应头。
  • 生产环境建议关注后端是否启用 gzip 压缩;网关登录请求会将 Accept-Encoding 改为 identity,以便 LoginResponseFilter 能正确解析响应体。

WebClient 与超时

  • WebClientConfig 设置的连接超时和响应超时仅用于探活。业务转发由 Spring Cloud Gateway 管理,不应误以为修改这里就能调大上传、SSE 或大文件下载的超时。
  • 如果业务出现 502 超时,应先区分是 Netty 连接超时、TCP 超时、还是上游应用处理慢;后者可能需要调整后端超时、网关代理超时或业务处理逻辑。

章节来源

  • WebClientConfig.java:1-26
  • TokenResolver.java:1-100
  • UserRouteService.java:1-117
  • LoginResponseFilter.java:1-176
  • GatewayErrorHandler.java:1-98
  • CorsConfig.java:1-39

503 错误语义与排障清单

503 在不同场景下的含义

StickyUnavailableException 与 StickyRouteFilter 共同定义了粘性路由下 503 的多种语义。这些语义的关键共性是:503 不代表临时网络抖动,而是代表“不能按粘性策略继续转发”。

场景 触发位置 503 含义 典型排查方向
服务不存在 StickyRouteFilter.filter 命中的服务未加载或未注册 检查 gateway_service.path_prefix、管理接口是否成功写入
服务停用 StickyRouteFilter.filter 服务已存在但 enabled=false 管理接口查看服务状态
无可用节点 decideForLogin、anonymousNode 服务有配置但没有健康节点 检查节点 base_url、防火墙、后端进程、健康检查
绑定节点不可用 route 用户绑定的节点 enabled=false 或健康检查 DOWN 管理接口查看节点状态,恢复后仍保持绑定
用户未绑定节点 bindToDefaultNode 用户登录后仍未绑定,且没有默认节点 检查 gateway_service.default_node_id 和用户路由表
用户已绑定但节点不存在或停用 route 绑定记录指向的节点被删除或停用 管理接口解绑或重绑
flowchart TD
    Start["粘性路由决策"] --> ServiceCheck{"服务存在且启用?"}
    ServiceCheck -->|否| NoService["503:服务不存在或已停用"]
    ServiceCheck -->|是| IsLogin{"是否为登录请求?"}
    IsLogin -->|是| LoginPath["查用户名绑定 → 未绑定则轮询候选"]
    LoginPath --> Candidate{"有候选节点?"}
    Candidate -->|否| NoCandidate["503:服务当前没有可用节点"]
    Candidate -->|是| RouteStep["校验绑定节点"]
    IsLogin -->|否| NormalPath["x-token 解析 userId → 查绑定 → 无绑定则默认节点兜底"]
    NormalPath --> DefaultCheck{"有默认节点?"}
    DefaultCheck -->|否| NoBind["503:用户未绑定节点"]
    DefaultCheck -->|是| BindTry["尝试 bindIfAbsent"]
    BindTry --> RouteStep
    RouteStep --> NodeValid{"节点存在且启用?"}
    NodeValid -->|否| NodeDisabled["503:用户绑定的节点不存在或已停用"]
    NodeValid --> HealthCheck{"健康检查 UP?"}
    HealthCheck -->|否| NodeDown["503:用户绑定的后端节点不可用"]
    HealthCheck -->|是| Forward["重写 URL 并转发"]

图示来源

  • StickyRouteFilter.java:1-180
  • StickyUnavailableException.java:1-25

排障清单

1. CORS 拦截问题

  • 现象:浏览器报跨域错误,或预检请求失败。
  • 排查步骤:
    • 确认后端是否已配置全局 CorsFilter。
    • 如果后端已有跨域处理,不要开启网关 gateway.cors.enabled=true,否则会出现重复 Access-Control-Allow-Origin。
    • 如需网关收口跨域,确认允许的来源模式、方法、请求头与后端一致。
    • 确认前端是否需要带 Cookie;网关默认 allowCredentials=false。
    • 检查响应头是否包含 X-Gateway-Node、Content-Disposition、X-Request-Id。

章节来源

  • CorsConfig.java:1-39
  • README.md:28-33

2. WebClient 超时问题

  • 现象:健康检查失败、节点频繁 DOWN。
  • 排查步骤:
    • 确认 GatewayProperties.healthCheck.timeout 是否合理。
    • 确认探活 WebClient 使用的是 WebClientConfig 创建的 Bean,而不是业务转发通道。
    • 区分连接超时、TCP 超时和上游处理超时:前者可能由网络或后端未启动导致,后者可能是后端负载过高。
    • 注意业务转发不走这里,不要把上传、SSE、大文件下载超时误配到探活 WebClient。

章节来源

  • WebClientConfig.java:1-26

3. 全局异常未捕获

  • 现象:返回 HTML 错误页、空体、或非预期 JSON。
  • 排查步骤:
    • 确认 GatewayErrorHandler 已被 Spring 扫描并注册。
    • 确认异常未被业务层提前消费或包装成未识别类型。
    • 检查响应是否已提交:SSE、流式响应中途出错时,网关不会强制改状态码,而是记录日志并断开连接。
    • 核对 502 和 503 的区别:502 通常是上游连接失败或超时;503 通常是粘性路由不可用。

章节来源

  • GatewayErrorHandler.java:1-98

4. 请求 ID 缺失

  • 现象:日志无法串联一次请求,多网关或多节点难以定位。
  • 排查步骤:
    • 确认 RequestIdFilter 已注册为组件并被 Spring 扫描。
    • 检查客户端是否传递 X-Request-Id;若为空,网关会自动生成。
    • 确认下游日志是否读取 gateway.requestId 属性。
    • 如果是管理接口或测试工具,确保响应头中也包含 X-Request-Id。

章节来源

  • RequestIdFilter.java:1-34
  • GatewayAttributes.java:1-31

5. 粘性路由异常

  • 现象:登录成功但仍 503,或业务请求 503。
  • 排查步骤:
    • 区分 503 原因:服务不存在、服务停用、无可用节点、绑定节点不可用、用户未绑定节点。
    • 使用 /gateway/admin/status 查看服务、节点、健康状态、绑定数量。
    • 检查 gateway_service.default_node_id 是否正确。
    • 检查 gateway_user_route 表是否有用户绑定记录。
    • 确认节点健康检查连续失败次数是否达到 DOWN 阈值。

章节来源

  • StickyRouteFilter.java:1-180
  • StickyUnavailableException.java:1-25
  • README.md:96-113

6. 登录绑定异常

  • 现象:登录后仍按匿名轮询,或下次登录又换节点。
  • 排查步骤:
    • 确认登录路径匹配 service.loginFullPath。
    • 确认登录响应结构符合 {code:200, data:{token, userId, username}}。
    • 检查登录响应是否超过 256KB;超限会跳过绑定解析,但不会阻断登录。
    • 检查 gateway:token:{serviceId}:{token} 是否写入 Redis。
    • 检查 gateway_user_route 是否新增用户绑定。

章节来源

  • LoginRequestFilter.java:1-120
  • LoginResponseFilter.java:1-176
  • TokenResolver.java:1-100
  • UserRouteService.java:1-117

结论

网关基础设施层的关键价值在于:为粘性路由提供稳定的启动上下文、可配置的跨域边界、可控的探活 WebClient、可追踪的请求 ID、统一的全局异常出口,以及明确的“粘性不可用”错误语义。

其中,503 不是简单的“系统忙”,而是一个业务语义信号:当前请求不能按用户粘性策略继续转发。它可能表示服务不存在、服务停用、无可用节点、绑定节点不可用,或者用户未绑定节点。无论哪种情况,网关都不应自动切换到其他节点,以避免把请求打到没有该用户数据的机器上。

在实际运维中,应优先结合 X-Request-Id、管理接口状态、PostgreSQL 路由表和 Redis 缓存进行定位;在网络层则需特别注意 Netty/WebFlux 的非阻塞特性、SSE 长连接兼容性和 WebClient 超时的适用范围。