添加双token无感刷新设计

Author: yqz

README.md

@@ -172,6 +172,25 @@ mvn -DskipTests package
 
 详细放行规则见 `SecurityConfig`。
 
+### 双 Token 与无感刷新（设计说明）
+
+**后端（无需单独端口）**
+
+- 登录成功返回 **Access Token**（短效）与 **Refresh Token**（长效），均由 `openblog.jwt.*` 配置过期时间（见上文配置表）。
+- 换发接口：`POST /api/v1/auth/refresh`，请求体为 `{ "refreshToken": "<refresh_jwt>" }`，成功时返回新的 **accessToken** 与 **refreshToken**（与登录接口同一 `AuthResponse` 结构）。
+- 与登录、文章等接口共用 **`server.port` 同一端口**；不存在「刷新专用端口」。
+
+**前端（Vue，`vue/src`）**
+
+- **`vue/src/auth/session.js`**：`isConsoleSessionValid()` 在 **access 已过期但 refresh 仍有效** 时也视为已登录，避免仅因短 token 过期被路由误判下线。
+- **`vue/src/api/http.js`**
+  - **`refreshSessionTokens()`**：直连 `/api/v1/auth/refresh` 换发双 token，**不走** `request()`，避免递归；并发多次刷新合并为 **同一 Promise**（互斥）。
+  - **`request(..., { withAuth: true })` 发起前**：若 refresh 仍可用，且「无 access」或 **access 剩余有效期不足约 90 秒」，则**主动刷新**，减少首包 401。
+  - **收到 HTTP 401**：在带鉴权请求上 **自动刷新一次并重试原请求**（带 `_refreshRetried` 标记，防止死循环）；刷新仍失败则 `clearAuth()`，在 `/console` 下跳转控制台登录。
+- **`vue/src/api/media.js`**：上传走原生 `fetch`，在 **401** 时调用 `refreshSessionTokens()` 后 **重传一次**（与 JSON 接口策略一致）。
+
+**小结**：后端只提供 REST 路径；无感刷新由前端在**同一 API 基址**上组合「主动刷新 + 401 重试 + 并发合并」完成。
+
 ---
 
 ## 测试

vue/src/api/http.js

@@ -4,7 +4,15 @@
  * - 未设置：开发环境默认连仓库里的远程后端；生产环境默认同域（与上面空字符串一致）。
  * 注意：不要用 `||`，否则空字符串会被当成假值而误用默认 IP。
  */
