登录请求与响应过滤链.md 25 KB

登录请求与响应过滤链

本文引用的文件

  • LoginRequestFilter.java
  • StickyRouteFilter.java
  • LoginResponseFilter.java
  • GatewayAttributes.java
  • TokenResolver.java
  • UserRouteService.java
  • UserRouteRepository.java
  • gateway.sql

目录

  1. 引言
  2. 项目结构定位
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能与可靠性特征
  8. 典型登录流程时序图
  9. 边界情况处理
  10. 排错指南
  11. 结论

引言

本文聚焦 Spring Cloud Gateway 中登录相关的全局过滤器链,解释 LoginRequestFilter、StickyRouteFilter 与 LoginResponseFilter 如何协作,完成“用户 → ai-server 节点”的粘性绑定。重点包括:

  • 登录请求识别、用户名提取与属性传递;
  • 登录时“先选候选节点、不立即写库”,由响应阶段落库的原因;
  • 普通请求中 token 解析与粘性路由的差异;
  • 并发首次登录的用户名冲突、重复登录、强制踢下线等场景的处理策略。

项目结构定位

该机制位于网关模块 ai-gateway 的路由层,核心类集中在 com.zsjz.gateway.route 包下,配合 sql/gateway.sql 中的持久化模型完成用户与节点的绑定关系管理。

graph TB
    Client["客户端"] --> GW["Spring Cloud Gateway"]
    subgraph "网关路由层"
        LRF["LoginRequestFilter<br/>order=9999"]
        SRV["StickyRouteFilter<br/>order=10001"]
        LRSF["LoginResponseFilter<br/>order=NettyWriteResponseFilter-1"]
        TR["TokenResolver"]
        URS["UserRouteService"]
        UR["UserRouteRepository"]
    end
    subgraph "后端服务"
        AIS["ai-server"]
    end
    DB[("PostgreSQL")]

    Client --> LRF
    LRF --> SRV
    SRV --> AIS
    AIS --> DB
    SRV --> TR
    SRV --> URS
    LRSF --> URS
    URS --> UR
    UR --> DB

图示来源

  • LoginRequestFilter.java:1-120
  • StickyRouteFilter.java:1-180
  • LoginResponseFilter.java:1-176
  • UserRouteService.java:1-117
  • UserRouteRepository.java:1-200
  • gateway.sql:69-107

章节来源

  • LoginRequestFilter.java:1-120
  • StickyRouteFilter.java:1-180
  • LoginResponseFilter.java:1-176
  • gateway.sql:69-107

核心组件

  • LoginRequestFilter:拦截配置路径上的登录 POST 请求,缓存并解析请求体中的 username,写入 GatewayAttributes.LOGIN_REQUEST 与 LOGIN_USERNAME,并将 Accept-Encoding 改为 identity,避免后续响应被 gzip 压缩导致解析失败。
  • StickyRouteFilter:根据是否登录请求走不同分支。登录请求进入 decideForLogin,优先查已绑定节点;未绑定时轮询健康节点得到“候选节点”,仅写入 LOGIN_CHOSEN_NODE_ID,不写数据库。
  • LoginResponseFilter:在登录响应写出后解析成功结果,根据 LOGIN_CHOSEN_NODE_ID 调用 UserRouteService.bindIfAbsent 完成持久化,并把 token → userId 写入 Redis 缓存。
  • TokenResolver:提供 x-token → userId 解析,优先读本地 Redis 缓存,回退到 sa-token;登录成功后回填缓存,TTL 为 24 小时。
  • UserRouteService / UserRouteRepository:封装用户路由的 Redis + PostgreSQL 两级读写,保证并发首次登录通过数据库唯一索引裁决。

章节来源

  • GatewayAttributes.java:1-31
  • TokenResolver.java:1-100
  • UserRouteService.java:1-117
  • UserRouteRepository.java:1-200

架构总览

登录粘性路由的设计目标是:同一用户在同一个 service 下始终访问同一个 ai-server 节点,因为业务数据可能落在节点本地磁盘或内存中,不能随意漂移。

