docs 补充项目注释

2026-06-01 13:58:13 +08:00
parent 107d3326b4
commit e49f3b2260
94 changed files with 2328 additions and 68 deletions
@@ -56,7 +56,7 @@ public class EncryptorAutoConfiguration {
    /**
     * 创建加密字段处理器。
     *
-     * @param encryptorManager 加解密管理器
+     * @param encryptorManager      加解密管理器
     * @param encryptContextFactory 加密上下文工厂
     * @return 加密字段处理器
     */
@@ -87,6 +87,11 @@ public class EncryptorAutoConfiguration {
        return new MybatisDecryptInterceptor(encryptedFieldProcessor);
    }

+    /**
+     * 校验字段加解密配置完整性。
+     *
+     * @param properties 字段加解密配置
+     */
    private void validateEncryptorProperties(EncryptorProperties properties) {
        AlgorithmType algorithm = properties.getAlgorithm();
        if (algorithm == AlgorithmType.AES || algorithm == AlgorithmType.SM4) {
@@ -102,5 +107,3 @@ public class EncryptorAutoConfiguration {
    }

 }
-
-
@@ -23,7 +23,7 @@ public class EncryptedFieldProcessor {
     * 构造加密字段处理器。
     *
     * @param encryptorManager 加解密管理器
-     * @param contextFactory 加密上下文工厂
+     * @param contextFactory   加密上下文工厂
     */
    public EncryptedFieldProcessor(EncryptorManager encryptorManager, EncryptContextFactory contextFactory) {
        this.encryptorManager = encryptorManager;
@@ -58,6 +58,13 @@ public class EncryptedFieldProcessor {
            field.set(target, encryptorManager.decrypt(value, contextFactory.create(field))));
    }

+    /**
+     * 递归处理对象、集合或 Map 中声明加密注解的字段。
+     *
+     * @param sourceObject 待处理对象
+     * @param visited      已访问对象集合
+     * @param fieldHandler 字段处理回调
+     */
    private void handle(Object sourceObject, Set<Object> visited, FieldHandler fieldHandler) {
        if (ObjectUtil.isNull(sourceObject) || sourceObject instanceof String || visited.contains(sourceObject)) {
            return;
@@ -100,8 +107,8 @@ public class EncryptedFieldProcessor {
         * 处理单个加密字段。
         *
         * @param target 字段所属对象
-         * @param field 加密字段
-         * @param value 字段原始字符串值
+         * @param field  加密字段
+         * @param value  字段原始字符串值
         * @throws IllegalAccessException 字段访问失败时抛出
         */
        void handle(Object target, Field field, String value) throws IllegalAccessException;
@@ -11,6 +11,11 @@ import org.dromara.common.encrypt.core.IEncryptor;
 */
 public abstract class AbstractEncryptor implements IEncryptor {

+    /**
+     * 初始化加密执行者。
+     *
+     * @param context 加密上下文
+     */
    public AbstractEncryptor(EncryptContext context) {
        // 用户配置校验与配置注入
    }
@@ -13,6 +13,11 @@ import org.dromara.common.encrypt.utils.EncryptUtils;
 */
 public class Base64Encryptor extends AbstractEncryptor {

+    /**
+     * 初始化 Base64 加密执行者。
+     *
+     * @param context 加密上下文
+     */
    public Base64Encryptor(EncryptContext context) {
        super(context);
    }
@@ -17,6 +17,11 @@ public class RsaEncryptor extends AbstractEncryptor {

    private final EncryptContext context;

+    /**
+     * 构造 RSA 加密器。
+     *
+     * @param context 加密上下文
+     */
    public RsaEncryptor(EncryptContext context) {
        super(context);
        String privateKey = context.getPrivateKey();
@@ -53,7 +58,7 @@ public class RsaEncryptor extends AbstractEncryptor {
    /**
     * 解密
     *
-     * @param value      待加密字符串
+     * @param value 待加密字符串
     */
    @Override
    public String decrypt(String value) {
@@ -16,6 +16,11 @@ public class Sm2Encryptor extends AbstractEncryptor {

    private final EncryptContext context;

+    /**
+     * 构造 SM2 加密器。
+     *
+     * @param context 加密上下文
+     */
    public Sm2Encryptor(EncryptContext context) {
        super(context);
        String privateKey = context.getPrivateKey();
@@ -52,7 +57,7 @@ public class Sm2Encryptor extends AbstractEncryptor {
    /**
     * 解密
     *
-     * @param value      待加密字符串
+     * @param value 待加密字符串
     */
    @Override
    public String decrypt(String value) {
@@ -15,6 +15,11 @@ public class Sm4Encryptor extends AbstractEncryptor {

    private final EncryptContext context;

+    /**
+     * 构造 SM4 加密器。
+     *
+     * @param context 加密上下文
+     */
    public Sm4Encryptor(EncryptContext context) {
        super(context);
        this.context = context;
@@ -46,7 +51,7 @@ public class Sm4Encryptor extends AbstractEncryptor {
    /**
     * 解密
     *
-     * @param value      待加密字符串
+     * @param value 待加密字符串
     */
    @Override
    public String decrypt(String value) {
@@ -32,9 +32,9 @@ public class CryptoFilter implements Filter {
    /**
     * 构造加解密过滤器。
     *
-     * @param properties API 解密配置
+     * @param properties                   API 解密配置
     * @param requestMappingHandlerMapping 请求映射处理器
-     * @param handlerExceptionResolver 异常处理器
+     * @param handlerExceptionResolver     异常处理器
     */
    public CryptoFilter(ApiDecryptProperties properties,
                        RequestMappingHandlerMapping requestMappingHandlerMapping,
@@ -46,6 +46,15 @@ public class CryptoFilter implements Filter {
        EncryptUtils.validateRsaPrivateKey(properties.getPrivateKey());
    }

+    /**
+     * 根据接口注解与请求头执行请求解密和响应加密。
+     *
+     * @param request  原始请求
+     * @param response 原始响应
+     * @param chain    过滤器链
+     * @throws IOException      IO 异常
+     * @throws ServletException Servlet 异常
+     */
    @Override
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException {
        HttpServletRequest servletRequest = (HttpServletRequest) request;
@@ -96,6 +105,9 @@ public class CryptoFilter implements Filter {

    /**
     * 获取 ApiEncrypt 注解
+     *
+     * @param servletRequest 当前请求
+     * @return API 加密注解
     */
    private ApiEncrypt getApiEncryptAnnotation(HttpServletRequest servletRequest) {
        // 获取注解
@@ -116,6 +128,9 @@ public class CryptoFilter implements Filter {
        return null;
    }

+    /**
+     * 销毁过滤器。
+     */
    @Override
    public void destroy() {
    }
@@ -23,6 +23,9 @@ import java.nio.charset.StandardCharsets;
 */
 public class DecryptRequestBodyWrapper extends HttpServletRequestWrapper {

+    /**
+     * 请求体字节数据。
+     */
    private final byte[] body;

    /**
@@ -48,6 +51,11 @@ public class DecryptRequestBodyWrapper extends HttpServletRequestWrapper {
        body = decryptBody.getBytes(StandardCharsets.UTF_8);
    }

+    /**
+     * 基于解密后的请求体创建字符读取器。
+     *
+     * @return 字符读取器
+     */
    @Override
    public BufferedReader getReader() {
        Charset charset = Charset.forName(getCharacterEncoding());
@@ -55,46 +63,91 @@ public class DecryptRequestBodyWrapper extends HttpServletRequestWrapper {
    }


+    /**
+     * 返回解密后请求体长度。
+     *
+     * @return 请求体长度
+     */
    @Override
    public int getContentLength() {
        return body.length;
    }

+    /**
+     * 返回解密后请求体长度。
+     *
+     * @return 请求体长度
+     */
    @Override
    public long getContentLengthLong() {
        return body.length;
    }

+    /**
+     * 返回解密后的请求体类型。
+     *
+     * @return JSON 内容类型
+     */
    @Override
    public String getContentType() {
        return MediaType.APPLICATION_JSON_VALUE;
    }


+    /**
+     * 返回基于解密请求体的输入流。
+     *
+     * @return 解密请求体输入流
+     */
    @Override
    public ServletInputStream getInputStream() {
        final ByteArrayInputStream bais = new ByteArrayInputStream(body);
        return new ServletInputStream() {
+            /**
+             * 读取解密请求体下一个字节。
+             *
+             * @return 下一个字节
+             */
            @Override
            public int read() {
                return bais.read();
            }

+            /**
+             * 返回解密请求体剩余可读字节数。
+             *
+             * @return 剩余字节数
+             */
            @Override
            public int available() {
                return bais.available();
            }

+            /**
+             * 判断解密请求体是否读取完毕。
+             *
+             * @return 是否读取完毕
+             */
            @Override
            public boolean isFinished() {
                return bais.available() == 0;
            }

+            /**
+             * 判断解密请求体输入流是否可读。
+             *
+             * @return 固定为 true
+             */
            @Override
            public boolean isReady() {
                return true;
            }

+            /**
+             * 设置异步读取监听器。
+             *
+             * @param readListener 读取监听器
+             */
            @Override
            public void setReadListener(ReadListener readListener) {

@@ -6,7 +6,10 @@ import jakarta.servlet.http.HttpServletResponse;
 import jakarta.servlet.http.HttpServletResponseWrapper;
 import org.dromara.common.encrypt.utils.EncryptUtils;

-import java.io.*;
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+import java.io.OutputStreamWriter;
+import java.io.PrintWriter;
 import java.nio.charset.Charset;
 import java.nio.charset.StandardCharsets;
 import java.security.SecureRandom;
@@ -39,6 +42,11 @@ public class EncryptResponseBodyWrapper extends HttpServletResponseWrapper {
        this.charset = resolveCharset(response);
    }

+    /**
+     * 返回缓存响应内容的字符输出器。
+     *
+     * @return 字符输出器
+     */
    @Override
    public PrintWriter getWriter() {
        if (printWriter == null) {
@@ -48,6 +56,11 @@ public class EncryptResponseBodyWrapper extends HttpServletResponseWrapper {
        return printWriter;
    }

+    /**
+     * 刷新缓存的响应输出流和字符输出器。
+     *
+     * @throws IOException IO 异常
+     */
    @Override
    public void flushBuffer() throws IOException {
        if (servletOutputStream != null) {
@@ -58,11 +71,17 @@ public class EncryptResponseBodyWrapper extends HttpServletResponseWrapper {
        }
    }

+    /**
+     * 重置已缓存的响应内容。
+     */
    @Override
    public void reset() {
        byteArrayOutputStream.reset();
    }

+    /**
+     * 重置已缓存的响应缓冲区。
+     */
    @Override
    public void resetBuffer() {
        byteArrayOutputStream.reset();
@@ -122,29 +141,64 @@ public class EncryptResponseBodyWrapper extends HttpServletResponseWrapper {
        return encryptContent;
    }

+    /**
+     * 返回缓存响应内容的二进制输出流。
+     *
+     * @return 响应输出流
+     */
    @Override
    public ServletOutputStream getOutputStream() throws IOException {
        return new ServletOutputStream() {
+            /**
+             * 判断响应输出流是否可写。
+             *
+             * @return 固定为 true
+             */
            @Override
            public boolean isReady() {
                return true;
            }

+            /**
+             * 设置异步写入监听器。
+             *
+             * @param writeListener 写入监听器
+             */
            @Override
            public void setWriteListener(WriteListener writeListener) {

            }

+            /**
+             * 写入单个字节到响应缓存。
+             *
+             * @param b 待写入字节
+             * @throws IOException IO 异常
+             */
            @Override
            public void write(int b) throws IOException {
                byteArrayOutputStream.write(b);
            }

+            /**
+             * 写入字节数组到响应缓存。
+             *
+             * @param b 待写入字节数组
+             * @throws IOException IO 异常
+             */
            @Override
            public void write(byte[] b) throws IOException {
                byteArrayOutputStream.write(b);
            }

+            /**
+             * 写入字节数组片段到响应缓存。
+             *
+             * @param b 待写入字节数组
+             * @param off 起始偏移量
+             * @param len 写入长度
+             * @throws IOException IO 异常
+             */
            @Override
            public void write(byte[] b, int off, int len) throws IOException {
                byteArrayOutputStream.write(b, off, len);
@@ -152,6 +206,12 @@ public class EncryptResponseBodyWrapper extends HttpServletResponseWrapper {
        };
    }

+    /**
+     * 解析响应字符集，未设置时默认使用 UTF-8。
+     *
+     * @param response 原始响应
+     * @return 响应字符集
+     */
    private Charset resolveCharset(HttpServletResponse response) {
        String characterEncoding = response.getCharacterEncoding();
        if (characterEncoding == null) {
@@ -160,6 +220,11 @@ public class EncryptResponseBodyWrapper extends HttpServletResponseWrapper {
        return Charset.forName(characterEncoding);
    }

+    /**
+     * 生成响应内容 AES 加密密钥。
+     *
+     * @return AES 密钥
+     */
    private String generateAesPassword() {
        byte[] bytes = new byte[24];
        SECURE_RANDOM.nextBytes(bytes);
@@ -23,6 +23,13 @@ public class MybatisDecryptInterceptor implements Interceptor {

    private final EncryptedFieldProcessor encryptedFieldProcessor;

+    /**
+     * 解密 MyBatis 查询结果中的加密字段。
+     *
+     * @param invocation 拦截调用信息
+     * @return 查询结果
+     * @throws Throwable 拦截处理异常
+     */
    @Override
    public Object intercept(Invocation invocation) throws Throwable {
        // 获取执行mysql执行结果
@@ -34,11 +41,22 @@ public class MybatisDecryptInterceptor implements Interceptor {
        return result;
    }

+    /**
+     * 包装 MyBatis 目标对象。
+     *
+     * @param target 目标对象
+     * @return 包装后的对象
+     */
    @Override
    public Object plugin(Object target) {
        return Plugin.wrap(target, this);
    }

+    /**
+     * 设置插件属性。
+     *
+     * @param properties 插件属性
+     */
    @Override
    public void setProperties(Properties properties) {

@@ -25,6 +25,13 @@ public class MybatisEncryptInterceptor implements Interceptor {

    private final EncryptedFieldProcessor encryptedFieldProcessor;

+    /**
+     * 加密 MyBatis 入参中的加密字段，并在执行后恢复原始值。
+     *
+     * @param invocation 拦截调用信息
+     * @return MyBatis 执行结果
+     * @throws Throwable 拦截处理异常
+     */
    @Override
    public Object intercept(Invocation invocation) throws Throwable {
        List<EncryptedFieldProcessor.FieldSnapshot> snapshots = List.of();
@@ -44,11 +51,22 @@ public class MybatisEncryptInterceptor implements Interceptor {
        }
    }

+    /**
+     * 包装 MyBatis 目标对象。
+     *
+     * @param target 目标对象
+     * @return 包装后的对象
+     */
    @Override
    public Object plugin(Object target) {
        return Plugin.wrap(target, this);
    }

+    /**
+     * 设置插件属性。
+     *
+     * @param properties 插件属性
+     */
    @Override
    public void setProperties(Properties properties) {
    }
@@ -381,6 +381,11 @@ public class EncryptUtils {
        }
    }

+    /**
+     * 校验 RSA 密钥长度是否满足最低安全要求。
+     *
+     * @param rsaKey RSA 密钥
+     */
    private static void validateRsaKeySize(RSAKey rsaKey) {
        int keySize = rsaKey.getModulus().bitLength();
        if (keySize < MIN_RSA_KEY_SIZE) {