API 加解密协议

Forge Admin 提供 API 接口加解密能力，通过 AES 算法保护敏感数据传输安全。

概述

加解密机制通过注解声明式启用：

注解	作用位置	说明
@ApiEncrypt	Controller 方法	自动解密请求体
@ApiDecrypt	Controller 方法	自动加密响应体

两个注解可单独使用或组合使用。

使用示例

后端

@PostMapping("/save")
@ApiEncrypt
@ApiDecrypt
public RespInfo<UserVO> save(@RequestBody String encryptedData) {
    // 框架自动解密 encryptedData 为 UserDTO
    UserVO result = userService.save(decryptedData);
    // 响应自动加密后返回
    return RespInfo.success(result);
}

密钥配置

forge:
  crypto:
    aes:
      key: 'your-aes-secret-key'    # 16/24/32 位密钥
      iv: 'your-aes-iv-vector'       # 16 位初始化向量

加密流程

┌─────────────┐         ┌─────────────┐
│   前端      │         │   后端      │
├─────────────┤         ├─────────────┤
│ 1. 构造数据 │         │             │
│ 2. AES加密  │ ──────> │ 3. 解密请求 │
│             │         │ 4. 业务处理 │
│ 6. 解密响应 │ <────── │ 5. AES加密  │
│ 7. 使用数据 │         │             │
└─────────────┘         └─────────────┘

前端对应

前端使用 postEncrypt 方法发送加密请求：

import { postEncrypt } from '@/api/crypto'

// 自动加密请求体，自动解密响应体
const result = await postEncrypt('/system/user/save', {
  username: 'admin',
  password: '123456'
})

postEncrypt 封装了以下逻辑：

1. 将请求参数 JSON 序列化
2. 使用约定密钥进行 AES-CBC 加密
3. 将密文作为请求体发送
4. 接收响应后解密密文
5. 返回明文数据

密钥协商

生产环境建议通过以下方式协商密钥，而非硬编码：

方式	说明
配置文件	开发环境使用 application.yml 配置固定密钥
环境变量	生产环境通过环境变量注入密钥
密钥交换	高安全场景使用 RSA + AES 混合加密交换密钥

注意事项

• 加密接口的 Content-Type 仍为 application/json，但请求体为密文字符串
• 加密与 HTTPS 不互斥，建议生产环境同时启用 HTTPS
• 密钥务必前后端一致，否则解密失败

⚠️ 非敏感接口不建议启用加解密，避免不必要的性能开销。