flowchart TD
    A["收到请求"] --> B{"是否为登录路径?"}
    B -->|否| C["按普通请求处理<br/>x-token → userId → 粘性节点"]
    B -->|是| D["LoginRequestFilter 解析 username<br/>写入 LOGIN_REQUEST 与 LOGIN_USERNAME"]
    D --> E["StickyRouteFilter.decideForLogin"]
    E --> F{"已绑定节点?"}
    F -->|是| G["使用已绑定节点"]
    F -->|否| H["轮询健康节点作为候选节点<br/>写入 LOGIN_CHOSEN_NODE_ID"]
    G --> I["转发到 ai-server"]
    H --> I
    I --> J{"响应是否登录成功?"}
    J -->|是| K["LoginResponseFilter 落库 bindIfAbsent<br/>并缓存 token"]
    J -->|否| L["跳过绑定,原样透传响应"]
    C --> M["后续请求按 token 粘性路由"]

图示来源

  • LoginRequestFilter.java:34-104
  • StickyRouteFilter.java:44-113
  • LoginResponseFilter.java:54-136

详细组件分析

LoginRequestFilter:登录请求识别与用户名注入

该过滤器仅在匹配服务注册中的完整登录路径且方法为 POST 时生效。它读取整个请求体(最多 64KB),尝试从 JSON 中取 username。无论解析成功与否都不阻断请求:解析失败时按匿名请求继续,让后端自行校验登录。

关键行为:

  • 设置 GatewayAttributes.LOGIN_REQUEST = true;
  • 设置 GatewayAttributes.LOGIN_USERNAME,可能为空;
  • 改写请求头 Accept-Encoding: identity;
  • 用 ServerHttpRequestDecorator 重建请求体,确保下游能再次消费;
  • 将请求交给后续过滤器链。

    flowchart TD
    Start(["进入 LoginRequestFilter"]) --> CheckPath["检查是否为服务的 loginFullPath 且为 POST"]
    CheckPath -->|否| PassThrough["直接放行,不修改请求"]
    CheckPath -->|是| ReadBody["缓存请求体(≤64KB)"]
    ReadBody --> ParseUsername["解析 username"]
    ParseUsername --> SetAttrs["写入 LOGIN_REQUEST=true<br/>写入 LOGIN_USERNAME"]
    SetAttrs --> RewriteHeader["改写 Accept-Encoding 为 identity"]
    RewriteHeader --> RebuildBody["装饰请求体以便下游再次读取"]
    RebuildBody --> Next["调用 chain.filter(exchange)"]
    

图示来源

  • LoginRequestFilter.java:34-104
  • LoginRequestFilter.java:106-120

章节来源

  • LoginRequestFilter.java:1-120
  • GatewayAttributes.java:12-20

StickyRouteFilter:粘性路由决策与节点重写

该过滤器在所有路由 URL 计算之后执行,负责把请求重写到具体 ai-server 节点。它读取 GatewayAttributes.LOGIN_REQUEST 决定走登录分支还是普通分支。

登录分支逻辑:

  1. 从 LOGIN_USERNAME 获取用户名;
  2. 通过 UserRouteService.findNodeIdByUsername 查询是否已有绑定;
  3. 若已绑定,使用该节点;
  4. 若未绑定,则通过 nodeSelector.select(service) 选择一个健康节点作为“候选节点”,写入 LOGIN_CHOSEN_NODE_ID,但不写库;
  5. 最终通过 route() 校验节点存在、启用且健康,再重写 GATEWAY_REQUEST_URL_ATTR 为目标节点 URL。

普通分支逻辑:

  • 无 x-token 或 token 解析失败:按匿名请求轮询健康节点;
  • 有 x-token:解析出 userId 后查找绑定节点;若无绑定则尝试绑定到服务配置的默认节点;仍无绑定则返回 503。

    classDiagram
    class StickyRouteFilter {
        +int getOrder()
        +filter(exchange, chain) Mono<Void>
        -decideForLogin(exchange, service) Mono<String>
        -decideForNormal(exchange, service) Mono<String>
        -bindToDefaultNode(service, userId) Mono<String>
        -anonymousNode(service) Mono<String>
        -route(exchange, chain, service, nodeId) Mono<Void>
    }
    class TokenResolver {
        +resolveUserId(serviceId, token) Mono<Long>
        +cacheToken(serviceId, token, userId) Mono<Boolean>
    }
    class UserRouteService {
        +findNodeIdByUserId(serviceId, userId) Mono<String>
        +findNodeIdByUsername(serviceId, username) Mono<String>
        +bindIfAbsent(serviceId, userId, username, nodeId) Mono<String>
    }
    StickyRouteFilter --> TokenResolver : "解析 x-token"
    StickyRouteFilter --> UserRouteService : "查询/绑定用户路由"
    