-import { clearAuth, getStoredAccessToken } from '../auth/session'
+import {
+  clearAuth,
+  getStoredAccessToken,
+  getStoredRefreshToken,
+  hasUsableRefreshToken,
+  isJwtExpired,
+  isLikelyJwt,
+  parseJwtPayload
+} from '../auth/session'
 
 function resolveApiBase() {
   const v = import.meta.env.VITE_API_BASE
@@ -16,21 +24,107 @@ function resolveApiBase() {
 
 export const API_BASE = resolveApiBase()
 
-const baseUrl = API_BASE
-
 function buildUrl(path) {
   // 后端统一是 /api/v1 前缀
   if (path.startsWith('http://') || path.startsWith('https://')) return path
-  return `${baseUrl}${path}`
+  return `${API_BASE}${path}`
+}
+
+/** 并发刷新合并为同一 Promise */
+let refreshInflight = null
+
+/**
+ * 使用 refreshToken 换发双 token（不经过 request，避免环）。
+ * 失败时会 clearAuth。
+ */
+export function refreshSessionTokens() {
+  if (refreshInflight) return refreshInflight
+
+  refreshInflight = (async () => {
+    const rt = getStoredRefreshToken()
+    if (!rt || !isLikelyJwt(rt) || isJwtExpired(rt)) {
+      clearAuth()
+      const err = new Error('登录已失效')
+      err.httpStatus = 401
+      throw err
+    }
+
+    const res = await fetch(buildUrl('/api/v1/auth/refresh'), {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ refreshToken: rt })
+    })
+
+    const text = await res.text()
+    let json = null
+    try {
+      json = text ? JSON.parse(text) : null
+    } catch {
+      // ignore
+    }
+
+    if (!res.ok || (json && typeof json.code === 'number' && json.code !== 0)) {
+      clearAuth()
+      const err = new Error(json?.message || '登录已失效')
+      err.httpStatus = res.status || 401
+      err.code = json?.code
+      throw err
+    }
+
+    const data = json?.data
+    if (!data?.accessToken || !data?.refreshToken) {
+      clearAuth()
+      const err = new Error('刷新返回异常')
+      err.httpStatus = 401
+      throw err
+    }
+
+    localStorage.setItem('accessToken', data.accessToken)
+    localStorage.setItem('refreshToken', data.refreshToken)
+    return data
+  })()
+
+  return refreshInflight.finally(() => {
+    refreshInflight = null
+  })
+}
+
+function accessExpiresWithinSeconds(seconds) {
+  const t = getStoredAccessToken()
+  if (!t || !isLikelyJwt(t)) return true
+  const p = parseJwtPayload(t)
+  if (typeof p.exp !== 'number') return false
+  return p.exp * 1000 - Date.now() < seconds * 1000
+}
+
+function redirectConsoleLoginIfNeeded() {
+  if (typeof window !== 'undefined' && window.location.pathname.startsWith('/console')) {
+    const redirect = window.location.pathname + window.location.search
+    window.location.assign('/console/login?redirect=' + encodeURIComponent(redirect))
+  }
 }
 
 export async function request(path, options = {}) {
+  const isRetry = Boolean(options._refreshRetried)
+  const extraHeaders = options.headers && typeof options.headers === 'object' ? options.headers : {}
   const headers = {
     'Content-Type': 'application/json',
-    ...(options.headers || {})
+    ...extraHeaders
   }
 
   if (options.withAuth) {
+    if (
+      !isRetry &&
+      hasUsableRefreshToken() &&
+      (!getStoredAccessToken() || accessExpiresWithinSeconds(90))
+    ) {
+      try {
+        await refreshSessionTokens()
+      } catch {
+        // 无 access 时交给后续分支；将过期 access 时可能仍失败，再由 401 重试
+      }
+    }
+
     const token = getStoredAccessToken()
     if (!token) {
       const err = new Error('未登录')
@@ -40,31 +134,46 @@ export async function request(path, options = {}) {
     headers.Authorization = `Bearer ${token}`
   }
 
+  const fetchOpts = { ...options }
+  delete fetchOpts.withAuth
+  delete fetchOpts._refreshRetried
+  delete fetchOpts.headers
+
   const res = await fetch(buildUrl(path), {
-    headers,
-    ...options
+    ...fetchOpts,
+    headers
   })
 
   const text = await res.text()
   let json = null
-  try {
-    json = text ? JSON.parse(text) : null
-  } catch {
-    // ignore
+  if (!_skipJson) {
+    try {
+      json = text ? JSON.parse(text) : null
+    } catch {
+      // ignore
+    }
   }
 
-  if (res.status === 401 && options.withAuth) {
-    clearAuth()
-    if (typeof window !== 'undefined' && window.location.pathname.startsWith('/console')) {
-      const redirect = window.location.pathname + window.location.search
-      window.location.assign('/console/login?redirect=' + encodeURIComponent(redirect))
+  if (res.status === 401 && options.withAuth && !isRetry) {
+    try {
+      await refreshSessionTokens()
+      return request(path, { ...options, _refreshRetried: true })
+    } catch {
+      redirectConsoleLoginIfNeeded()
+      const err = new Error('登录已失效')
+      err.httpStatus = 401
+      throw err
     }
+  }
+
+  if (res.status === 401 && options.withAuth && isRetry) {
+    clearAuth()
+    redirectConsoleLoginIfNeeded()
     const err = new Error('登录已失效')
     err.httpStatus = 401
     throw err
   }
 
-  // API 统一返回 ApiResponse，HTTP 层可能仍为 200
   if (json && typeof json.code === 'number' && json.code !== 0) {
     const msg = json.message || '请求失败'
     const err = new Error(msg)
@@ -83,4 +192,3 @@ export async function request(path, options = {}) {
 
   return json?.data ?? json
 }
-

vue/src/api/media.js

@@ -1,5 +1,5 @@
 import { getStoredAccessToken } from '../auth/session'
-import { API_BASE } from './http'
+import { API_BASE, refreshSessionTokens } from './http'
 
 function getAuthHeader() {
   const token = getStoredAccessToken()
@@ -8,23 +8,17 @@ function getAuthHeader() {
 }
 
 export async function uploadMedia(file) {
-  const fd = new FormData()
-  fd.append('file', file)
-
-  const res = await fetch(`${API_BASE}/api/v1/media/upload`, {
-    method: 'POST',
-    headers: {
-      ...getAuthHeader()
-    },
-    body: fd
-  })
-
-  const text = await res.text()
-  let json = null
-  try {
-    json = text ? JSON.parse(text) : null
-  } catch {
-    json = null
+  let { res, json } = await doUploadWithFile(file)
+
+  if (res.status === 401) {
+    try {
+      await refreshSessionTokens()
+      ;({ res, json } = await doUploadWithFile(file))
+    } catch {
+      const err = new Error('登录已失效')
+      err.httpStatus = 401
+      throw err
+    }
   }
 
   if (!res.ok) {
@@ -41,3 +35,25 @@ export async function uploadMedia(file) {
   return json?.data ?? json
 }
 
+function doUploadWithFile(file) {
+  const fd = new FormData()
+  fd.append('file', file)
+
+  return fetch(`${API_BASE}/api/v1/media/upload`, {
+    method: 'POST',
+    headers: {
+      ...getAuthHeader()
+    },
+    body: fd
+  }).then(async (res) => {
+    const text = await res.text()
+    let json = null
+    try {
+      json = text ? JSON.parse(text) : null
+    } catch {
+      json = null
+    }
+    return { res, json }
+  })
+}
+

vue/src/auth/session.js

@@ -15,6 +15,19 @@ export function getStoredAccessToken() {
   return s.length > 0 ? s : null
 }
 
+export function getStoredRefreshToken() {
+  const t = localStorage.getItem('refreshToken')
+  if (typeof t !== 'string') return null
+  const s = t.trim()
+  return s.length > 0 ? s : null
+}
+
+/** refresh JWT 仍有效且未过期 */
+export function hasUsableRefreshToken() {
+  const rt = getStoredRefreshToken()
+  return Boolean(rt && isLikelyJwt(rt) && !isJwtExpired(rt))
+}
+
 /** 是否为标准 JWT 外形（header.payload.sig） */
 export function isLikelyJwt(token) {
   return typeof token === 'string' && token.split('.').length === 3
@@ -42,10 +55,11 @@ export function clearAuth() {
   localStorage.removeItem('refreshToken')
 }
 
+/** 控制台/带鉴权前台：access 有效，或仍可用 refresh 换发（无感刷新入口） */
 export function isConsoleSessionValid() {
-  const token = getStoredAccessToken()
-  if (!token || !isLikelyJwt(token) || isJwtExpired(token)) return false
-  return true
+  const access = getStoredAccessToken()
+  if (access && isLikelyJwt(access) && !isJwtExpired(access)) return true
+  return hasUsableRefreshToken()
 }
 
 /** JWT payload 中的 role（ADMIN / AUTHOR / READER） */

vue/src/components/BlogHeader.vue

@@ -82,7 +82,7 @@ import { computed, onMounted, ref, watch } from 'vue'
 import { useRoute, useRouter } from 'vue-router'
 import { toggleTheme as applyToggle } from '../theme'
 import { fetchMe } from '../api/admin'
-import { clearAuth, getStoredAccessToken, isJwtExpired, isLikelyJwt } from '../auth/session'
+import { clearAuth, isConsoleSessionValid } from '../auth/session'
 
 defineEmits(['toggle-widgets'])
 
@@ -98,8 +98,7 @@ const displayName = computed(() => {
 })
 
 function tokenLooksValid() {
-  const t = getStoredAccessToken()
-  return Boolean(t && isLikelyJwt(t) && !isJwtExpired(t))
+  return isConsoleSessionValid()
 }
 
 async function loadMe() {