Cookie 存储 (Cookie Store)

@pt/utils/modules/storage 提供了基于 js-cookie 的存储封装，支持加密存储和灵活的 cookie 选项。

CookieStore 类

CookieStore 类提供了对浏览器 Cookie 的增强封装，支持数据加密、域名自动检测和现代浏览器的安全策略。

基本用法

typescript

import { cookieStore, setSetting } from '@pt/utils/modules/storage';

// 设置普通数据
cookieStore.set('user', { name: 'John' });

// 设置加密数据（第三个参数为true表示加密）
cookieStore.set('token', 'secret123', true);

// 获取数据
const user = cookieStore.get('user');

// 移除数据
cookieStore.remove('user');

// 清除所有数据
cookieStore.clear();

主要特性

1. 数据加密

支持敏感数据加密存储，保护用户隐私和安全信息。

typescript

// 存储加密的认证令牌
cookieStore.set('authToken', 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...', true);

// 存储加密的用户凭证
cookieStore.set('credentials', {
  username: 'admin',
  sessionId: 'abc123'
}, true);

// 获取时自动解密
const token = cookieStore.get('authToken');
const credentials = cookieStore.get('credentials');

2. 域名自动检测

智能处理 cookie 域，自动适配不同环境。

3. SameSite 策略

支持现代浏览器的 cookie 安全策略配置。

4. 批量操作

支持批量获取和设置数据。

API 参考

`cookieStore.set(key: string, value: any, encrypt?: boolean)`

设置 Cookie 数据。

参数：

key: Cookie 键名
value: 要存储的值（会自动序列化）
encrypt (可选): 是否加密存储，默认为 false

`cookieStore.get(key: string): any`

获取 Cookie 数据，自动反序列化和解密。

`cookieStore.remove(key: string)`

移除指定的 Cookie。

`cookieStore.clear()`

清除所有 Cookie。

高级配置

环境变量配置

可通过环境变量 VITE_JS_COOKIE_OPTIONS 配置 Cookie 选项：

javascript

// 在 .env 文件中
VITE_JS_COOKIE_OPTIONS={"path":"/","sameSite":"Strict","secure":true}

可配置选项：

path: Cookie 路径，默认为 "/"
domain: Cookie 域名
expires: 过期时间（天数）
secure: 是否仅通过 HTTPS 传输
sameSite: SameSite 策略（"Strict" | "Lax" | "None"）

动态配置

typescript

import { setSetting } from '@pt/utils/modules/storage';

// 动态设置 Cookie 选项
setSetting({
  cookieOptions: {
    path: '/',
    sameSite: 'Strict',
    secure: true,
    expires: 7 // 7天后过期
  }
});

完整示例

用户认证场景

typescript

import { cookieStore } from '@pt/utils/modules/storage';

interface AuthData {
  token: string;
  refreshToken: string;
  expiresAt: number;
}

// 登录成功后存储认证信息（加密）
function saveAuthData(authData: AuthData) {
  cookieStore.set('auth', authData, true);
}

// 获取认证信息
function getAuthData(): AuthData | null {
  return cookieStore.get('auth');
}

// 检查是否已登录
function isAuthenticated(): boolean {
  const auth = getAuthData();
  if (!auth) return false;
  return Date.now() < auth.expiresAt;
}

// 登出
function logout() {
  cookieStore.remove('auth');
}

多语言偏好设置

typescript

interface UserPreferences {
  language: string;
  theme: 'light' | 'dark';
  fontSize: number;
}

// 保存用户偏好
function savePreferences(prefs: UserPreferences) {
  cookieStore.set('preferences', prefs);
}

// 加载用户偏好
function loadPreferences(): UserPreferences {
  return cookieStore.get('preferences') || {
    language: 'zh-CN',
    theme: 'light',
    fontSize: 14
  };
}

安全建议

1. 敏感数据加密

始终对敏感数据使用加密存储：

typescript

// ✅ 推荐：加密存储
cookieStore.set('authToken', token, true);
cookieStore.set('apiKey', key, true);

// ❌ 不推荐：明文存储敏感数据
cookieStore.set('password', pwd); // 不要这样做！

2. 设置合适的过期时间

typescript

import { setSetting } from '@pt/utils/modules/storage';

// 为敏感数据设置较短的过期时间
setSetting({
  cookieOptions: {
    expires: 1 // 1天后过期
  }
});

3. 使用 HTTPS

在生产环境中始终使用 secure 标志：

typescript

setSetting({
  cookieOptions: {
    secure: true, // 仅通过 HTTPS 传输
    sameSite: 'Strict'
  }

完整示例

用户会话管理

typescript

import { cookieStore, setSetting } from '@pt/utils/modules/storage';

// 配置 Cookie 选项
setSetting({
  cookieOptions: {
    path: '/',
    secure: true,
    sameSite: 'Strict',
    expires: 7 // 7天
  }
});

interface UserSession {
  userId: string;
  username: string;
  token: string;
  refreshToken: string;
  expiresAt: number;
}

class SessionManager {
  private readonly SESSION_KEY = 'user_session';
  
  // 保存会话
  saveSession(session: UserSession) {
    cookieStore.set(this.SESSION_KEY, session, true); // 加密存储
  }
  
  // 获取会话
  getSession(): UserSession | null {
    const session = cookieStore.get(this.SESSION_KEY);
    if (!session) return null;
    
    // 检查是否过期
    if (Date.now() > session.expiresAt) {
      this.clearSession();
      return null;
    }
    
    return session;
  }
  
  // 更新令牌
  updateToken(token: string, expiresAt: number) {
    const session = this.getSession();
    if (session) {
      session.token = token;
      session.expiresAt = expiresAt;
      this.saveSession(session);
    }
  }
  
  // 清除会话
  clearSession() {
    cookieStore.remove(this.SESSION_KEY);
  }
  
  // 检查是否已登录
  isAuthenticated(): boolean {
    return this.getSession() !== null;
  }
}

export const sessionManager = new SessionManager();

typescript

import { cookieStore, setSetting } from '@pt/utils/modules/storage';

// 配置跨域 Cookie
setSetting({
  cookieOptions: {
    domain: '.example.com', // 允许子域名访问
    path: '/',
    secure: true,
    sameSite: 'None' // 允许跨站点请求
  }
});

// 在主域名设置 Cookie
cookieStore.set('shared_data', { value: 'data' });

// 子域名可以访问
// sub1.example.com 和 sub2.example.com 都能读取

记住我功能

typescript

import { cookieStore, setSetting } from '@pt/utils/modules/storage';

interface LoginForm {
  username: string;
  password: string;
  rememberMe: boolean;
}

function handleLogin(form: LoginForm) {
  if (form.rememberMe) {
    // 记住用户名，30天过期
    setSetting({
      cookieOptions: { expires: 30 }
    });
    cookieStore.set('remembered_username', form.username);
  } else {
    // 清除记住的用户名
    cookieStore.remove('remembered_username');
  }
  
  // 执行登录逻辑...
}

// 页面加载时恢复用户名
function loadRememberedUsername(): string | null {
  return cookieStore.get('remembered_username');
}

常见问题

Cookie 单个值不能超过 4KB，存储大量数据时应考虑使用 Local Storage。

typescript

// ❌ 不推荐：存储大量数据
cookieStore.set('largeData', hugeObject);

// ✅ 推荐：使用 Local Storage
localStorage.set('largeData', hugeObject);

2. 跨域问题

Cookie 受同源策略限制，跨域时需要正确配置。

typescript

// 配置允许跨域的 Cookie
setSetting({
  cookieOptions: {
    domain: '.example.com',
    sameSite: 'None',
    secure: true // sameSite=None 必须配合 secure=true
  }
});

3. HttpOnly 限制

通过 JavaScript 设置的 Cookie 无法设置 HttpOnly 标志，需要服务端设置。

typescript

// ⚠️ 注意：无法通过 JavaScript 设置 HttpOnly
// HttpOnly Cookie 只能由服务端设置
// 用于防止 XSS 攻击窃取 Cookie

性能优化

1. 批量操作

typescript

// ❌ 不推荐：多次调用
cookieStore.set('key1', value1);
cookieStore.set('key2', value2);
cookieStore.set('key3', value3);

// ✅ 推荐：合并数据
cookieStore.set('batchData', {
  key1: value1,
  key2: value2,
  key3: value3
});

typescript

// ❌ 不推荐：每个配置项单独存储
cookieStore.set('theme', 'dark');
cookieStore.set('language', 'zh-CN');
cookieStore.set('fontSize', 14);

// ✅ 推荐：合并为一个配置对象
cookieStore.set('userPreferences', {
  theme: 'dark',
  language: 'zh-CN',
  fontSize: 14
});

安全最佳实践总结

敏感数据加密：始终对敏感信息使用加密存储
HTTPS only：生产环境启用 secure 标志
SameSite 保护：使用 Strict 或 Lax 防止 CSRF 攻击
合理过期时间：根据数据敏感度设置合适的过期时间
最小权限原则：只存储必要的信息
定期清理：及时清除不再需要的 Cookie

typescript

// 安全配置示例
setSetting({
  cookieOptions: {
    path: '/',
    secure: true,           // 仅 HTTPS
    sameSite: 'Strict',     // 严格的同站策略
    expires: 1              // 1天过期
  }
});

// 加密存储敏感数据
cookieStore.set('authToken', token, true);
cookieStore.set('apiKey', key, true);
});

Cookie 存储 (Cookie Store) ​

CookieStore 类 ​

基本用法 ​

主要特性 ​

1. 数据加密 ​

2. 域名自动检测 ​

3. SameSite 策略 ​

4. 批量操作 ​

API 参考 ​

cookieStore.set(key: string, value: any, encrypt?: boolean) ​

cookieStore.get(key: string): any ​

cookieStore.remove(key: string) ​

cookieStore.clear() ​

高级配置 ​

环境变量配置 ​

动态配置 ​

完整示例 ​

用户认证场景 ​

多语言偏好设置 ​

安全建议 ​

1. 敏感数据加密 ​

2. 设置合适的过期时间 ​

3. 使用 HTTPS ​

完整示例 ​

用户会话管理 ​

跨域 Cookie 配置 ​

记住我功能 ​

常见问题 ​

1. Cookie 大小限制 ​

2. 跨域问题 ​

3. HttpOnly 限制 ​

性能优化 ​

1. 批量操作 ​

2. 减少 Cookie 数量 ​

安全最佳实践总结 ​

Cookie 存储 (Cookie Store)

CookieStore 类

基本用法

主要特性

1. 数据加密

2. 域名自动检测

3. SameSite 策略

4. 批量操作

API 参考

`cookieStore.set(key: string, value: any, encrypt?: boolean)`

`cookieStore.get(key: string): any`

`cookieStore.remove(key: string)`

`cookieStore.clear()`

高级配置

环境变量配置

动态配置

完整示例

用户认证场景

多语言偏好设置

安全建议

1. 敏感数据加密

2. 设置合适的过期时间

3. 使用 HTTPS

完整示例

用户会话管理

跨域 Cookie 配置

记住我功能

常见问题

1. Cookie 大小限制

2. 跨域问题

3. HttpOnly 限制

性能优化

1. 批量操作

2. 减少 Cookie 数量

安全最佳实践总结