图示来源

  • StickyRouteFilter.java:1-180
  • TokenResolver.java:1-100
  • UserRouteService.java:1-117

章节来源

  • StickyRouteFilter.java:1-180
  • GatewayAttributes.java:12-28

LoginResponseFilter:登录成功后落库与 token 缓存

该过滤器在 Netty 写出响应之前拦截响应体,收集最多 256KB 的数据,判断是否为登录成功响应。成功条件包括:响应体为 JSON、code=200、data.userId 非空、data.username 非空。

如果命中成功结构:

  • 从 GatewayAttributes 取出 SERVICE_ID 与 LOGIN_CHOSEN_NODE_ID;
  • 调用 UserRouteService.bindIfAbsent(serviceId, userId, username, chosenNodeId);
  • 调用 TokenResolver.cacheToken(serviceId, token, userId);
  • 日志记录实际生效节点,用于处理并发首次登录时“另一个网关先插入”的情况;
  • 所有异常仅记录警告,不影响本次登录响应透传。

    sequenceDiagram
    participant GW as "网关"
    participant LRSF as "LoginResponseFilter"
    participant URS as "UserRouteService"
    participant TR as "TokenResolver"
    participant DB as "PostgreSQL"
    
    GW->>LRSF: 登录响应写出前拦截
    LRSF->>LRSF: 收集响应体 ≤256KB
    LRSF->>LRSF: 解析 code=200 且 data.userId、data.username 有效
    LRSF->>URS: bindIfAbsent(serviceId, userId, username, chosenNodeId)
    URS->>DB: 唯一索引裁决 INSERT ... ON CONFLICT DO NOTHING
    DB-->>URS: 返回生效节点
    URS-->>LRSF: 返回 effective nodeId
    LRSF->>TR: cacheToken(serviceId, token, userId)
    TR-->>LRSF: 写入 Redis 缓存
    LRSF-->>GW: 继续写出原始响应
    

图示来源

  • LoginResponseFilter.java:54-136
  • UserRouteService.java:69-87
  • UserRouteRepository.java:108-151
  • TokenResolver.java:54-67

章节来源

  • LoginResponseFilter.java:1-176
  • UserRouteService.java:1-117
  • UserRouteRepository.java:100-160

为什么“登录时不立即写库、由响应过滤器落库”

原因有三点:

  1. 业务状态尚未确认
    LoginRequestFilter 只拿到 username,但此时 ai-server 还未验证密码或账号状态。若在请求阶段就写库,可能出现“用户名合法但登录失败”的脏绑定。

  2. 需要知道最终 token 和 userId
    只有登录成功响应中才包含 token、userId、username。LoginResponseFilter.parseLogin 要求 code=200 且 data.userId、data.username 有效,才能进行绑定与 token 缓存。

  3. 解耦请求转发与持久化
    LoginResponseFilter 以 fire-and-forget 方式触发绑定,即使数据库或 Redis 写入失败也不影响客户端收到的登录响应。这符合“绑定失败可下次补”的容错设计。

章节来源

  • LoginRequestFilter.java:12-32
  • LoginResponseFilter.java:10-38
  • LoginResponseFilter.java:102-136

依赖关系分析

网关侧主要依赖以下外部能力:

  • GatewayRegistry:根据请求路径找到服务信息,包括 loginFullPath、defaultNodeId、节点列表;
  • NodeHealthRegistry / NodeSelector:选择健康节点;
  • ReactiveStringRedisTemplate:缓存 token、用户路由;
  • JdbcTemplate:直连 PostgreSQL 读写用户路由;
  • Sa-Token:兜底解析已存在的 token。

    graph LR
    LRF["LoginRequestFilter"] --> REG["GatewayRegistry"]
    SRV["StickyRouteFilter"] --> REG
    SRV --> NH["NodeHealthRegistry"]
    SRV --> NS["NodeSelector"]
    SRV --> TR["TokenResolver"]
    SRV --> URS["UserRouteService"]
    LRSF["LoginResponseFilter"] --> URS
    LRSF --> TR
    URS --> REDIS["Redis"]
    URS --> UR["UserRouteRepository"]
    UR --> PG["PostgreSQL"]
    

