refactor: ♻️ 重构存储键命名规范

2025-09-09 11:03:27 +08:00
parent e84d87d403
commit 070a43d540
5 changed files with 148 additions and 79 deletions
--- a/src/constants/index.ts
+++ b/src/constants/index.ts
@@ -1,4 +1,118 @@
-export const ROLE_ROOT = "ROOT";
+/**
+ * 项目常量统一管理
+ *
+ * 存储键命名规范：
+ * - 使用小写 + 冒号分隔 + 名称空间
+ * - 格式：myapp:user:token
+ * - 便于清理和避免冲突
+ * - 当需要版本升级、兼容旧数据，可在 key 中加入版本如 myapp:v2:user:token。
+ */

-// 🔗 导出所有存储键常量
-export * from "./storage-keys";
+// 🏷️ 应用前缀常量
+export const APP_PREFIX = "vea";
+
+// 📦 存储键统一管理
+export const STORAGE_KEYS = {
+  // 🔐 用户认证相关
+  ACCESS_TOKEN: `${APP_PREFIX}:auth:access_token`, // JWT 访问令牌，用于 API 请求认证
+  REFRESH_TOKEN: `${APP_PREFIX}:auth:refresh_token`, // JWT 刷新令牌，用于获取新的访问令牌
+  REMEMBER_ME: `${APP_PREFIX}:auth:remember_me`, // 记住登录状态，控制登录持久化
+
+  // 🏗️ 系统核心相关
+  DICT_CACHE: `${APP_PREFIX}:system:dict_cache`, // 字典数据缓存，存储系统字典配置信息
+
+  // 🎨 系统设置相关
+  SHOW_TAGS_VIEW: `${APP_PREFIX}:ui:show_tags_view`, // 是否显示标签页视图
+  SHOW_APP_LOGO: `${APP_PREFIX}:ui:show_app_logo`, // 是否显示应用 Logo
+  SHOW_WATERMARK: `${APP_PREFIX}:ui:show_watermark`, // 是否显示水印
+  LAYOUT: `${APP_PREFIX}:ui:layout`, // 布局模式：vertical(垂直) | horizontal(水平) | mix(混合)
+  SIDEBAR_COLOR_SCHEME: `${APP_PREFIX}:ui:sidebar_color_scheme`, // 侧边栏颜色方案：light(浅色) | dark(深色)
+  THEME: `${APP_PREFIX}:ui:theme`, // 主题模式：light(浅色) | dark(深色) | auto(自动)
+  THEME_COLOR: `${APP_PREFIX}:ui:theme_color`, // 主题色，用于自定义主题色彩
+
+  // 📱 应用状态相关
+  DEVICE: `${APP_PREFIX}:app:device`, // 设备类型：desktop(桌面) | mobile(移动端) | tablet(平板)
+  SIZE: `${APP_PREFIX}:app:size`, // 屏幕尺寸：large(大) | medium(中) | small(小)
+  LANGUAGE: `${APP_PREFIX}:app:language`, // 应用语言：zh-CN(中文) | en-US(英文) 等
+  SIDEBAR_STATUS: `${APP_PREFIX}:app:sidebar_status`, // 侧边栏状态：opened(展开) | closed(收起)
+  ACTIVE_TOP_MENU_PATH: `${APP_PREFIX}:app:active_top_menu_path`, // 当前激活的顶部菜单路径
+} as const;
+
+// 🎯 功能分组的键映射对象（向后兼容）
+// 这些分组对象提供了按功能分类的存储键访问方式，便于在特定场景下批量操作
+
+// 👤 用户角色相关
+export const ROLE_ROOT = "ROOT"; // 超级管理员角色标识
+
+// 🔐 认证相关键集合
+// 包含所有与用户认证、授权相关的存储键
+export const AUTH_KEYS = {
+  ACCESS_TOKEN: STORAGE_KEYS.ACCESS_TOKEN, // JWT 访问令牌
+  REFRESH_TOKEN: STORAGE_KEYS.REFRESH_TOKEN, // JWT 刷新令牌
+  REMEMBER_ME: STORAGE_KEYS.REMEMBER_ME, // 记住登录状态
+} as const;
+
+// 🏗️ 系统核心相关键集合
+// 包含系统核心功能相关的存储键
+export const SYSTEM_KEYS = {
+  DICT_CACHE: STORAGE_KEYS.DICT_CACHE, // 字典数据缓存
+} as const;
+
+// 🎨 设置相关键集合
+// 包含所有用户界面设置和主题相关的存储键
+export const SETTINGS_KEYS = {
+  SHOW_TAGS_VIEW: STORAGE_KEYS.SHOW_TAGS_VIEW, // 是否显示标签页视图
+  SHOW_APP_LOGO: STORAGE_KEYS.SHOW_APP_LOGO, // 是否显示应用 Logo
+  SHOW_WATERMARK: STORAGE_KEYS.SHOW_WATERMARK, // 是否显示水印
+  SIDEBAR_COLOR_SCHEME: STORAGE_KEYS.SIDEBAR_COLOR_SCHEME, // 侧边栏颜色方案
+  LAYOUT: STORAGE_KEYS.LAYOUT, // 布局模式
+  THEME_COLOR: STORAGE_KEYS.THEME_COLOR, // 主题色
+  THEME: STORAGE_KEYS.THEME, // 主题模式
+} as const;
+
+// 📱 应用状态相关键集合
+// 包含应用运行时状态相关的存储键
+export const APP_KEYS = {
+  DEVICE: STORAGE_KEYS.DEVICE, // 设备类型
+  SIZE: STORAGE_KEYS.SIZE, // 屏幕尺寸
+  LANGUAGE: STORAGE_KEYS.LANGUAGE, // 应用语言
+  SIDEBAR_STATUS: STORAGE_KEYS.SIDEBAR_STATUS, // 侧边栏状态
+  ACTIVE_TOP_MENU_PATH: STORAGE_KEYS.ACTIVE_TOP_MENU_PATH, // 当前激活的顶部菜单路径
+} as const;
+
+// 📦 所有存储键的统一集合
+// 包含所有存储键的完整映射，用于批量操作或遍历
+export const ALL_STORAGE_KEYS = {
+  ...AUTH_KEYS, // 认证相关键
+  ...SYSTEM_KEYS, // 系统核心键
+  ...SETTINGS_KEYS, // 设置相关键
+  ...APP_KEYS, // 应用状态键
+} as const;
+
+// 🔧 类型定义
+export type StorageKey = (typeof STORAGE_KEYS)[keyof typeof STORAGE_KEYS];
+
+// 🧹 存储清理工具
+export const STORAGE_UTILS = {
+  // 清理所有项目相关的存储
+  clearAll: () => {
+    const keys = Object.values(STORAGE_KEYS);
+    keys.forEach((key) => {
+      localStorage.removeItem(key);
+      sessionStorage.removeItem(key);
+    });
+  },
+
+  // 清理特定分类的存储
+  clearByCategory: (category: "auth" | "system" | "ui" | "app") => {
+    const prefix = `${APP_PREFIX}:${category}:`;
+    const keys = Object.values(STORAGE_KEYS).filter((key) => key.startsWith(prefix));
+    keys.forEach((key) => {
+      localStorage.removeItem(key);
+      sessionStorage.removeItem(key);
+    });
+  },
+
+  // 获取所有项目相关的存储键
+  getAllKeys: () => Object.values(STORAGE_KEYS),
+} as const;
--- a/src/constants/storage-keys.ts
+++ b/src/constants/storage-keys.ts
@@ -1,53 +0,0 @@
-/**
- * 存储键常量统一管理
- * 包括 localStorage、sessionStorage 等各种存储的键名
- */
-
-// 🔐 用户认证相关
-export const ACCESS_TOKEN_KEY = "access_token";
-export const REFRESH_TOKEN_KEY = "refresh_token";
-export const REMEMBER_ME_KEY = "remember_me";
-
-// 📊 数据缓存相关
-export const DICT_CACHE_KEY = "dict_cache";
-
-// 🎨 系统设置相关
-export const SHOW_TAGS_VIEW_KEY = "showTagsView";
-export const SHOW_APP_LOGO_KEY = "showAppLogo";
-export const SHOW_WATERMARK_KEY = "showWatermark";
-export const LAYOUT_KEY = "layout";
-export const SIDEBAR_COLOR_SCHEME_KEY = "sidebarColorScheme";
-export const THEME_KEY = "theme";
-export const THEME_COLOR_KEY = "themeColor";
-
-// 🎯 功能分组的键映射对象
-
-// 认证相关键集合
-export const AUTH_KEYS = {
-  ACCESS_TOKEN: ACCESS_TOKEN_KEY,
-  REFRESH_TOKEN: REFRESH_TOKEN_KEY,
-  REMEMBER_ME: REMEMBER_ME_KEY,
-} as const;
-
-// 缓存相关键集合
-export const CACHE_KEYS = {
-  DICT_CACHE: DICT_CACHE_KEY,
-} as const;
-
-// 设置相关键集合
-export const SETTINGS_KEYS = {
-  SHOW_TAGS_VIEW: SHOW_TAGS_VIEW_KEY,
-  SHOW_APP_LOGO: SHOW_APP_LOGO_KEY,
-  SHOW_WATERMARK: SHOW_WATERMARK_KEY,
-  SIDEBAR_COLOR_SCHEME: SIDEBAR_COLOR_SCHEME_KEY,
-  LAYOUT: LAYOUT_KEY,
-  THEME_COLOR: THEME_COLOR_KEY,
-  THEME: THEME_KEY,
-} as const;
-
-// 📦 所有存储键的统一集合
-export const ALL_STORAGE_KEYS = {
-  ...AUTH_KEYS,
-  ...CACHE_KEYS,
-  ...SETTINGS_KEYS,
-} as const;
--- a/src/store/modules/app-store.ts
+++ b/src/store/modules/app-store.ts
@@ -6,23 +6,24 @@ import en from "element-plus/es/locale/lang/en";
 import { store } from "@/store";
 import { DeviceEnum } from "@/enums/settings/device.enum";
 import { SidebarStatus } from "@/enums/settings/layout.enum";
