Vue3 后台管理框架的状态管理怎么做？Pinia 3 多 Store 架构与持久化方案拆解

前言

中后台系统的复杂性一上来，状态管理就成了绕不过去的坎。用户信息、菜单权限、主题配置、Token 管理……这些状态散落在组件里，改一处动全身。很多团队在 Vue3 项目里还在用 provide/inject 硬扛，或者把 Pinia 当成一个大号缓存来用——Store 文件越写越胖，最终变成技术债。

最近在研究 vue3 后台管理框架 XYGo Admin 的前端架构时，发现它的状态管理设计有不少值得借鉴的地方。这篇文章拆解一下它的 Pinia 3 多 Store 架构、持久化策略和前后台 Token 隔离方案。

为什么需要多 Store 拆分？

很多人刚接触 Pinia 时会犯一个错：把所有的状态塞进一个 Store，取名叫 `useAppStore`。刚开始没问题，过两个月这个文件就上千行了——用户数据、菜单树、主题配置、表格设定全混在一起。

XYGo Admin 的做法是按业务边界拆 Store，项目里总共挂了 8 个独立 Store（`web/src/store/modules/`）：

| Store | 职责 |
|-------|------|
| `useUserStore` | 后台管理员 Token、用户信息、语言、锁屏状态 |
| `useMemberStore` | 前台会员状态，独立 Token + 会员信息 |
| `useSiteStore` | 站点名称、Logo、主题色、ICP 备案号 |
| `useMenuStore` | 后台菜单树状态 |
| `useSettingStore` | 主题模式、布局设置、颜色偏好 |
| `useWorktabStore` | 多标签页（Worktab）打开/关闭状态 |
| `useTableStore` | 表格列显隐、排序等偏好配置 |
| `useMemberMenuStore` | 前台会员端菜单 |

拆得够细，每个 Store 只干一件事。比如 `useSettingStore` 只管主题和布局，跟用户数据完全不沾边；`useTableStore` 只存表格的 UI 偏好，不碰业务数据。开发时不会因为改了主题色把用户 Token 搞丢。

持久化该怎么做

中后台应用最烦人的一个问题：用户刷新页面后，主题设置丢了，菜单状态也丢了。Pinia 本身不持久化，自己写 localStorage 逻辑又很容易踩版本升级的坑。

这套框架用的是 `pinia-plugin-persistedstate`，但它没有直接用原始键名，而是封装了一个 `StorageKeyManager` 生成版本化存储键：

```
格式：sys-v{version}-{storeId}
示例：sys-v3.0-user
```

这样做的好处很明显：项目升级时，如果 Store 的结构变了（比如从 v2.0 升到 v3.0），旧 localStorage 里的数据不会被误读。版本号一变，旧键自动失效，不会出现「升完级页面白屏，清缓存才好」的情况。

初始化代码很简洁：

```typescript
import { createPinia } from 'pinia'
import piniaPluginPersistedstate from 'pinia-plugin-persistedstate'

const pinia = createPinia()
pinia.use(piniaPluginPersistedstate)
```

一个 `.use()` 就把所有 Store 的持久化逻辑统一管理了，不需要在每个 Store 里重复写 `localStorage.setItem`。

前后台 Token 为什么要分开

XYGo Admin 同时有后台管理系统和前台会员端两套认证体系。很多同类项目会用同一套 Token 和同一个 `useUserStore`，然后在接口里通过角色判断权限范围——这其实是个坑。

这套框架的方案是两套 Token 完全独立：

- 后台管理员 Token → `useUserStore` → 通过 `Authorization: Bearer` 传递
- 前台会员 Token → `useMemberStore` → 通过 `Xy-User-Token` Header 传递

两个 Store 各自管理自己的持久化键和过期逻辑，互不干扰。管理员登录不会把会员 Token 冲掉，会员端也不会意外拿到管理员接口的权限。这在安全审计和权限隔离上比单 Token 方案清晰得多。

实际使用体验

在组件里使用起来跟标准 Pinia 完全一致，没有额外的心智负担：

```typescript
import { useUserStore } from '@/store/modules/user'

const userStore = useUserStore()

// 读状态
console.log(userStore.token)

// 改状态
userStore.setToken('new-token')

// 登出清理
userStore.logout()
```

不需要额外包一层 composable，也不需要手动处理 localStorage 同步——持久化插件自动完成。

总结

一个好的状态管理方案不在于用了多新的技术，而在于业务边界清晰。多 Store 拆分让每个模块职责单一，版本化持久化键解决了升级痛点，前后台 Token 隔离则从架构层面规避了安全问题。

如果你在用 Vue3 搭中后台，这套设计思路可以直接参考。项目本身也开源在 XYGo Admin，感兴趣可以拉下来跑一下看看完整实现。