Vue / 系统课时

持久化必要状态

持久化必要状态

管理后台刷新后应保留主题、侧栏和少量身份展示信息,但缓存不能无限有效,更不能把敏感凭据直接写入浏览器存储。本课将实现带版本号、过期时间和迁移逻辑的 Pinia 持久化方案。

学习目标

  • 区分适合持久化、只应驻留内存和必须由服务端保存的状态
  • 为缓存增加版本、过期时间和迁移逻辑
  • 在退出登录、版本升级和缓存损坏时安全清理状态

先划定持久化边界

适合写入 localStorage 的状态应同时满足两个条件:刷新后仍有价值,泄露后不会直接扩大账号权限。主题模式、侧栏折叠、内容密度、语言偏好,以及用于界面展示的最小身份信息通常符合要求。

访问令牌、刷新令牌、密码、验证码、完整权限集合和敏感业务数据不应直接持久化到 localStorage。令牌优先使用 HttpOnly Cookie 或只保存在内存中;权限应在会话恢复后重新向服务端获取,避免缓存过期权限继续生效。

状态 建议位置 原因
主题、布局偏好 localStorage 低敏感,刷新后仍需使用
用户 ID、显示名 可持久化最小副本 仅用于界面占位,不能作为鉴权依据
Access Token 内存或 HttpOnly Cookie 降低脚本读取和长期泄露风险
菜单与权限 内存,登录后重新获取 服务端可能随时调整

设计带版本和过期时间的缓存

不要直接保存 Store 的整个 $state。更稳妥的做法是定义明确的缓存结构,只选择必要字段,并在外层增加 version、savedAt 和 expiresAt。读取时依次检查 JSON 是否可解析、版本是否可迁移、缓存是否过期。

状态持久化读取与失效流程

下面的模块可直接放入 src/stores/appPreferences.ts。它只保存允许持久化的字段,并兼容旧版缓存。

ts
import { defineStore } from 'pinia'

const STORAGE_KEY = 'admin:preferences'
const CACHE_VERSION = 2
const CACHE_TTL = 30 * 24 * 60 * 60 * 1000

type ThemeMode = 'light' | 'dark' | 'system'

interface PersistedStateV2 {
  version: 2
  savedAt: number
  expiresAt: number
  data: {
    theme: ThemeMode
    sidebarCollapsed: boolean
    density: 'comfortable' | 'compact'
    identity: {
      userId: string
      displayName: string
    } | null
  }
}

interface PersistedStateV1 {
  version: 1
  data: {
    darkMode: boolean
    sidebarCollapsed: boolean
    userName?: string
  }
}

function migrate(raw: PersistedStateV1 | PersistedStateV2): PersistedStateV2 | null {
  if (raw.version === 2) return raw
  if (raw.version !== 1) return null

  const now = Date.now()
  return {
    version: 2,
    savedAt: now,
    expiresAt: now + CACHE_TTL,
    data: {
      theme: raw.data.darkMode ? 'dark' : 'light',
      sidebarCollapsed: raw.data.sidebarCollapsed,
      density: 'comfortable',
      identity: raw.data.userName
        ? { userId: '', displayName: raw.data.userName }
        : null,
    },
  }
}

function readCache(): PersistedStateV2['data'] | null {
  const text = localStorage.getItem(STORAGE_KEY)
  if (!text) return null

  try {
    const migrated = migrate(JSON.parse(text))
    if (!migrated || migrated.expiresAt <= Date.now()) {
      localStorage.removeItem(STORAGE_KEY)
      return null
    }
    return migrated.data
  } catch {
    localStorage.removeItem(STORAGE_KEY)
    return null
  }
}

export const useAppPreferencesStore = defineStore('appPreferences', {
  state: () => ({
    theme: 'system' as ThemeMode,
    sidebarCollapsed: false,
    density: 'comfortable' as 'comfortable' | 'compact',
    identity: null as PersistedStateV2['data']['identity'],
  }),
  actions: {
    hydrate() {
      const cached = readCache()
      if (cached) this.$patch(cached)
    },
    persist() {
      const now = Date.now()
      const payload: PersistedStateV2 = {
        version: CACHE_VERSION,
        savedAt: now,
        expiresAt: now + CACHE_TTL,
        data: {
          theme: this.theme,
          sidebarCollapsed: this.sidebarCollapsed,
          density: this.density,
          identity: this.identity,
        },
      }
      localStorage.setItem(STORAGE_KEY, JSON.stringify(payload))
    },
    clearSessionIdentity() {
      this.identity = null
      this.persist()
    },
    clearAllPersistedState() {
      localStorage.removeItem(STORAGE_KEY)
      this.$reset()
    },
  },
})

这是项目模块示例,依赖已安装的 Pinia,并由应用入口调用 hydrate()。当偏好变化时调用 persist();退出登录时调用 clearSessionIdentity(),保留与账号无关的主题和布局偏好。

接入应用并验证

在创建 Pinia 后恢复缓存,再挂载应用,能够避免页面先按默认主题渲染、随后突然切换。主题或布局发生变化时再主动保存,不要对整个 Store 做无限频率的深度监听。

ts
import { createApp } from 'vue'
import { createPinia } from 'pinia'
import App from './App.vue'
import { useAppPreferencesStore } from './stores/appPreferences'

const app = createApp(App)
const pinia = createPinia()

app.use(pinia)

const preferencesStore = useAppPreferencesStore(pinia)
preferencesStore.hydrate()

app.mount('#app')

生效行为:刷新页面后,未过期且版本可识别的主题、侧栏和密度设置会恢复;损坏、过期或无法迁移的缓存会被删除并回退到默认值。启动开发服务器进行验证:

bash
npm run dev

预期输出:

text
VITE ready in <TIME> ms
Local: http://localhost:<PORT>/

实际启动时间和端口可能不同。修改主题后刷新页面,应保持当前主题;手动把缓存中的 expiresAt 改成过去时间,再刷新页面,应恢复默认设置并删除旧缓存。

处理升级、退出与多标签页

缓存结构发生不兼容变化时应提升版本号,并在 migrate() 中显式迁移。无法确认语义的旧数据不要强行复用,直接失效比错误恢复更安全。

退出登录必须清理持久化身份副本和对应内存状态,但可以保留与账号无关的主题、密度与布局偏好。若后台允许同一账号在多个标签页使用,还可以监听 storage 事件:其他标签页清除身份时,当前标签页同步执行退出或重新拉取会话。

缓存只负责改善体验,不能作为身份真实性、权限有效性或业务数据正确性的依据。所有安全判断仍应由服务端完成。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

持久化必要状态

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通