图示来源

  • LoginRequestFilter.java:20-33
  • StickyRouteFilter.java:13-38
  • LoginResponseFilter.java:13-33
  • UserRouteService.java:10-24
  • UserRouteRepository.java:10-24

章节来源

  • UserRouteService.java:10-24
  • UserRouteRepository.java:10-24
  • TokenResolver.java:10-24

性能与可靠性特征

  • 请求体限制:登录请求体最多 64KB,避免大请求阻塞网关线程;超出则按匿名轮询。
  • 响应体限制:登录响应最多 256KB,超出时跳过绑定解析但仍透传响应。
  • 异步绑定:绑定与 token 缓存使用 boundedElastic 调度器,避免阻塞网关主事件循环。
  • fire-and-forget:绑定操作独立订阅,客户端断开连接不会取消数据库写入。
  • 两级缓存:用户路由和 token 均使用 Redis 缓存,失败降级为直查数据库或 sa-token。
  • 幂等绑定:通过 ON CONFLICT DO NOTHING 与唯一索引保证并发安全,返回实际生效节点。
  • 错误容忍:缓存写入失败、解析失败、数据库异常均记录日志,不中断登录响应。

章节来源

  • LoginRequestFilter.java:28-32
  • LoginRequestFilter.java:106-120
  • LoginResponseFilter.java:43-49
  • LoginResponseFilter.java:114-136
  • UserRouteService.java:26-67
  • TokenResolver.java:26-67

典型登录流程时序图

下图展示客户端、网关、ai-server、PostgreSQL 之间的典型交互。

sequenceDiagram
    participant Client as "客户端"
    participant GW as "Gateway"
    participant LRF as "LoginRequestFilter"
    participant SRV as "StickyRouteFilter"
    participant AIS as "ai-server"
    participant LRSF as "LoginResponseFilter"
    participant URS as "UserRouteService"
    participant TR as "TokenResolver"
    participant PG as "PostgreSQL"

    Client->>GW: POST /path_prefix/login
    GW->>LRF: 全局过滤器 order=9999
    LRF->>LRF: 解析 username,写入 LOGIN_REQUEST、LOGIN_USERNAME
    LRF->>SRV: 继续过滤器链
    SRV->>SRV: decideForLogin
    SRV->>URS: findNodeIdByUsername(username)
    alt 用户未绑定
        SRV->>SRV: 轮询健康节点,写入 LOGIN_CHOSEN_NODE_ID
    else 用户已绑定
        SRV-->>SRV: 使用已绑定节点
    end
    SRV->>AIS: 转发到目标节点
    AIS->>PG: 校验账号/密码等业务
    AIS-->>GW: 返回 Result{code=200, data.token, data.userId, data.username}
    GW->>LRSF: 响应写出前拦截
    LRSF->>LRSF: 解析成功结构
    LRSF->>URS: bindIfAbsent(serviceId, userId, username, chosenNodeId)
    URS->>PG: 插入 gateway_user_route(唯一索引裁决)
    PG-->>URS: 返回生效节点
    LRSF->>TR: cacheToken(serviceId, token, userId)
    TR-->>Client: 透传原始登录响应
    Note over Client,GW: 后续请求携带 x-token,按粘性路由访问同一节点

图示来源

  • LoginRequestFilter.java:34-104
  • StickyRouteFilter.java:44-113
  • LoginResponseFilter.java:54-136
  • UserRouteService.java:69-87
  • UserRouteRepository.java:108-151

边界情况处理

用户名冲突

用户名冲突由数据库唯一索引处理。gateway_user_route 上对 (service_id, lower(username)) 建立唯一索引,多个网关实例同时插入时会由 PostgreSQL 裁决赢家。UserRouteRepository.bindIfAbsent 在冲突后重新读取赢家节点,返回实际生效节点。

