身份认证与应用安全 / 系统课时
处理刷新失败与重新登录
处理刷新失败与重新登录
刷新接口失败时,客户端不能把所有 401 都当成“再刷新一次”,否则容易形成循环请求;服务端也不应把用户被禁用、令牌撤销等内部细节全部暴露给前端。本节建立一个稳定的失败契约,让客户端明确区分“可重试”和“必须重新登录”。
学习目标
- 区分 Access Token 失效、Refresh Token 不可用和临时服务故障
- 设计不会无限刷新或无限重试的前后端处理流程
- 在需要重新认证时可靠清理会话并回到登录页
先把失败分成两类
刷新失败最重要的不是给每个内部原因设计不同页面,而是判断当前会话还有没有恢复可能。
Refresh Token 过期、被撤销、被检测到重放、签名无效,或者用户状态已经不允许继续登录,都属于不可恢复的当前会话。服务端可以在日志中保留具体原因,但对客户端统一返回 401 和稳定错误码 REAUTH_REQUIRED。数据库暂时不可用、下游密钥服务超时等短暂故障则更适合返回 503,客户端可以有限重试,而不应立即清空登录状态。

服务端给前端稳定的错误契约
在 Spring Boot 中,可以把具体异常收敛成少量外部错误码。下面是片段示例,假设这些刷新异常已经由认证服务抛出;处理器只负责把它们映射成稳定响应。
@RestControllerAdvice
public class AuthExceptionHandler {
@ExceptionHandler({
ExpiredRefreshTokenException.class,
InvalidRefreshTokenException.class,
RevokedRefreshTokenException.class,
RefreshTokenReuseException.class,
UserNotAllowedException.class
})
ResponseEntity<AuthError> handleReauthRequired(RuntimeException ex) {
return ResponseEntity.status(HttpStatus.UNAUTHORIZED)
.body(new AuthError("REAUTH_REQUIRED", "Login again"));
}
public record AuthError(String code, String message) {
}
}这段代码依赖项目中的自定义异常,不能脱离当前 Spring Boot 工程独立运行。它的目的不是隐藏服务端日志,而是让前端只依赖一个长期稳定的状态:收到 401 + REAUTH_REQUIRED 就结束当前登录会话,不再继续尝试刷新。
如果是数据库连接失败或认证服务暂时不可用,不要伪装成 REAUTH_REQUIRED。这类故障应返回 503 Service Unavailable,否则客户端会把一个临时故障误判成用户必须重新登录。
客户端只允许一次刷新链
前端遇到业务接口的 Access Token 过期后,应发起一次刷新。多个并发请求同时失败时,最好复用同一个刷新 Promise,而不是每个请求都提交一次 Refresh Token;这样也能避免轮换机制把并发刷新误判为旧令牌重放。
下面示例假设 Refresh Token 放在 HttpOnly Cookie 中,因此 JavaScript 不读取它,只对刷新接口启用 credentials: "include"。
let accessToken: string | null = null;
let refreshInFlight: Promise<boolean> | null = null;
async function refreshOnce(): Promise<boolean> {
if (!refreshInFlight) {
refreshInFlight = fetch("/auth/refresh", {
method: "POST",
credentials: "include"
})
.then(async (response) => {
if (response.ok) {
const body = await response.json();
accessToken = body.accessToken;
return true;
}
if (response.status === 401) {
const body = await response.json();
if (body.code === "REAUTH_REQUIRED") {
accessToken = null;
return false;
}
}
throw new Error(`refresh failed: ${response.status}`);
})
.finally(() => {
refreshInFlight = null;
});
}
return refreshInFlight;
}页面可见效果是:同一时刻即使多个 API 都因 Access Token 过期返回 401,也只会产生一个刷新请求;刷新成功后,调用方可以重试原请求;刷新返回 REAUTH_REQUIRED 时统一进入退出登录流程。
验证必须重新登录的响应
可以直接用一个已经过期或已撤销的 Refresh Token 验证服务端契约:
curl -i -X POST "https://<HOST>:<PORT>/auth/refresh" --cookie "refresh_token=<EXPIRED_OR_REVOKED_REFRESH_TOKEN>"预期结果:
HTTP/1.1 401
Content-Type: application/json
{"code":"REAUTH_REQUIRED","message":"Login again"}客户端收到这个响应后,应停止刷新、清除内存中的 Access Token 和用户状态,并跳转登录页。如果 Refresh Token 使用 HttpOnly Cookie,还应由服务端在注销或失败处理接口中发送过期的 Set-Cookie 来清除该 Cookie,前端不要尝试用 JavaScript 删除它。
避免三种常见循环
第一种循环是“业务 API 401 → 刷新 401 → 再刷新”,解决方法是把刷新接口排除在自动刷新拦截器之外。第二种是“刷新 503 → 永久重试”,应限制次数并使用退避。第三种是多个并发 401 同时刷新,必须用单飞机制合并请求。
重新登录不是异常兜底的最后一句话,而是认证状态机中的明确终点:只要刷新凭证已经不可恢复,就结束当前会话;只有真正的临时服务故障才允许有限重试。