docs 补充项目注释

2026-06-01 13:58:13 +08:00
parent 107d3326b4
commit e49f3b2260
94 changed files with 2328 additions and 68 deletions
@@ -85,6 +85,13 @@ public class RateLimiterAspect {
        }
    }

+    /**
+     * 组装限流缓存键。
+     *
+     * @param rateLimiter 限流注解配置
+     * @param point 切点信息
+     * @return 限流缓存键
+     */
    private String getCombineKey(RateLimiter rateLimiter, JoinPoint point) {
        String key = rateLimiter.key();
        // 判断 key 不为空 和 不是表达式
@@ -42,7 +42,7 @@ public class RepeatSubmitAspect {
    /**
     * 请求进入前校验是否重复提交。
     *
-     * @param point 切点
+     * @param point        切点
     * @param repeatSubmit 防重复提交注解
     */
    @Before("@annotation(repeatSubmit)")
@@ -111,6 +111,9 @@ public class RepeatSubmitAspect {
        }
    }

+    /**
+     * 删除当前请求写入的防重键。
+     */
    private void deleteRepeatKey() {
        String key = KEY_CACHE.get();
        if (StringUtils.isNotBlank(key)) {
@@ -120,6 +123,9 @@ public class RepeatSubmitAspect {

    /**
     * 参数拼装
+     *
+     * @param paramsArray 方法参数数组
+     * @return 拼装后的参数字符串
     */
    private String argsArrayToString(Object[] paramsArray) {
        StringJoiner params = new StringJoiner(" ");
@@ -157,7 +163,7 @@ public class RepeatSubmitAspect {
            }
        }
        return o instanceof MultipartFile || o instanceof HttpServletRequest || o instanceof HttpServletResponse
-               || o instanceof BindingResult;
+            || o instanceof BindingResult;
    }

 }
@@ -18,7 +18,7 @@ public class CaffeineCacheDecorator implements Cache {
    /**
     * 创建带 Caffeine 一级缓存的缓存装饰器。
     *
-     * @param name 缓存名称
+     * @param name     缓存名称
     * @param cache    被装饰的缓存实例
     * @param caffeine 本地一级缓存实例
     */
@@ -73,7 +73,7 @@ public class CaffeineCacheDecorator implements Cache {
    /**
     * 按指定类型获取缓存值。
     *
-     * @param key 缓存键
+     * @param key  缓存键
     * @param type 值类型
     * @return 缓存值
     */
@@ -87,7 +87,7 @@ public class CaffeineCacheDecorator implements Cache {
    /**
     * 写入缓存值，并清理本地一级缓存。
     *
-     * @param key 缓存键
+     * @param key   缓存键
     * @param value 缓存值
     */
    @Override
@@ -99,7 +99,7 @@ public class CaffeineCacheDecorator implements Cache {
    /**
     * 当键不存在时写入缓存值。
     *
-     * @param key 缓存键
+     * @param key   缓存键
     * @param value 缓存值
     * @return 原缓存值包装对象
     */
@@ -160,7 +160,7 @@ public class CaffeineCacheDecorator implements Cache {
    /**
     * 获取缓存值，不存在时通过回调加载。
     *
-     * @param key 缓存键
+     * @param key         缓存键
     * @param valueLoader 回调加载器
     * @return 缓存值
     */
@@ -171,6 +171,9 @@ public class CaffeineCacheDecorator implements Cache {
        return (T) o;
    }

+    /**
+     * 清理当前缓存命名空间下的本地一级缓存。
+     */
    private void clearLocalCache() {
        String prefix = name + ":";
        caffeine.asMap().keySet().removeIf(key -> key instanceof String cacheKey && cacheKey.startsWith(prefix));
@@ -1,12 +1,12 @@
 /**
 * Copyright (c) 2013-2021 Nikita Koksharov
- *
+ * <p>
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
- *
- *    http://www.apache.org/licenses/LICENSE-2.0
- *
+ * <p>
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * <p>
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@@ -169,6 +169,14 @@ public class PlusSpringCacheManager implements CacheManager {
        return createMapCache(cacheName, name, config, local);
    }

+    /**
+     * 解析缓存配置，支持从模板配置复制并叠加缓存名称中的扩展参数。
+     *
+     * @param cacheName 完整缓存名称
+     * @param name 基础缓存名称
+     * @param array 缓存名称拆分参数
+     * @return 缓存配置
+     */
    private CacheConfig resolveCacheConfig(String cacheName, String name, String[] array) {
        CacheConfig config = configMap.get(cacheName);
        if (config != null) {
@@ -196,6 +204,12 @@ public class PlusSpringCacheManager implements CacheManager {
        return config;
    }

+    /**
+     * 解析是否启用本地一级缓存。
+     *
+     * @param array 缓存名称拆分参数
+     * @return 本地缓存开关
+     */
    private int resolveLocal(String[] array) {
        int local = 1;
        if (array.length > 4) {
@@ -204,6 +218,12 @@ public class PlusSpringCacheManager implements CacheManager {
        return local;
    }

+    /**
+     * 复制 Redisson 缓存配置，避免修改模板配置。
+     *
+     * @param source 模板缓存配置
+     * @return 新缓存配置
+     */
    private CacheConfig copyConfig(CacheConfig source) {
        CacheConfig target = new CacheConfig();
        target.setTTL(source.getTTL());
@@ -57,6 +57,12 @@ public class CacheUtils {
        getRequiredCache(cacheNames).clear();
    }

+    /**
+     * 获取必需存在的缓存实例。
+     *
+     * @param cacheNames 缓存组名称
+     * @return 缓存实例
+     */
    private static Cache getRequiredCache(String cacheNames) {
        Cache cache = CacheManagerHolder.CACHE_MANAGER.getCache(cacheNames);
        if (cache == null) {