flowchart TD
    A["两个网关同时登录同一用户名"] --> B["各自选出候选节点"]
    B --> C["并发 INSERT ... ON CONFLICT DO NOTHING"]
    C --> D["PostgreSQL 唯一索引裁决赢家"]
    D --> E["read back winner node"]
    E --> F["返回 effective nodeId"]

图示来源

  • UserRouteRepository.java:108-151
  • gateway.sql:85-89

章节来源

  • UserRouteRepository.java:100-160
  • gateway.sql:69-95

重复登录

如果用户已经绑定到某个节点,StickyRouteFilter.decideForLogin 会直接复用已绑定节点,不再轮询新节点。bindIfAbsent 也会发现已有路由并返回既有节点,因此重复登录不会漂移节点。

章节来源

  • StickyRouteFilter.java:66-87
  • UserRouteRepository.java:108-151

强制踢下线或被顶下线

当用户被强制踢下线或单端登录顶掉旧会话时,Sa-Token 中的 token 失效。TokenResolver.resolveFromSaToken 会返回空值,StickyRouteFilter.decideForNormal 将其视为解析失败,按匿名请求处理,最终由 ai-server 返回 401,引导客户端重新登录。

flowchart TD
    A["旧 token 被顶掉或过期"] --> B["TokenResolver 解析失败"]
    B --> C["StickyRouteFilter 按匿名请求处理"]
    C --> D["转发到 ai-server"]
    D --> E["ai-server 返回 code=401"]
    E --> F["客户端重新登录"]

图示来源

  • TokenResolver.java:69-99
  • StickyRouteFilter.java:95-105

章节来源

  • TokenResolver.java:26-99
  • StickyRouteFilter.java:91-105

登录失败不产生绑定

LoginResponseFilter.parseLogin 只对 code=200 且满足字段条件的响应进行绑定。密码错误、账号禁用、字段缺失等情况不会触发 bindIfAbsent,也不会写库。

章节来源

  • LoginResponseFilter.java:138-176

无用户名或非法登录体

LoginRequestFilter.parseUsername 对空体、超限体、非 JSON、缺少 username 字段的情况返回 null,此时 LOGIN_USERNAME 为空,StickyRouteFilter 按匿名轮询处理,由 ai-server 自行校验登录。

章节来源

  • LoginRequestFilter.java:106-120
  • StickyRouteFilter.java:91-105

排错指南

  • 登录后仍然随机跳转节点
    检查 GatewayAttributes.LOGIN_CHOSEN_NODE_ID 是否在 StickyRouteFilter 中写入,以及 LoginResponseFilter 是否成功解析登录成功响应。关注日志中“登录响应超过 KB”“登录响应未命中成功结构”等提示。

  • token 无法解析
    检查 Redis 中 gateway:token:{serviceId}:{token} 是否存在;若不存在,检查 sa-token 共享 Redis 是否可用。注意 TokenResolver 在缓存写入失败时仍允许正确请求通过。

  • 用户被绑定到预期之外节点
    检查是否存在并发首次登录,查看 LoginResponseFilter 日志中“并发首次登录:用户...实际绑定到已有节点”。这是唯一索引裁决的正常现象。

  • 节点不可用返回 503
    StickyRouteFilter.route() 会拒绝 DOWN 或停用的节点,并返回 503。这不是自动切换,因为业务数据可能在节点本地磁盘。

章节来源

  • LoginResponseFilter.java:77-136
  • TokenResolver.java:26-67
  • StickyRouteFilter.java:115-149

结论

登录粘性路由通过三层过滤器协作实现:LoginRequestFilter 在请求阶段提取用户名并标记登录请求;StickyRouteFilter 在路由阶段决定是否使用已绑定节点或生成候选节点;LoginResponseFilter 在响应阶段完成持久化与 token 缓存。该设计避免了在未确认登录成功前写库,同时通过 Redis 缓存与数据库唯一索引兼顾性能与一致性。对于用户名冲突、重复登录、token 失效等边界场景,系统采用延迟落库、匿名降级、唯一索引裁决等方式保证整体可用性。