📄 encrypt-api 接口加解密使用

版本说明

此功能需要 PIGX 5.8 及以上版本支持。如果您使用的是旧版本，请替换 common-encrypt-api 源码或升级到最新版本。

背景

在金融、政务等高安全要求的项目场景中，仅依赖 HTTPS 传输层加密存在以下安全风险：

1. 中间人攻击可能解密 TLS 流量获取明文
2. 服务端日志可能记录敏感数据明文
3. 前端代码可能暴露未加密的敏感参数

为此我们采用应用层加密方案实现端到端加密：前端对请求参数进行加密编码，服务端自动解密处理。

快速上手

① 添加依赖

<dependency>
    <groupId>com.pig4cloud</groupId>
    <artifactId>pigx-common-encrypt-api</artifactId>
</dependency>

② 配置加解密密钥

在 nacos/application-dev.yml 配置文件中进行配置，对所有的微服务有效

security:
  api:
    encrypt:
      enable: true   # 开启请求加解密
      aes-key: 1234567812345678 # 注意必须为16位，当前版本暂只支持 aes

单体版本 pigx-boot/application-dev.yml 配置

security:
  api:
    encrypt:
      enable: true   # 开启请求加解密
      aes-key: pigxpigxpigxpigx # 注意必须为16位,同前端密码传输的KEY

PIGX 前端处理

找到前端根目录的 .env ；开启加解密

VITE_PWD_ENC_KEY=加密密钥 （16位，注意和后端保持一致）
VITE_API_ENC_ENABLED=false

特殊：@NoEncrypt跳过加解密

在某些特殊场景下，如文件上传、下载或包含特殊字符的请求中，可能需要跳过加密处理。PigX 提供了 @NoEncrypt 注解来实现这一功能。

@NoEncrypt 注解可以应用在控制器方法上，用于标识该接口不需要进行加密/解密处理。

@NoEncrypt
@GetMapping("/local/file/{fileName}")
public void localFile(@PathVariable String fileName, HttpServletResponse response) {
  ClassPathResource resource = new ClassPathResource("file/" + fileName);
  response.setContentType("application/octet-stream; charset=UTF-8");
  IoUtil.copy(resource.getInputStream(), response.getOutputStream());
}

• 前端跳过加解密 "Enc-Flag": "false"

request({
  url: "xxx",
  headers: {
    "Enc-Flag": "false", // 通过指定 "Enc-Flag": "false"
  },
  method: "get",
  params: { xxx },
});