docs 补充项目注释

2026-06-01 11:50:59 +08:00
parent 941c0b9032
commit 107d3326b4
66 changed files with 1079 additions and 110 deletions
@@ -43,6 +43,12 @@ public class ThreadPoolConfig {
        ScheduledThreadPoolExecutor scheduledThreadPoolExecutor = new ScheduledThreadPoolExecutor(core,
            builder.build(),
            new ThreadPoolExecutor.CallerRunsPolicy()) {
+            /**
+             * 定时任务执行完成后统一打印异常。
+             *
+             * @param r 已执行的任务
+             * @param t 任务执行异常
+             */
            @Override
            protected void afterExecute(Runnable r, Throwable t) {
                super.afterExecute(r, t);
@@ -42,7 +42,12 @@ public class PageResult<T> implements Serializable {
    }

    /**
-     * 根据分页对象构建表格分页数据对象
+     * 根据列表和总数构建表格分页数据对象。
+     *
+     * @param list  列表数据
+     * @param total 总记录数
+     * @param <T>   列表数据类型
+     * @return 表格分页数据对象
     */
    public static <T> PageResult<T> build(Collection<T> list, long total) {
        PageResult<T> rspData = new PageResult<>();
@@ -52,7 +57,11 @@ public class PageResult<T> implements Serializable {
    }

    /**
-     * 根据数据列表构建表格分页数据对象
+     * 根据数据列表构建表格分页数据对象。
+     *
+     * @param list 列表数据
+     * @param <T>  列表数据类型
+     * @return 表格分页数据对象
     */
    public static <T> PageResult<T> build(Collection<T> list) {
        PageResult<T> rspData = new PageResult<>();
@@ -63,12 +72,22 @@ public class PageResult<T> implements Serializable {
    }

    /**
-     * 构建表格分页数据对象
+     * 构建空表格分页数据对象。
+     *
+     * @param <T> 列表数据类型
+     * @return 表格分页数据对象
     */
    public static <T> PageResult<T> build() {
        return new PageResult<>();
    }

+    /**
+     * 空集合兜底处理。
+     *
+     * @param list 原始集合
+     * @param <T>  集合元素类型
+     * @return 非 null 集合
+     */
    private static <T> Collection<T> emptyIfNull(Collection<T> list) {
        return list == null ? Collections.emptyList() : list;
    }
@@ -66,6 +66,9 @@ public enum BusinessStatusEnum {
     */
    private final String desc;

+    /**
+     * 业务状态枚举缓存。
+     */
    private static final Map<String, BusinessStatusEnum> STATUS_MAP = Arrays.stream(BusinessStatusEnum.values())
        .collect(Collectors.toConcurrentMap(BusinessStatusEnum::getStatus, Function.identity()));

@@ -37,5 +37,8 @@ public enum PushSourceEnum {
     */
    CLIENT("client");

+    /**
+     * 消息来源标识。
+     */
    private final String source;
 }
@@ -32,5 +32,8 @@ public enum PushTypeEnum {
     */
    CUSTOM("custom");

+    /**
+     * 消息类型标识。
+     */
    private final String type;
 }
@@ -78,6 +78,11 @@ public final class ServiceException extends RuntimeException {
        this.message = StrFormatter.format(message, args);
    }

+    /**
+     * 获取错误提示。
+     *
+     * @return 错误提示
+     */
    @Override
    public String getMessage() {
        return message;
@@ -56,6 +56,11 @@ public final class SseException extends RuntimeException {
        this.code = code;
    }

+    /**
+     * 获取错误提示。
+     *
+     * @return 错误提示
+     */
    @Override
    public String getMessage() {
        return message;
@@ -83,6 +83,11 @@ public class BaseException extends RuntimeException {
        this(null, null, null, defaultMessage);
    }

+    /**
+     * 获取国际化后的错误消息。
+     *
+     * @return 错误消息
+     */
    @Override
    public String getMessage() {
        String message = null;
@@ -14,6 +14,12 @@ public class FileException extends BaseException {
    @Serial
    private static final long serialVersionUID = 1L;

+    /**
+     * 构造文件异常。
+     *
+     * @param code 错误码
+     * @param args 错误码参数
+     */
    public FileException(String code, Object[] args) {
        super("file", code, args, null);
    }
@@ -12,6 +12,11 @@ public class FileNameLengthLimitExceededException extends FileException {
    @Serial
    private static final long serialVersionUID = 1L;

+    /**
+     * 构造文件名称超长异常。
+     *
+     * @param defaultFileNameLength 默认文件名长度限制
+     */
    public FileNameLengthLimitExceededException(int defaultFileNameLength) {
        super("upload.filename.exceed.length", new Object[]{defaultFileNameLength});
    }
@@ -12,6 +12,11 @@ public class FileSizeLimitExceededException extends FileException {
    @Serial
    private static final long serialVersionUID = 1L;

+    /**
+     * 构造文件大小超限异常。
+     *
+     * @param defaultMaxSize 默认最大文件大小
+     */
    public FileSizeLimitExceededException(long defaultMaxSize) {
        super("upload.exceed.maxSize", new Object[]{defaultMaxSize});
    }
@@ -12,6 +12,9 @@ public class CaptchaException extends UserException {
    @Serial
    private static final long serialVersionUID = 1L;

+    /**
+     * 构造验证码错误异常。
+     */
    public CaptchaException() {
        super("user.jcaptcha.error");
    }
@@ -12,6 +12,9 @@ public class CaptchaExpireException extends UserException {
    @Serial
    private static final long serialVersionUID = 1L;

+    /**
+     * 构造验证码失效异常。
+     */
    public CaptchaExpireException() {
        super("user.jcaptcha.expire");
    }
@@ -14,6 +14,12 @@ public class UserException extends BaseException {
    @Serial
    private static final long serialVersionUID = 1L;

+    /**
+     * 构造用户模块异常。
+     *
+     * @param code 错误码
+     * @param args 错误码参数
+     */
    public UserException(String code, Object... args) {
        super("user", code, args, null);
    }
@@ -18,6 +18,14 @@ import java.util.Objects;
 */
 public class YmlPropertySourceFactory extends DefaultPropertySourceFactory {

+    /**
+     * 创建配置属性源，支持将 yml/yaml 资源解析为 PropertiesPropertySource。
+     *
+     * @param name     属性源名称
+     * @param resource 配置资源
+     * @return 属性源
+     * @throws IOException 读取配置资源失败时抛出
+     */
    @Override
    public PropertySource<?> createPropertySource(@Nullable String name, EncodedResource resource) throws IOException {
        String sourceName = resource.getResource().getFilename();
@@ -25,6 +25,9 @@ public class DateUtils extends org.apache.commons.lang3.time.DateUtils {
        "yyyy/MM/dd", "yyyy/MM/dd HH:mm:ss", "yyyy/MM/dd HH:mm", "yyyy/MM",
        "yyyy.MM.dd", "yyyy.MM.dd HH:mm:ss", "yyyy.MM.dd HH:mm", "yyyy.MM"};

+    /**
+     * 工具类不允许实例化。
+     */
    @Deprecated
    private DateUtils() {
    }