跳转到正文

缓存与兼容加密 ​

交互示例 ​

查看示例源码
tsx
import { useI18n } from '@/hooks'
import { getStorage, hasStorage, removeStorage, setStorage } from '@/utils'
import {
  NButton,
  NCard,
  NFlex,
  NFormItem,
  NInput,
  NRadioButton,
  NRadioGroup,
} from 'naive-ui'
import DemoPage from '../components/DemoPage'
import DemoResult from '../components/DemoResult'

export default defineComponent({
  name: 'CacheDemo',
  setup() {
    const { t } = useI18n('demoDetails')
    const value = ref('Ray')
    const scope = ref<'sessionStorage' | 'localStorage'>('sessionStorage')
    const suffix = ref('name')
    const selectedKey = computed(() => `ray:showcase:${suffix.value.trim()}`)
    const current = ref<string | null>(null)
    const operation = ref('cache.read')
    const keyId = useId()
    const valueId = useId()

    const read = () => {
      current.value = hasStorage(selectedKey.value, scope.value)
        ? getStorage<string>(selectedKey.value, scope.value)
        : null
    }

    watch([selectedKey, scope], read, { immediate: true })

    return () => (
      <DemoPage title={t('cache.title')} description={t('cache.intro')}>
        <div class="r-demo-grid">
          <NCard title={t('cache.write')}>
            <div class="r-demo-card-stack">
              <NRadioGroup
                v-model:value={scope.value}
                aria-label={t('cache.scope')}
              >
                <NRadioButton value="sessionStorage">
                  sessionStorage
                </NRadioButton>
                <NRadioButton value="localStorage">localStorage</NRadioButton>
              </NRadioGroup>
              <NFormItem
                label={t('cache.key')}
                labelProps={{ for: keyId }}
                showFeedback={false}
              >
                <NInput
                  inputProps={{ id: keyId }}
                  v-model:value={suffix.value}
                  maxlength={32}
                />
              </NFormItem>
              <NFormItem
                label={t('cache.value')}
                labelProps={{ for: valueId }}
                showFeedback={false}
              >
                <NInput
                  inputProps={{ id: valueId }}
                  v-model:value={value.value}
                />
              </NFormItem>
              <NFlex>
                <NButton
                  type="primary"
                  disabled={!suffix.value.trim()}
                  onClick={() => {
                    setStorage(selectedKey.value, value.value, scope.value)
                    operation.value = 'cache.write'
                    read()
                  }}
                >
                  {t('cache.write')}
                </NButton>
                <NButton
                  onClick={() => {
                    operation.value = 'cache.read'
                    read()
                  }}
                >
                  {t('cache.read')}
                </NButton>
                <NButton
                  onClick={() => {
                    removeStorage(selectedKey.value, scope.value)
                    operation.value = 'cache.remove'
                    read()
                  }}
                >
                  {t('cache.remove')}
                </NButton>
              </NFlex>
            </div>
          </NCard>
          <NCard title={t('result')}>
            <DemoResult label={t(operation.value)}>
              <pre>{selectedKey.value}</pre>
              <pre>
                {current.value === null
                  ? t('cache.missing')
                  : JSON.stringify(current.value)}
              </pre>
            </DemoResult>
          </NCard>
        </div>
      </DemoPage>
    )
  },
})

Web Storage ​

默认使用 sessionStorage,传 'localStorage' 跨刷新保存。所有读写值按 JSON 序列化。类型参数仅影响 TypeScript,不能确认缓存格式。

API行为
setStorage(key, value, storageType?, options?)写入可序列化值,空键、循环引用或浏览器拒绝写入时记录错误。
getStorage<T>(key, storageType?, options?)缺键、损坏或不可读时返回 options.defaultValue 或 null;显式 JSON null 仍返回 null。
hasStorage(key, storageType?, options?)检查键存在,存储不可访问时返回 false,不验证 JSON 内容。
removeStorage(key, storageType?, options?)删除单键。也可传 __all__、__all_sessionStorage__ 或 __all_localStorage__ 做批量删除。
prefixCacheKey(key, { customPrefix }?)拼接自定义前缀或默认 APP_CATCH_KEY_PREFIX,分隔符需包含在前缀内。

