useTokenManager

管理访问令牌与刷新令牌的状态、持久化与自动刷新。

前置依赖

依赖参数

参数名	类型	说明
env.vue.ref	Ref<T> 工厂	创建响应式引用
env.vue.computed	Computed<T> 工厂	创建计算属性
env.vue.watchEffect	() => void	副作用追踪与持久化写入
env.vue.onMounted	() => void	初始化读入存储与定时任务
env.vue.onUnmounted	() => void	清理定时器
env.host.setTimeout	typeof setTimeout	安排刷新任务
env.host.clearTimeout	typeof clearTimeout	取消刷新任务
env.host.now	() => number	获取当前时间（毫秒）
env.storage.getItem	Storage['getItem']	读取持久化令牌
env.storage.setItem	Storage['setItem']	写入持久化令牌
env.storage.removeItem	Storage['removeItem']	清除持久化令牌

环境要求

• Vue 运行时函数: 通过依赖注入传入（类型仅可从 vue 导入）
• 定时器/时间源: 提供 setTimeout/clearTimeout 与 now()
• 存储实现: 可使用浏览器 localStorage 或自定义存储

函数签名

function useTokenManager(
  options: UseTokenManagerOptions,
  env: UseTokenManagerEnvironment
): UseTokenManagerReturn

interface UseTokenManagerOptions {
  refreshThresholdMs?: number
  storageKeys?: { access?: string; refresh?: string; expiresAt?: string }
  refreshFn?: (refreshToken: string) => Promise<{
    accessToken: string
    refreshToken?: string
    expiresAt: number
  } | null>
}

interface UseTokenManagerReturn {
  accessToken: Ref<string | null>
  refreshToken: Ref<string | null>
  expiresAt: Ref<number | null>
  isRefreshing: Ref<boolean>
  error: Ref<string | null>
  isAuthenticated: Ref<boolean>
  setTokens(input: {
    accessToken: string
    refreshToken?: string | null
    expiresAt?: number | null
    expiresInSeconds?: number | null
  }): void
  clearTokens(): void
  forceRefresh(): Promise<boolean>
}

参数

参数名	类型	必填	说明
options.refreshThresholdMs	number	否	到期前多少毫秒触发刷新，默认 60000
options.storageKeys	{ access?, refresh?, expiresAt? }	否	覆盖默认持久化键名
options.refreshFn	(refreshToken) => Promise<...>	否	刷新令牌的异步函数，返回 null 表示刷新失败

返回值

类型	说明
UseTokenManagerReturn	提供令牌状态、设置/清理方法与强制刷新能力

工作原理

1. 组件挂载时，从存储中读入 accessToken、refreshToken 与 expiresAt。
2. 根据 expiresAt 与 refreshThresholdMs 安排定时刷新（存在 refreshFn 时）。
3. 调用 setTokens 会更新内存与存储，并重新安排刷新任务。
4. forceRefresh 使用 refreshFn 主动刷新，失败时写入 error 并返回 false。
5. 组件卸载时取消所有定时器并清理引用。