前言

AES是最常用的对称加密算法，加密和解密使用同一密钥，适用于数据加密存储、传输加密等场景。@pura/harmony-utils 的 EncryptUtil 封装了AES加解密方法。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。

一、AES加解密核心API

EncryptUtil 提供了以下AES方法：

方法	说明	返回类型	使用场景
encryptAES(data, key, iv?)	AES加密	string	数据加密
decryptAES(data, key, iv?)	AES解密	string	数据解密

1.1 核心特性

• 简洁易用：封装复杂逻辑为一行调用，降低使用门槛
• 类型安全：完整的TypeScript类型定义，编译期即可发现错误
• 异常处理：内置异常捕获机制，避免运行时崩溃
• 可选IV：支持初始化向量(IV)参数

1.2 AES密钥长度对照

密钥长度	算法名	安全级别	说明
128位	AES-128	高	推荐
192位	AES-192	很高	更安全
256位	AES-256	极高	最高安全

二、完整使用步骤

2.1 安装依赖

ohpm install @pura/harmony-utils

2.2 AES加密

import { EncryptUtil } from '@pura/harmony-utils';

Button('AES加密')
  .width('100%')
  .onClick(async () => {
    try {
      let plaintext = 'Hello harmony-utils!';
      let key = '1234567890123456';
      let encrypted = await EncryptUtil.encryptAES(plaintext, key);
      this.result = `原文: ${plaintext}\n密钥: ${key}\n密文: ${encrypted}`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

2.3 AES解密

Button('AES解密')
  .width('100%')
  .onClick(async () => {
    try {
      let encrypted = '加密后的字符串';
      let key = '1234567890123456';
      let decrypted = await EncryptUtil.decryptAES(encrypted, key);
      this.result = `密文: ${encrypted}\n密钥: ${key}\n原文: ${decrypted}`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

三、完整页面示例

import { EncryptUtil } from '@pura/harmony-utils';

@Entry
@Component
struct AESDemo {
  @State result: string = '';
  private key = '1234567890123456';

  build() {
    Column({ space: 12 }) {
      Button('AES加密').width('100%').onClick(async () => {
        let encrypted = await EncryptUtil.encryptAES('Hello', this.key);
        this.result = `密文: ${encrypted}`;
      });
      Button('AES解密').width('100%').onClick(async () => {
        let encrypted = await EncryptUtil.encryptAES('Hello', this.key);
        let decrypted = await EncryptUtil.decryptAES(encrypted, this.key);
        this.result = `原文: ${decrypted}`;
      });
      Text(this.result).fontSize(14).fontColor('#333333')
    }
    .padding(16)
  }
}

四、进阶用法

4.1 敏感数据加密存储

import { EncryptUtil, PreferencesUtil } from '@pura/harmony-utils';

const SECRET_KEY = 'your-secret-key-16';

async function saveSecureData(key: string, value: string): Promise<void> {
  let encrypted = await EncryptUtil.encryptAES(value, SECRET_KEY);
  await PreferencesUtil.putString(key, encrypted);
}

async function loadSecureData(key: string): Promise<string> {
  let encrypted = await PreferencesUtil.getString(key);
  return await EncryptUtil.decryptAES(encrypted, SECRET_KEY);
}

4.2 使用IV增强安全性

async function encryptWithIV(data: string, key: string): Promise<string> {
  let iv = '1234567890123456';
  return await EncryptUtil.encryptAES(data, key, iv);
}

五、注意事项

1. 密钥管理：密钥必须安全存储，泄露等于加密无效
2. 密钥长度：密钥长度必须为16/24/32字节
3. 异步方法：AES加解密是异步的，需使用await
4. 初始化依赖：使用前需确保 AppUtil.init() 已调用
5. IV重要性：使用IV可以防止相同明文产生相同密文

六、常见问题

Q1: 密钥长度不对会怎样？

会抛出异常，AES密钥必须是16/24/32字节。

Q2: 加密和解密必须用同一个密钥吗？

是的，AES是对称加密，加密和解密使用同一密钥。

Q3: IV是什么？必须提供吗？

IV是初始化向量，增加加密随机性。不提供时使用默认IV。

Q4: AES加密后数据会变大吗？

会略微增大，通常增加一个块大小（16字节）的填充。

总结

EncryptUtil 的AES加解密方法为数据安全提供了便捷支持。本文详细介绍了核心API、使用步骤、完整示例、进阶用法以及常见问题的解决方案。开发者可以利用AES实现敏感数据加密存储和传输加密。

本文基于 @pura/harmony-utils 工具库，更多功能请参考官方文档与后续系列文章。