useDictSync

字典数据实时同步 Composable，用于监听后端字典变更并自动同步到前端缓存。

功能特性

• 🔄 实时同步 - 通过 WebSocket 监听后端字典变更
• 🎯 单例模式 - 全局共享一个连接实例，避免重复连接
• 📦 自动缓存 - 字典变更时自动清除本地缓存，按需重新加载
• 🔌 自动重连 - 支持断线自动重连和订阅恢复
• 📢 事件回调 - 支持注册字典变更回调函数

基础用法

import { useDictSync } from '@/composables'

const dictSync = useDictSync()

// 初始化连接（通常在应用启动时调用一次）
dictSync.initialize()

// 监听字典变更
const unsubscribe = dictSync.onDictChange((message) => {
  console.log('字典已更新:', message.dictCode)
  console.log('更新时间:', message.timestamp)
})

// 取消监听
unsubscribe()

// 清理连接（在应用退出时调用）
dictSync.cleanup()

在应用中集成

通常在 App.vue 或入口文件中初始化：

<script setup lang="ts">
import { useDictSync } from '@/composables'

const dictSync = useDictSync()

onMounted(() => {
  // 初始化字典同步服务
  dictSync.initialize()
})

onUnmounted(() => {
  // 清理资源
  dictSync.cleanup()
})
</script>

监听特定字典变更

import { useDictSync } from '@/composables'

const dictSync = useDictSync()

// 注册回调，监听字典变更
const unsubscribe = dictSync.onDictChange((message) => {
  // 只处理特定字典的变更
  if (message.dictCode === 'gender') {
    console.log('性别字典已更新')
    // 执行相关业务逻辑
  }
})

// 组件卸载时取消监听
onUnmounted(() => {
  unsubscribe()
})

类型定义

/**
 * 字典变更消息结构
 */
interface DictChangeMessage {
  /** 字典编码 */
  dictCode: string
  /** 时间戳 */
  timestamp: number
}

/**
 * 字典变更事件回调函数类型
 */
type DictChangeCallback = (message: DictChangeMessage) => void

/**
 * useDictSync 返回值
 */
interface DictSyncComposable {
  /** 连接状态 */
  isConnected: Ref<boolean>
  /** 连接状态详情 */
  connectionState: Ref<string>
  /** 初始化连接 */
  initialize: () => void
  /** 清理资源 */
  cleanup: () => void
  /** 注册字典变更回调 */
  onDictChange: (callback: DictChangeCallback) => () => void
}

API

返回值

名称	类型	说明
isConnected	Ref<boolean>	WebSocket 连接状态
connectionState	Ref<string>	连接状态详情（connecting/connected/disconnected）
initialize	() => void	初始化 WebSocket 连接并订阅字典主题
cleanup	() => void	关闭连接并清理资源
onDictChange	(callback) => () => void	注册字典变更回调，返回取消注册函数

工作原理

配置说明

useDictSync 内部使用 useStomp 进行实时通信（WebSocket），默认配置：

配置项	默认值	说明
reconnectDelay	20000ms	重连延迟时间
connectionTimeout	15000ms	连接超时时间
maxReconnectAttempts	3	最大重连次数
autoRestoreSubscriptions	true	自动恢复订阅

环境变量

需要在 .env 文件中配置 WebSocket 端点：

# WebSocket 端点地址
VITE_APP_WS_ENDPOINT=ws://localhost:8080/ws

如果未配置 VITE_APP_WS_ENDPOINT，字典同步功能将自动跳过初始化。

注意事项

1. 单例模式：useDictSync 采用单例模式，多次调用返回同一实例
2. 初始化时机：建议在应用启动时调用一次 initialize()
3. 资源清理：应用退出时调用 cleanup() 释放资源
4. 回调管理：注册的回调函数需要在组件卸载时取消注册

相关链接

• 字典管理
• 实时通信
• useStomp
• DictSelect 字典组件