refactor: 增强代码注释以提升可读性和维护性

2026-05-18 10:10:16 +08:00
parent 84afd6e6c0
commit a2300b3a29
22 changed files with 192 additions and 1 deletions
@@ -22,6 +22,14 @@ import org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandl
@ConditionalOnProperty(value = "api-decrypt.enabled", havingValue = "true")
 public class ApiDecryptAutoConfiguration {

+    /**
+     * 注册 API 加解密过滤器。
+     *
+     * @param properties API 解密配置
+     * @param requestMappingHandlerMapping 请求映射处理器
+     * @param handlerExceptionResolver 异常处理器
+     * @return API 加解密过滤器
+     */
    @Bean
    @FilterRegistration(
        name = "cryptoFilter",
@@ -31,27 +31,57 @@ public class EncryptorAutoConfiguration {
    @Autowired
    private EncryptorProperties properties;

+    /**
+     * 创建字段加解密管理器。
+     *
+     * @param mybatisPlusProperties MyBatis-Plus 配置
+     * @return 字段加解密管理器
+     */
    @Bean
    public EncryptorManager encryptorManager(MybatisPlusProperties mybatisPlusProperties) {
        validateEncryptorProperties(properties);
        return new EncryptorManager(mybatisPlusProperties.getTypeAliasesPackage());
    }

+    /**
+     * 创建加密上下文工厂。
+     *
+     * @return 加密上下文工厂
+     */
    @Bean
    public EncryptContextFactory encryptContextFactory() {
        return new EncryptContextFactory(properties);
    }

+    /**
+     * 创建加密字段处理器。
+     *
+     * @param encryptorManager 加解密管理器
+     * @param encryptContextFactory 加密上下文工厂
+     * @return 加密字段处理器
+     */
    @Bean
    public EncryptedFieldProcessor encryptedFieldProcessor(EncryptorManager encryptorManager, EncryptContextFactory encryptContextFactory) {
        return new EncryptedFieldProcessor(encryptorManager, encryptContextFactory);
    }

+    /**
+     * 创建 MyBatis 入参加密拦截器。
+     *
+     * @param encryptedFieldProcessor 加密字段处理器
+     * @return MyBatis 入参加密拦截器
+     */
    @Bean
    public MybatisEncryptInterceptor mybatisEncryptInterceptor(EncryptedFieldProcessor encryptedFieldProcessor) {
        return new MybatisEncryptInterceptor(encryptedFieldProcessor);
    }

+    /**
+     * 创建 MyBatis 出参解密拦截器。
+     *
+     * @param encryptedFieldProcessor 加密字段处理器
+     * @return MyBatis 出参解密拦截器
+     */
    @Bean
    public MybatisDecryptInterceptor mybatisDecryptInterceptor(EncryptedFieldProcessor encryptedFieldProcessor) {
        return new MybatisDecryptInterceptor(encryptedFieldProcessor);
@@ -74,4 +104,3 @@ public class EncryptorAutoConfiguration {
 }


-
@@ -17,6 +17,11 @@ public class EncryptContextFactory {

    private final EncryptorProperties defaultProperties;

+    /**
+     * 构造加密上下文工厂。
+     *
+     * @param defaultProperties 默认加密配置
+     */
    public EncryptContextFactory(EncryptorProperties defaultProperties) {
        this.defaultProperties = defaultProperties;
    }
@@ -19,6 +19,12 @@ public class EncryptedFieldProcessor {
    private final EncryptorManager encryptorManager;
    private final EncryptContextFactory contextFactory;

+    /**
+     * 构造加密字段处理器。
+     *
+     * @param encryptorManager 加解密管理器
+     * @param contextFactory 加密上下文工厂
+     */
    public EncryptedFieldProcessor(EncryptorManager encryptorManager, EncryptContextFactory contextFactory) {
        this.encryptorManager = encryptorManager;
        this.contextFactory = contextFactory;
@@ -29,6 +29,13 @@ public class CryptoFilter implements Filter {
    private final RequestMappingHandlerMapping requestMappingHandlerMapping;
    private final HandlerExceptionResolver handlerExceptionResolver;

+    /**
+     * 构造加解密过滤器。
+     *
+     * @param properties API 解密配置
+     * @param requestMappingHandlerMapping 请求映射处理器
+     * @param handlerExceptionResolver 异常处理器
+     */
    public CryptoFilter(ApiDecryptProperties properties,
                        RequestMappingHandlerMapping requestMappingHandlerMapping,
                        HandlerExceptionResolver handlerExceptionResolver) {
@@ -25,6 +25,14 @@ public class DecryptRequestBodyWrapper extends HttpServletRequestWrapper {

    private final byte[] body;

+    /**
+     * 解密请求体并缓存为可重复读取的 JSON 请求体。
+     *
+     * @param request 原始请求
+     * @param privateKey RSA 私钥
+     * @param headerFlag 加密密钥请求头
+     * @throws IOException 读取请求体异常
+     */
    public DecryptRequestBodyWrapper(HttpServletRequest request, String privateKey, String headerFlag) throws IOException {
        super(request);
        // 获取 AES 密码 采用 RSA 加密
@@ -26,6 +26,12 @@ public class EncryptResponseBodyWrapper extends HttpServletResponseWrapper {
    private PrintWriter printWriter;
    private Charset charset;

+    /**
+     * 构造加密响应包装器。
+     *
+     * @param response 原始响应
+     * @throws IOException 创建输出流异常
+     */
    public EncryptResponseBodyWrapper(HttpServletResponse response) throws IOException {
        super(response);
        this.byteArrayOutputStream = new ByteArrayOutputStream();
@@ -62,11 +68,23 @@ public class EncryptResponseBodyWrapper extends HttpServletResponseWrapper {
        byteArrayOutputStream.reset();
    }

+    /**
+     * 获取已缓存的响应字节。
+     *
+     * @return 响应字节数组
+     * @throws IOException 刷新响应缓冲异常
+     */
    public byte[] getResponseData() throws IOException {
        flushBuffer();
        return byteArrayOutputStream.toByteArray();
    }

+    /**
+     * 获取已缓存的响应内容。
+     *
+     * @return 响应文本
+     * @throws IOException 刷新响应缓冲异常
+     */
    public String getContent() throws IOException {
        flushBuffer();
        return byteArrayOutputStream.toString(charset);