安全工具 (Security)

@pt/utils/modules/crypto 提供了加密解密相关的工具函数，基于 CryptoJS 实现。

全局配置

可以通过全局配置函数设置默认的加密配置。

setGlobalConfig

设置简单加密的全局配置。

import { setGlobalConfig } from '@pt/utils/modules/crypto';

// 设置全局配置
setGlobalConfig({
  key: 'yourCustomKey',
  iv: 'yourCustomIV'
});

// 使用全局配置加密
const encrypted = encryptText('Hello');

// 使用全局配置解密
const decrypted = decryptText(encrypted);

setGlobalComplexConfig

设置复杂加密的全局配置。

import { setGlobalComplexConfig } from '@pt/utils/modules/crypto';

// 设置全局配置
setGlobalComplexConfig({
  key: 'yourCustomKey',
  iv: 'yourCustomIV',
  mode: CryptoJS.mode.CBC,
  padding: CryptoJS.pad.Pkcs7
});

// 临时配置会覆盖全局配置
const encrypted = encryptText('Hello', {
  key: 'temporaryKey'
});

const decrypted = decryptText(encrypted, {
  key: 'temporaryKey'
});

混合使用

// 设置全局复杂配置
setGlobalComplexConfig({
  key: 'globalKey',
  iv: 'globalIV'
});

// 使用全局配置
const encrypted1 = encryptComplex({ data: 'test1' });

// 使用临时配置
const encrypted2 = encryptComplex({ data: 'test2' }, {
  key: 'tempKey',
  iv: 'tempIV'
});

简单加密解密

适用于基本的数据加密需求，使用AES算法，配置简单。

encryptText

简单AES加密。

import { encryptText } from '@pt/utils/modules/crypto';

// 基本使用
const encrypted = encryptText('Hello, 世界');
// 'U2FsdGVkX1+k7hsrmfutPZhLlia0AhUshTZXRNBYjUw='

// 自定义密钥
const encrypted2 = encryptText('Hello, 世界', { key: 'customKey' });

decryptText

简单AES解密。

import { decryptText } from '@pt/utils/modules/crypto';

// 基本使用
const decrypted = decryptText('U2FsdGVkX1+k7hsrmfutPZhLlia0AhUshTZXRNBYjUw=');
// 'Hello, 世界'

// 自定义密钥
const decrypted2 = decryptText(encrypted2, { key: 'customKey' });

复杂加密解密

适用于需要更高安全性的场景，支持IV向量、加密模式、填充方式等配置。

encryptComplex

复杂AES加密，支持对象加密，返回大写十六进制字符串。

import { encryptComplex } from '@pt/utils/modules/crypto';

// 加密字符串
const encrypted = encryptComplex('Hello, 世界');

// 加密对象
const encrypted2 = encryptComplex({
  name: 'John',
  age: 30
});

// 自定义配置
const encrypted3 = encryptComplex('Hello', {
  key: 'customKey',
  iv: 'customIV',
  mode: CryptoJS.mode.CBC,
  padding: CryptoJS.pad.Pkcs7
});

decryptComplex

复杂AES解密，支持泛型类型。

import { decryptComplex } from '@pt/utils/modules/crypto';

// 解密字符串
const decrypted = decryptComplex<string>(encrypted);

// 解密对象
interface User {
  name: string;
  age: number;
}
const decrypted2 = decryptComplex<User>(encrypted2);
console.log(decrypted2.name); // 'John'

// 自定义配置
const decrypted3 = decryptComplex(encrypted3, {
  key: 'customKey',
  iv: 'customIV',
  mode: CryptoJS.mode.CBC,
  padding: CryptoJS.pad.Pkcs7
});

配置选项

interface AESConfig {
  key: string;      // 密钥
  iv?: string;      // 初始化向量
  mode?: typeof CryptoJS.mode.CBC;    // 加密模式
  padding?: typeof CryptoJS.pad.Pkcs7; // 填充方式
}

性能考虑

1. Base64 vs AES:

   • Base64: 仅做编码，速度极快，适合轻量场景
   • AES: 提供加密保护，计算复杂度更高

2. 影响AES性能的因素:

   • 数据块大小
   • 加密模式（CBC比ECB耗时）
   • 设备对Web Crypto API的优化程度

使用建议

1. 选择合适的加密级别:

   • 一般数据：使用encryptText/decryptText
   • 敏感数据：使用encryptComplex/decryptComplex

2. 错误处理:

try {
  const decrypted = decryptComplex(encrypted);
} catch (error) {
  console.error('解密失败:', error);
}

3. 类型安全:

interface UserData {
  id: number;
  name: string;
}

const encrypted = encryptComplex<UserData>({
  id: 1,
  name: 'John'
});

const decrypted = decryptComplex<UserData>(encrypted);
// decrypted 具有完整的类型提示

常见问题

Q: 为什么不直接打包 crypto-js？

A: crypto-js 是 CommonJS 模块，直接打包可能导致：

• 模块初始化问题（Cannot set properties of undefined）
• 增加包体积
• 版本冲突

Q: 我不想安装额外的依赖怎么办？

A: 如果不需要加密功能，可以不使用 security 模块，也就不需要安装 crypto-js。或者可以使用浏览器原生的 Web Crypto API。

Q: 如何检查是否需要安装 crypto-js？

A: 在你的代码中搜索以下导入：

import { encryptText, decryptText, encryptComplex, decryptComplex } from '@pt/utils';
// 或
import * as security from '@pt/utils/modules/crypto';

如果有使用这些功能，就需要安装 crypto-js。

注意事项

1. 密钥管理至关重要，避免硬编码在代码中
2. 考虑使用环境变量或配置文件存储密钥
3. 大数据量加密可能影响性能
4. 确保加密和解密使用相同的配置