Encrypt 加密模块概览

com.molandev.core.encrypt 是 Molan Core 的加密模块，提供了多层次、多场景的数据加密解决方案，涵盖数据库字段加密、接口通信加密、签名校验和敏感信息脱敏等功能。

核心功能

功能	说明	项目使用频率	文档
请求参数加密	@EncryptedParam 注解自动解密	⭐⭐⭐ 登录密码加密	详细说明
数据库字段加密	@Enc 注解透明加解密	暂未使用	详细说明
混合加密通信	RSA + AES 双层加密	暂未使用	详细说明
签名校验	防篡改、防重放攻击	暂未使用	详细说明
敏感信息脱敏	@Sensitive 注解脱敏	暂未使用	详细说明

快速开始

请求参数加密（项目中实际使用）

前端使用 RSA 公钥加密密码传输，后端使用 @EncryptedParam 注解自动解密：

// 登录接口
@PostMapping("/login")
public JsonResult<LoginResult> login(String account,
                                     @EncryptedParam String password,
                                     String imgId, String imgCode) {
    return loginService.doLogin(account, password);
}

前端加密：

import { encrypt } from '@/utils/crypto'

const encryptedPassword = encrypt(password)  // RSA 公钥加密

后端自动解密： @EncryptedParam 注解会在参数绑定时自动解密，业务代码拿到的是明文密码。

密码哈希（业务侧，非 encrypt 包）

登录密码哈希/校验使用 Spring Security 的 PasswordEncoder（BCryptPasswordEncoder），由业务模块注册 Bean，不在 core.encrypt 内。

@Service
@RequiredArgsConstructor
public class LoginService {
    private final PasswordEncoder passwordEncoder;

    public JsonResult<LoginResult> doLogin(String account, String password) {
        UserDetail userDetail = sysPermissionService.getUserDetail(account);
        if (!passwordEncoder.matches(password, userDetail.getPassword())) {
            return JsonResult.invalid("用户名或密码错误");
        }
        // 登录成功...
    }
}

特性：

• BCrypt 算法，自动加盐
• 无法反向解密，只能 matches 校验

项目中的实际应用

登录密码加密与验证

代码位置： base-service/.../auth/controller/LoginController.java、LoginService.java

// Controller 层 - 参数自动解密
@PostMapping("/login")
public JsonResult<LoginResult> login(String account,
                                     @EncryptedParam String password,
                                     String imgId, String imgCode) {
    return loginService.doLogin(account, password);
}

// Service 层 - 密码校验
if (!passwordEncoder.matches(password, userDetail.getPassword())) {
    return JsonResult.invalid("用户名或密码错误");
}

完整流程：

1. 前端使用 RSA 公钥加密密码
2. 后端 @EncryptedParam 自动解密为明文
3. PasswordEncoder.matches 与数据库中的 BCrypt 密文比对
4. 验证通过则登录成功

📖 详细说明 → 登录策略文档

配置说明

molandev:
  encrypt:
    # 请求参数加密
    params:
      enabled: true
      key: ${RSA_PRIVATE_KEY}  # RSA 私钥

  # BCrypt 强度（业务认证配置，非 encrypt 包）
  security:
    password:
      strength: 12

⚠️ 安全建议：RSA 私钥应从环境变量或配置中心读取，不要硬编码在配置文件中。

其他功能（项目中暂未使用）

以下功能模块代码已实现，但当前项目中未启用。如需使用，请参考对应子文档。

数据库字段加密

使用 @Enc 注解标记实体字段，MyBatis 拦截器自动加解密：

@Data
@TableName("t_user")
public class User {
    private Long id;

    @Enc  // 插入时自动加密，查询时自动解密
    private String idCard;

    @Enc
    private String phone;
}

📖 详细说明 → 数据库加密文档

混合加密通信

RSA + AES 混合加密，保护 HTTP 请求/响应：

// 后端配置启用
molandev:
  encrypt:
    hybrid:
      enabled: true
      public-key: ${RSA_PUBLIC_KEY}
      private-key: ${RSA_PRIVATE_KEY}

前端使用随机 AES 密钥加密数据，再用 RSA 公钥加密 AES 密钥传输。后端自动解密。

📖 详细说明 → 混合加密文档

签名校验

防止请求被篡改和重放攻击：

molandev:
  encrypt:
    sign:
      enabled: true
      secret: ${SIGN_SECRET}
      expire-time: 300  # 5分钟有效期

前端生成签名（HMAC-SHA256 + 时间戳 + nonce），后端自动校验。

📖 详细说明 → 签名校验文档

敏感信息脱敏

使用 @Sensitive 注解在 JSON 序列化时自动脱敏：

@Data
public class UserVO {
    private Long id;

    @Sensitive(type = SensitiveTypes.PHONE)
    private String phone;  // 138****5678

    @Sensitive(type = SensitiveTypes.EMAIL)
    private String email;  // a***@example.com
}

📖 详细说明 → 脱敏文档

异常处理

签名 / 混合加解密等 Filter 在校验失败时会抛出 SignException、HybridEncryptException。

core 的 ExceptionWrapFilter（最外层）会将其映射为规范响应：

• JsonResult.invalid(message)（HTTP 200，业务码 2001）
• 未知异常 → JsonResult.failed("系统异常")（不暴露堆栈）

应用侧无需再写额外的 GlobalErrorFilter。

总结

com.molandev.core.encrypt 提供了：

• ✅ 请求参数自动解密（@EncryptedParam，项目已使用）
• ✅ 数据库字段透明加解密（@Enc）
• ✅ 混合加密通信（RSA + AES）
• ✅ 签名校验防篡改
• ✅ 敏感信息自动脱敏（@Sensitive）

密码哈希使用业务侧 Spring Security PasswordEncoder，不属于本包。