缓存方法只有在 options.prefix: true 时才调用前缀函数,prefixKey 覆盖默认值。启用非空前缀时,批量删除只影响匹配的键;空前缀会清整个对应存储区域。读写和删除使用同一套前缀选项。Pinia 插件使用自己的持久化配置,修改工具前缀不会迁移 Pinia 的历史数据。

ts
import { getStorage, removeStorage, setStorage } from '@/utils'

const options = { prefix: true, prefixKey: 'inventory:' }
export function saveOrderFilter(status: string) {
  setStorage('order-filter', { status }, 'sessionStorage', options)
}
export const readOrderFilter = () =>
  getStorage<{ status: string }>('order-filter', 'sessionStorage', options)
export const clearOrderFilter = () =>
  removeStorage('order-filter', 'sessionStorage', options)

独立包中的 createStorage(storage, prefix?) 为宿主提供的同步后端生成 get、set、remove。它使用相同的 JSON 格式;读取失败返回 null,写入或删除失败不向外抛错。不能序列化的值(包括 undefined、函数和循环引用)不会覆盖已有内容。前缀直接与键拼接。

兼容 AES JSON ​

下面的实验可以比较缓存键前缀,并用示例口令把一段 JSON 加密后还原。

查看示例源码
tsx
import { useI18n } from '@/hooks'
import { decrypt, encrypt, prefixCacheKey } from '@/utils'
import { NButton, NFlex, NInput } from 'naive-ui'
import DemoPage from './components/DemoPage'
import DemoResult from './components/DemoResult'

export default defineComponent({
  name: 'DocsStorageUtils',
  setup() {
    const { t } = useI18n('docsExamples')
    const text = (key: string) => t<string>(key)
    const key = ref('order-filter')
    const prefix = ref('orders:')
    const input = ref(text('storage.initial'))
    const ciphertext = ref('')
    const restored = ref('')
    const passphrase = 'ray-template-example-only'
    const cacheKey = computed(() =>
      prefixCacheKey(key.value, { customPrefix: prefix.value }),
    )

    return () => (
      <DemoPage
        title={text('storage.title')}
        description={text('storage.intro')}
      >
        <NFlex>
          <NInput
            v-model:value={prefix.value}
            aria-label={text('storage.prefix')}
          />
          <NInput v-model:value={key.value} aria-label={text('storage.key')} />
        </NFlex>
        <DemoResult label={text('storage.resultKey')}>
          <code>{cacheKey.value}</code>
        </DemoResult>
        <NInput
          v-model:value={input.value}
          aria-label={text('storage.plainText')}
        />
        <NFlex>
          <NButton
            onClick={() => {
              ciphertext.value = encrypt({ status: input.value }, passphrase)
              restored.value = ''
            }}
          >
            {text('storage.encrypt')}
          </NButton>
          <NButton
            disabled={!ciphertext.value}
            onClick={() => {
              restored.value = JSON.stringify(
                decrypt(ciphertext.value, passphrase),
              )
            }}
          >
            {text('storage.decrypt')}
          </NButton>
        </NFlex>
        <DemoResult label={text('storage.ciphertext')}>
          <code>{ciphertext.value}</code>
        </DemoResult>
        <DemoResult label={text('storage.restored')}>
          <code>{restored.value}</code>
        </DemoResult>
      </DemoPage>
    )
  },
})

encrypt(data, key?) 返回 JSON 密文,decrypt(ciphertext, key?) 解码。可用字符串口令或 CryptoJS WordArray,同一数据须使用同类型和内容的 key。字符串沿用 OpenSSL 兼容格式,原始密钥使用随机 IV,字符串序列化为 IV:密文。错误密文或密钥会记录错误并返回 undefined,无法 JSON 序列化的输入会使加密抛错。

CRYPTO_KEY 是应用公开的历史兼容常量。这个工具用于读取既有本地数据(如演示锁屏),不能保护服务端密钥或替代认证。迁移格式时先保留对历史密文的读取能力。

缓存实现 · 加密 · 解密