Satoken网关转发后调用方如何透传Token？

Question

在基于 Sa-Token 实现网关统一鉴权的微服务架构中，常见问题为：**网关（如 Spring Cloud Gateway）完成 Sa-Token 解析与校验后，下游服务无法获取原始 Token，导致业务层无法调用 Sa-Token 的 `StpUtil.getLoginId()` 等方法进行权限校验或上下文操作。** 根本原因在于：网关默认仅做鉴权拦截，并未将解析出的 token（如 `satoken` 请求头或 cookie 中的值）或登录信息（如 loginId、tokenSign）透传至下游服务；而 Sa-Token 默认依赖本地请求上下文（`RequestContextHolder`）提取 token，跨服务后该上下文丢失。若仅靠网关转发原始请求头（如 `Authorization`），下游服务因未集成 Sa-Token 或未配置 `SaTokenConfigure`，仍无法识别和解析。 该问题直接导致权限链路断裂、用户上下文丢失、`StpUtil` 工具类失效，是 Sa-Token 网关化落地中最典型、最易被忽视的“透传断点”。

Answer 1

```html

一、现象层：网关鉴权成功，下游服务却“不认识用户”

典型日志表现：java.lang.RuntimeException: 当前上下文未获取到有效 token；调用 StpUtil.getLoginId() 返回 null 或抛出 NotLoginException。前端请求经 Gateway 鉴权放行后，业务服务日志中完全无 Sa-Token 初始化痕迹——这是最表层的“失联”信号。

二、机制层：Sa-Token 的上下文生命周期与微服务边界冲突

• Sa-Token 默认基于 RequestContextHolder 绑定 ThreadLocal 请求上下文，生命周期仅限单 JVM 实例内一次 HTTP 请求
• 网关（如 Spring Cloud Gateway）是响应式非阻塞架构，WebFilter 中解析的 loginId 无法自动延续至下游服务线程
• 下游服务若未显式配置 @EnableSaToken + SaTokenConfigure，则 StpUtil 将退化为“空壳”，不触发任何 token 解析逻辑

三、链路层：透传断点的四大关键缺失环节

环节	缺失项	后果
网关侧	未将原始 token 值写入 X-Auth-Token 等标准透传头	下游无 token 原始载荷
网关侧	未注入 loginId、tokenSign 等元数据至请求头	下游无法免解析复用认证结果
下游服务	缺少 SaTokenConfig 中 setTokenName("satoken") 与 header 映射配置	即使收到 token 头也无法识别
下游服务	未启用 @EnableSaToken 或遗漏 StpInterface 实现	权限校验能力未激活

四、方案层：三级透传加固策略（推荐生产级组合）

1. 基础透传：网关在 GlobalFilter 中提取并重写 Header
   

   exchange.getRequest().mutate()
       .header("X-Auth-Token", tokenValue)
       .header("X-Login-Id", String.valueOf(loginId))
       .build();

2. 可信增强：网关生成 tokenSign 并签名透传（防篡改），下游通过 SaSignUtil.checkSign() 校验
3. 上下文重建：下游服务自定义 SaTokenProcessor，从 X-Login-Id 直接注入登录态：
   

   StpUtil.login(loginId, true); // 强制建立本地上下文

五、架构层：可视化透传链路（Mermaid 流程图）

flowchart LR
  A[Client] -->|Authorization: Bearer xxx| B[Gateway]
  B -->|X-Auth-Token: xxx
X-Login-Id: 1001
X-Token-Sign: SHA256| C[Service-A]
  C --> D{SaTokenFilter}
  D -->|tokenName=“X-Auth-Token”| E[StpUtil.getLoginId()]
  E --> F[正常执行业务逻辑]
  style B fill:#4CAF50,stroke:#388E3C
  style C fill:#2196F3,stroke:#1976D2

六、避坑指南：高频误操作清单

• ❌ 仅转发原始 Authorization 头，但下游未配置 setTokenName("Authorization")
• ❌ 在 Gateway 中调用 StpUtil.getLoginId() 后直接丢弃，未透传至下游
• ❌ 下游使用 sa-token-spring-boot-starter 但未添加 @EnableSaToken 注解
• ❌ 忽略跨服务时间差导致的 token 过期，未同步网关与下游的 timeout 配置

七、进阶实践：基于 Sa-Token 的分布式上下文桥接器

封装 DistributedStpContextBridge 工具类，支持：

• 自动从 X-* 头还原 StpUtil 所需全部上下文字段
• 兼容 Feign/RestTemplate/OpenFeign 的自动 header 注入
• 集成 MDC，将 loginId 注入日志链路追踪（如 SkyWalking）

八、验证清单：上线前必检 5 项

1. ✅ 网关 Filter 日志确认输出 Forwarding token to service: xxx
2. ✅ 下游服务启动日志含 SaTokenConfiguration initialized
3. ✅ curl -H 'X-Auth-Token: xxx' http://svc/user/info 返回正确 loginId
4. ✅ 断点调试进入 Sa-Token 源码，确认 getTokenValue() 读取的是 X-Auth-Token
5. ✅ 调用 StpUtil.hasRole("admin") 返回 true（非空指针或异常）

```