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

2026-07-17 10:06:12 +00:00 · 2026-05-18 10:10:16 +08:00
parent 84afd6e6c0
commit a2300b3a29
22 changed files with 192 additions and 1 deletions
@@ -143,6 +143,9 @@ public class SpringDocConfig {
     */
    static class PlusPaths extends Paths {

+        /**
+         * 构造路径缓存标记对象。
+         */
        public PlusPaths() {
            super();
        }
@@ -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);
@@ -46,10 +46,21 @@ public class DefaultExcelListener<T> extends AnalysisEventListener<T> implements
     */
    private Boolean failFast = Boolean.TRUE;

+    /**
+     * 构造 Excel 导入监听器。
+     *
+     * @param isValidate 是否执行 Validator 校验
+     */
    public DefaultExcelListener(boolean isValidate) {
        this.isValidate = isValidate;
    }

+    /**
+     * 构造 Excel 导入监听器。
+     *
+     * @param isValidate 是否执行 Validator 校验
+     * @param failFast 发生异常时是否立即终止读取
+     */
    public DefaultExcelListener(boolean isValidate, boolean failFast) {
        this.isValidate = isValidate;
        this.failFast = failFast;
@@ -65,6 +65,11 @@ public class ExcelDownHandler implements SheetWriteHandler {
     */
    private int currentLinkedOptionsSheetIndex;

+    /**
+     * 构造 Excel 下拉选处理器。
+     *
+     * @param options 外部指定的下拉选项
+     */
    public ExcelDownHandler(List<DropDownOptions> options) {
        this.dropDownOptions = options;
        this.currentOptionsColumnIndex = 0;
@@ -40,6 +40,11 @@ public class DataWriteHandler implements SheetWriteHandler, CellWriteHandler {
    private final Map<String, Short> headColumnMap;


+    /**
+     * 构造批注与必填样式处理器。
+     *
+     * @param clazz 表头类型
+     */
    public DataWriteHandler(Class<?> clazz) {
        notationMap = getNotationMap(clazz);
        headColumnMap = getRequiredMap(clazz);
@@ -16,6 +16,12 @@ import org.springframework.context.annotation.Bean;
@EnableConfigurationProperties(MailProperties.class)
 public class MailConfig {

+    /**
+     * 创建邮件账户配置。
+     *
+     * @param mailProperties 邮件配置属性
+     * @return 邮件账户
+     */
    @Bean
    @ConditionalOnProperty(value = "mail.enabled", havingValue = "true")
    public MailAccount mailAccount(MailProperties mailProperties) {
@@ -86,6 +86,12 @@ public abstract class AbstractOssClientImpl implements OssClient {
     */
    protected ExecutorService asyncExecutor;

+    /**
+     * 构造 S3 存储客户端基础实现。
+     *
+     * @param clientId 客户端 ID
+     * @param config S3 存储客户端配置
+     */
    public AbstractOssClientImpl(String clientId, OssClientConfig config) {
        Assert.notNull(config, () -> S3StorageException.form("S3StorageClientConfig must not be null"));
        // 如果没有设置存储客户端ID，则随机生成一个
@@ -25,6 +25,12 @@ import java.util.concurrent.Executors;
 */
 public class DefaultOssClientImpl extends AbstractOssClientImpl {

+    /**
+     * 构造默认 S3 存储客户端。
+     *
+     * @param clientId 客户端 ID
+     * @param config S3 存储客户端配置
+     */
    public DefaultOssClientImpl(String clientId, OssClientConfig config) {
        super(clientId, config);
    }
@@ -33,6 +33,12 @@ public class SseEmitterSessionManager implements PushSessionManager {

    private final MessageProperties messageProperties;

+    /**
+     * 构造 SSE 会话管理器并启动心跳检测。
+     *
+     * @param scheduledExecutorService 定时任务线程池
+     * @param messageProperties 消息推送配置
+     */
    public SseEmitterSessionManager(ScheduledExecutorService scheduledExecutorService, MessageProperties messageProperties) {
        this.messageProperties = messageProperties;
        // 定时执行 SSE 心跳检测
@@ -39,6 +39,12 @@ public class RepeatSubmitAspect {

    private static final ThreadLocal<String> KEY_CACHE = new ThreadLocal<>();

+    /**
+     * 请求进入前校验是否重复提交。
+     *
+     * @param point 切点
+     * @param repeatSubmit 防重复提交注解
+     */
    @Before("@annotation(repeatSubmit)")
    public void doBefore(JoinPoint point, RepeatSubmit repeatSubmit) throws Throwable {
        // 如果注解不为0 则使用注解数值
@@ -40,6 +40,11 @@ public class RedisConfig {
    @Autowired
    private RedissonProperties redissonProperties;

+    /**
+     * 自定义 Redisson 序列化、线程与连接模式配置。
+     *
+     * @return Redisson 自动配置定制器
+     */
    @Bean
    public RedissonAutoConfigurationCustomizer redissonCustomizer() {
        return config -> {
@@ -40,6 +40,9 @@ public class RedissonProperties {
     */
    private ClusterServersConfig clusterServersConfig;

+    /**
+     * Redisson 单机服务配置。
+     */
    @Data
    @NoArgsConstructor
    public static class SingleServerConfig {
@@ -76,6 +79,9 @@ public class RedissonProperties {

    }

+    /**
+     * Redisson 集群服务配置。
+     */
    @Data
    @NoArgsConstructor
    public static class ClusterServersConfig {
@@ -87,6 +87,12 @@ public class ResourcesConfig implements WebMvcConfigurer {
        return new GlobalExceptionHandler();
    }

+    /**
+     * 注册响应增强处理器。
+     *
+     * @param jsonValueEnhancer JSON 字段增强器
+     * @return 响应增强处理器
+     */
    @Bean
    public ResponseEnhancementAdvice responseEnhancementAdvice(JsonValueEnhancer jsonValueEnhancer) {
        return new ResponseEnhancementAdvice(jsonValueEnhancer);
@@ -232,6 +232,13 @@ public class ExportExcelServiceImpl implements IExportExcelService {
         */
        private DemoCityData pData;

+        /**
+         * 构造城市演示数据。
+         *
+         * @param id 数据库 id
+         * @param pid 父级 id
+         * @param name 名称
+         */
        public DemoCityData(Integer id, Integer pid, String name) {
            this.id = id;
            this.pid = pid;
@@ -19,10 +19,22 @@ public record OnlineUserCleanEvent(Long roleId, Collection<Long> userIds) {
        }
    }

+    /**
+     * 创建按角色清理在线用户事件。
+     *
+     * @param roleId 角色 ID
+     * @return 在线用户清理事件
+     */
    public static OnlineUserCleanEvent byRole(Long roleId) {
        return new OnlineUserCleanEvent(roleId, null);
    }

+    /**
+     * 创建按用户清理在线用户事件。
+     *
+     * @param userIds 用户 ID 集合
+     * @return 在线用户清理事件
+     */
    public static OnlineUserCleanEvent byUsers(Collection<Long> userIds) {
        return new OnlineUserCleanEvent(null, userIds);
    }
@@ -15,14 +15,34 @@ public record OssConfigChangeEvent(
    boolean defaultConfig
 ) {

+    /**
+     * 创建保存 OSS 配置后的变更事件。
+     *
+     * @param configKey 当前配置 key
+     * @param oldConfigKey 变更前配置 key
+     * @param configJson 当前配置 JSON
+     * @return OSS 配置变更事件
+     */
    public static OssConfigChangeEvent save(String configKey, String oldConfigKey, String configJson) {
        return new OssConfigChangeEvent(configKey, oldConfigKey, configJson, false);
    }

+    /**
+     * 创建删除 OSS 配置后的变更事件。
+     *
+     * @param configKey 配置 key
+     * @return OSS 配置变更事件
+     */
    public static OssConfigChangeEvent remove(String configKey) {
        return new OssConfigChangeEvent(configKey, null, null, false);
    }

+    /**
+     * 创建切换默认 OSS 配置后的变更事件。
+     *
+     * @param configKey 默认配置 key
+     * @return OSS 配置变更事件
+     */
    public static OssConfigChangeEvent useDefault(String configKey) {
        return new OssConfigChangeEvent(configKey, null, null, true);
    }