+import { STORAGE_KEYS } from "@/constants";

 export const useAppStore = defineStore("app", () => {
  // 设备类型
-  const device = useStorage("device", DeviceEnum.DESKTOP);
+  const device = useStorage(STORAGE_KEYS.DEVICE, DeviceEnum.DESKTOP);
  // 布局大小
-  const size = useStorage("size", defaultSettings.size);
+  const size = useStorage(STORAGE_KEYS.SIZE, defaultSettings.size);
  // 语言
-  const language = useStorage("language", defaultSettings.language);
+  const language = useStorage(STORAGE_KEYS.LANGUAGE, defaultSettings.language);
  // 侧边栏状态
-  const sidebarStatus = useStorage("sidebarStatus", SidebarStatus.CLOSED);
+  const sidebarStatus = useStorage(STORAGE_KEYS.SIDEBAR_STATUS, SidebarStatus.CLOSED);
  const sidebar = reactive({
    opened: sidebarStatus.value === SidebarStatus.OPENED,
    withoutAnimation: false,
  });

  // 顶部菜单激活路径
-  const activeTopMenuPath = useStorage("activeTopMenuPath", "");
+  const activeTopMenuPath = useStorage(STORAGE_KEYS.ACTIVE_TOP_MENU_PATH, "");

  /**
   * 根据语言标识读取对应的语言包
--- a/src/store/modules/dict-store.ts
+++ b/src/store/modules/dict-store.ts
@@ -1,9 +1,10 @@
 import { store } from "@/store";
 import DictAPI, { type DictItemOption } from "@/api/system/dict-api";
+import { STORAGE_KEYS } from "@/constants";

 export const useDictStore = defineStore("dict", () => {
  // 字典数据缓存
-  const dictCache = useStorage<Record<string, DictItemOption[]>>("dict_cache", {});
+  const dictCache = useStorage<Record<string, DictItemOption[]>>(STORAGE_KEYS.DICT_CACHE, {});

  // 请求队列（防止重复请求）
  const requestQueue: Record<string, Promise<void>> = {};
--- a/src/store/modules/settings-store.ts
+++ b/src/store/modules/settings-store.ts
@@ -2,7 +2,7 @@ import { defaultSettings } from "@/settings";
 import { SidebarColor, ThemeMode } from "@/enums/settings/theme.enum";
 import type { LayoutMode } from "@/enums/settings/layout.enum";
 import { applyTheme, generateThemeColors, toggleDarkMode, toggleSidebarColor } from "@/utils/theme";
-import { SETTINGS_KEYS } from "@/constants";
+import { STORAGE_KEYS } from "@/constants";

 // 🎯 设置项类型定义
 interface SettingsState {
@@ -26,34 +26,40 @@ type MutableSetting = Exclude<keyof SettingsState, "settingsVisible">;
 type SettingValue<K extends MutableSetting> = SettingsState[K];

 export const useSettingsStore = defineStore("setting", () => {
-  // 🎯 基础设置 - 非持久化
+  // 设置面板可见性
  const settingsVisible = ref<boolean>(false);

-  // 🎯 持久化设置 - 使用分组常量
+  // 是否显示标签页视图
  const showTagsView = useStorage<boolean>(
-    SETTINGS_KEYS.SHOW_TAGS_VIEW,
+    STORAGE_KEYS.SHOW_TAGS_VIEW,
    defaultSettings.showTagsView
  );

-  const showAppLogo = useStorage<boolean>(SETTINGS_KEYS.SHOW_APP_LOGO, defaultSettings.showAppLogo);
+  // 是否显示应用Logo
+  const showAppLogo = useStorage<boolean>(STORAGE_KEYS.SHOW_APP_LOGO, defaultSettings.showAppLogo);

+  // 是否显示水印
  const showWatermark = useStorage<boolean>(
-    SETTINGS_KEYS.SHOW_WATERMARK,
+    STORAGE_KEYS.SHOW_WATERMARK,
    defaultSettings.showWatermark
  );

+  // 侧边栏配色方案
  const sidebarColorScheme = useStorage<string>(
-    SETTINGS_KEYS.SIDEBAR_COLOR_SCHEME,
+    STORAGE_KEYS.SIDEBAR_COLOR_SCHEME,
    defaultSettings.sidebarColorScheme
  );

-  const layout = useStorage<LayoutMode>(SETTINGS_KEYS.LAYOUT, defaultSettings.layout as LayoutMode);
+  // 布局模式
+  const layout = useStorage<LayoutMode>(STORAGE_KEYS.LAYOUT, defaultSettings.layout as LayoutMode);

-  const themeColor = useStorage<string>(SETTINGS_KEYS.THEME_COLOR, defaultSettings.themeColor);
+  // 主题颜色
+  const themeColor = useStorage<string>(STORAGE_KEYS.THEME_COLOR, defaultSettings.themeColor);

-  const theme = useStorage<ThemeMode>(SETTINGS_KEYS.THEME, defaultSettings.theme);
+  // 主题模式（亮色/暗色）
+  const theme = useStorage<ThemeMode>(STORAGE_KEYS.THEME, defaultSettings.theme);

-  // 🎯 设置项映射
+  // 设置项映射，用于统一管理
  const settingsMap = {
    showTagsView,
    showAppLogo,
@@ -62,7 +68,7 @@ export const useSettingsStore = defineStore("setting", () => {
    layout,
  } as const;

-  // 🎯 监听器 - 主题变化
+  // 监听主题变化，自动应用样式
  watch(
    [theme, themeColor],
    ([newTheme, newThemeColor]) => {
@@ -73,7 +79,7 @@ export const useSettingsStore = defineStore("setting", () => {
    { immediate: true }
  );

-  // 🎯 监听器 - 侧边栏配色方案变化
+  // 监听侧边栏配色变化
  watch(
    [sidebarColorScheme],
    ([newSidebarColorScheme]) => {
@@ -82,7 +88,7 @@ export const useSettingsStore = defineStore("setting", () => {
    { immediate: true }
  );

-  // 🎯 统一的设置更新方法 - 类型安全
+  // 通用设置更新方法
  function updateSetting<K extends keyof typeof settingsMap>(key: K, value: SettingValue<K>): void {
    const setting = settingsMap[key];
    if (setting) {
@@ -90,7 +96,7 @@ export const useSettingsStore = defineStore("setting", () => {
    }
  }

-  // 🎯 主题相关的专用更新方法
+  // 主题更新方法
  function updateTheme(newTheme: ThemeMode): void {
    theme.value = newTheme;
  }
@@ -107,7 +113,7 @@ export const useSettingsStore = defineStore("setting", () => {
    layout.value = newLayout;
  }

-  // 🎯 设置面板显示控制
+  // 设置面板控制
  function toggleSettingsPanel(): void {
    settingsVisible.value = !settingsVisible.value;
  }
@@ -120,7 +126,7 @@ export const useSettingsStore = defineStore("setting", () => {
    settingsVisible.value = false;
  }

-  // 🎯 批量重置设置
+  // 重置所有设置
  function resetSettings(): void {
    showTagsView.value = defaultSettings.showTagsView;
    showAppLogo.value = defaultSettings.showAppLogo;